스킬 워크숍 Plugin

스킬 워크숍은 실험적 기능입니다. 기본적으로 비활성화되어 있으며, 캡처 휴리스틱과 리뷰어 프롬프트는 릴리스마다 변경될 수 있고, 자동 쓰기는 먼저 pending 모드 출력을 검토한 뒤 신뢰할 수 있는 워크스페이스에서만 사용해야 합니다.

스킬 워크숍은 워크스페이스 스킬을 위한 절차적 메모리입니다. 에이전트가 재사용 가능한 워크플로, 사용자 수정 사항, 어렵게 얻은 수정 방법, 반복되는 주의점을 다음 위치의 SKILL.md 파일로 전환할 수 있게 해줍니다.

<workspace>/skills/<skill-name>/SKILL.md

이는 장기 메모리와 다릅니다.

• 메모리는 사실, 선호도, 엔터티, 과거 컨텍스트를 저장합니다.
• Skills는 에이전트가 향후 작업에서 따라야 할 재사용 가능한 절차를 저장합니다.
• 스킬 워크숍은 유용한 턴을 안전성 검사와 선택적 승인을 거쳐 지속 가능한 워크스페이스 스킬로 이어주는 다리입니다.

스킬 워크숍은 에이전트가 다음과 같은 절차를 학습할 때 유용합니다.

• 외부에서 가져온 애니메이션 GIF 에셋을 검증하는 방법
• 스크린샷 에셋을 교체하고 치수를 확인하는 방법
• 저장소별 QA 시나리오를 실행하는 방법
• 반복되는 제공자 실패를 디버그하는 방법
• 오래된 로컬 워크플로 노트를 복구하는 방법

다음 용도로는 의도되지 않았습니다.

• "사용자가 파란색을 좋아한다" 같은 사실
• 광범위한 자전적 메모리
• 원본 트랜스크립트 보관
• 비밀, 자격 증명, 숨겨진 프롬프트 텍스트
• 반복되지 않을 일회성 지침

기본 상태

번들 Plugin은 실험적 기능이며, plugins.entries.skill-workshop에서 명시적으로 활성화하지 않는 한 기본적으로 비활성화되어 있습니다.

Plugin 매니페스트는 enabledByDefault: true를 설정하지 않습니다. Plugin 구성 스키마 내부의 enabled: true 기본값은 Plugin 항목이 이미 선택되고 로드된 뒤에만 적용됩니다.

실험적이라는 의미는 다음과 같습니다.

• Plugin이 옵트인 테스트와 내부 실사용에 충분한 수준으로 지원됩니다.
• 제안 저장 방식, 리뷰어 임계값, 캡처 휴리스틱은 발전할 수 있습니다.
• 보류 승인이 권장 시작 모드입니다.
• 자동 적용은 신뢰할 수 있는 개인/워크스페이스 설정용이며, 공유되었거나 적대적 입력이 많은 환경용이 아닙니다.

활성화

최소한의 안전한 구성:

{  plugins: {    entries: {      "skill-workshop": {        enabled: true,        config: {          autoCapture: true,          approvalPolicy: "pending",          reviewMode: "hybrid",        },      },    },  },}

이 구성에서는 다음이 적용됩니다.

• skill_workshop 도구를 사용할 수 있습니다.
• 명시적인 재사용 가능 수정 사항이 보류 제안으로 대기열에 추가됩니다.
• 임계값 기반 리뷰어 패스가 스킬 업데이트를 제안할 수 있습니다.
• 보류 제안이 적용되기 전까지는 어떤 스킬 파일도 작성되지 않습니다.

자동 쓰기는 신뢰할 수 있는 워크스페이스에서만 사용하세요.

{  plugins: {    entries: {      "skill-workshop": {        enabled: true,        config: {          autoCapture: true,          approvalPolicy: "auto",          reviewMode: "hybrid",        },      },    },  },}

approvalPolicy: "auto"도 동일한 스캐너와 격리 경로를 사용합니다. 치명적 발견 사항이 있는 제안은 적용하지 않습니다.

구성

권장 프로필:

// Conservative: explicit tool use only, no automatic capture.{  autoCapture: false,  approvalPolicy: "pending",  reviewMode: "off",}

// Review-first: capture automatically, but require approval.{  autoCapture: true,  approvalPolicy: "pending",  reviewMode: "hybrid",}

// Trusted automation: write safe proposals immediately.{  autoCapture: true,  approvalPolicy: "auto",  reviewMode: "hybrid",}

// Low-cost: no reviewer LLM call, only explicit correction phrases.{  autoCapture: true,  approvalPolicy: "pending",  reviewMode: "heuristic",}

캡처 경로

스킬 워크숍에는 세 가지 캡처 경로가 있습니다.

도구 제안

모델은 재사용 가능한 절차를 발견하거나 사용자가 스킬 저장/업데이트를 요청할 때 skill_workshop을 직접 호출할 수 있습니다.

이는 가장 명시적인 경로이며 autoCapture: false에서도 작동합니다.

휴리스틱 캡처

autoCapture가 활성화되고 reviewMode가 heuristic 또는 hybrid이면 Plugin은 성공한 턴에서 명시적인 사용자 수정 문구를 스캔합니다.

• next time
• from now on
• remember to
• make sure to
• always ... use/check/verify/record/save/prefer
• prefer ... when/for/instead/use
• when asked

휴리스틱은 가장 최근에 일치한 사용자 지침으로부터 제안을 생성합니다. 일반적인 워크플로의 스킬 이름을 선택하기 위해 주제 힌트를 사용합니다.

• 애니메이션 GIF 작업 -> animated-gif-workflow
• 스크린샷 또는 에셋 작업 -> screenshot-asset-workflow
• QA 또는 시나리오 작업 -> qa-scenario-workflow
• GitHub PR 작업 -> github-pr-workflow
• 대체값 -> learned-workflows

휴리스틱 캡처는 의도적으로 좁게 설계되어 있습니다. 일반적인 트랜스크립트 요약이 아니라 명확한 수정 사항과 반복 가능한 프로세스 노트를 위한 것입니다.

LLM 리뷰어

autoCapture가 활성화되고 reviewMode가 llm 또는 hybrid이면 Plugin은 임계값에 도달한 뒤 간결한 내장 리뷰어를 실행합니다.

리뷰어는 다음을 받습니다.

• 최근 트랜스크립트 텍스트, 마지막 12,000자로 제한
• 기존 워크스페이스 스킬 최대 12개
• 각 기존 스킬에서 최대 2,000자
• JSON 전용 지침

리뷰어에는 도구가 없습니다.

• disableTools: true
• toolsAllow: []
• disableMessageTool: true

리뷰어는 { "action": "none" } 또는 하나의 제안을 반환합니다. action 필드는 create, append, replace입니다. 관련 스킬이 이미 있으면 append/replace를 선호하고, 기존 스킬이 맞지 않을 때만 create를 사용하세요.

create 예시:

{  "action": "create",  "skillName": "media-asset-qa",  "title": "Media Asset QA",  "reason": "Reusable animated media acceptance workflow",  "description": "Validate externally sourced animated media before product use.",  "body": "## Workflow\n\n- Verify true animation.\n- Record attribution.\n- Store a local approved copy.\n- Verify in product UI before final reply."}

append는 section + body를 추가합니다. replace는 이름이 지정된 스킬에서 oldText를 newText로 교체합니다.

제안 수명 주기

생성된 모든 업데이트는 다음을 포함하는 제안이 됩니다.

• id
• createdAt
• updatedAt
• workspaceDir
• 선택적 agentId
• 선택적 sessionId
• skillName
• title
• reason
• source: tool, agent_end, 또는 reviewer
• status
• change
• 선택적 scanFindings
• 선택적 quarantineReason

제안 상태:

• pending - 승인 대기 중
• applied - <workspace>/skills에 작성됨
• rejected - 운영자/모델이 거부함
• quarantined - 치명적 스캐너 발견 사항으로 차단됨

상태는 Gateway 상태 디렉터리 아래에 워크스페이스별로 저장됩니다:

<stateDir>/skill-workshop/<workspace-hash>.json

대기 중 및 격리된 제안은 스킬 이름과 변경 페이로드를 기준으로 중복 제거됩니다. 저장소는 최신 대기 중/격리 제안을 maxPending까지 유지합니다.

도구 참조

Plugin은 하나의 에이전트 도구를 등록합니다:

skill_workshop

status

활성 워크스페이스의 제안을 상태별로 집계합니다.

{ "action": "status" }

결과 형태:

{  "workspaceDir": "/path/to/workspace",  "pending": 1,  "quarantined": 0,  "applied": 3,  "rejected": 0}

list_pending

대기 중인 제안을 나열합니다.

{ "action": "list_pending" }

다른 상태를 나열하려면:

{ "action": "list_pending", "status": "applied" }

유효한 status 값:

• pending
• applied
• rejected
• quarantined

list_quarantine

격리된 제안을 나열합니다.

{ "action": "list_quarantine" }

자동 캡처가 아무 작업도 하지 않는 것처럼 보이고 로그에 skill-workshop: quarantined <skill>이 언급될 때 사용하세요.

inspect

ID로 제안을 가져옵니다.

{  "action": "inspect",  "id": "proposal-id"}

suggest

제안을 생성합니다. approvalPolicy: "pending"(기본값)을 사용하면 쓰는 대신 대기열에 추가합니다.

{  "action": "suggest",  "skillName": "animated-gif-workflow",  "title": "Animated GIF Workflow",  "reason": "User established reusable GIF validation rules.",  "description": "Validate animated GIF assets before using them.",  "body": "## Workflow\n\n- Verify the URL resolves to image/gif.\n- Confirm it has multiple frames.\n- Record attribution and license.\n- Avoid hotlinking when a local asset is needed."}

{"action": "suggest","apply": true,"skillName": "animated-gif-workflow","description": "Validate animated GIF assets before using them.","body": "## Workflow\n\n- Verify true animation.\n- Record attribution."}

{"action": "suggest","apply": false,"skillName": "screenshot-asset-workflow","description": "Screenshot replacement workflow.","body": "## Workflow\n\n- Verify dimensions.\n- Optimize the PNG.\n- Run the relevant gate."}

{"action": "suggest","skillName": "qa-scenario-workflow","section": "Workflow","description": "QA scenario workflow.","body": "- For media QA, verify generated assets render and pass final assertions."}

{"action": "suggest","skillName": "github-pr-workflow","oldText": "- Check the PR.","newText": "- Check unresolved review threads, CI status, linked issues, and changed files before deciding."}

apply

대기 중인 제안을 적용합니다.

approvalPolicy: "pending"에서는 이 작업이 워크스페이스 스킬에 쓰기 전에 운영자 승인을 요청합니다.

{  "action": "apply",  "id": "proposal-id"}

apply는 격리된 제안을 거부합니다:

quarantined proposal cannot be applied

reject

제안을 거부됨으로 표시합니다.

{  "action": "reject",  "id": "proposal-id"}

write_support_file

기존 또는 제안된 스킬 디렉터리 안에 지원 파일을 씁니다.

허용되는 최상위 지원 디렉터리:

• references/
• templates/
• scripts/
• assets/

예:

{  "action": "write_support_file",  "skillName": "release-workflow",  "relativePath": "references/checklist.md",  "body": "# Release Checklist\n\n- Run release docs.\n- Verify changelog.\n"}

지원 파일은 작업 영역 범위로 제한되고, 경로가 검사되며, maxSkillBytes로 바이트 수가 제한되고, 스캔된 뒤 원자적으로 작성됩니다.

Skill 쓰기

Skill Workshop은 다음 위치 아래에만 씁니다.

<workspace>/skills/<normalized-skill-name>/

Skill 이름은 정규화됩니다.

• 소문자로 변환
• [a-z0-9_-]가 아닌 연속 문자는 -가 됨
• 앞뒤의 영숫자가 아닌 문자는 제거
• 최대 길이는 80자
• 최종 이름은 [a-z0-9][a-z0-9_-]{1,79}와 일치해야 함

create의 경우:

• Skill이 없으면 Skill Workshop이 새 SKILL.md를 작성합니다
• 이미 있으면 Skill Workshop이 본문을 ## Workflow에 추가합니다

append의 경우:

• Skill이 있으면 Skill Workshop이 요청한 섹션에 추가합니다
• 없으면 Skill Workshop이 최소 Skill을 만든 다음 추가합니다

replace의 경우:

• Skill이 이미 있어야 합니다
• oldText가 정확히 존재해야 합니다
• 첫 번째 정확한 일치 항목만 교체됩니다

모든 쓰기는 원자적이며 메모리 내 Skills 스냅샷을 즉시 새로 고치므로, Gateway를 다시 시작하지 않아도 새 Skill이나 업데이트된 Skill이 표시될 수 있습니다.

안전 모델

Skill Workshop에는 생성된 SKILL.md 콘텐츠와 지원 파일에 대한 안전 스캐너가 있습니다.

중요 발견 사항은 제안을 격리합니다.

경고 발견 사항은 유지되지만 그 자체로 차단하지는 않습니다.

격리된 제안:

• scanFindings를 유지합니다
• quarantineReason을 유지합니다
• list_quarantine에 표시됩니다
• apply를 통해 적용할 수 없습니다

격리된 제안에서 복구하려면 안전하지 않은 콘텐츠를 제거한 새 안전 제안을 만드세요. 저장소 JSON을 직접 편집하지 마세요.

프롬프트 지침

활성화되면 Skill Workshop은 에이전트에게 지속적인 절차 메모리를 위해 skill_workshop을 사용하라고 알려 주는 짧은 프롬프트 섹션을 주입합니다.

지침은 다음을 강조합니다.

• 사실/선호가 아니라 절차
• 사용자 수정 사항
• 명확하지 않지만 성공한 절차
• 반복되는 함정
• 추가/교체를 통한 오래되었거나 얕거나 잘못된 Skill 복구
• 긴 도구 루프나 어려운 수정 후 재사용 가능한 절차 저장
• 짧은 명령형 Skill 텍스트
• transcript 덤프 금지

쓰기 모드 텍스트는 approvalPolicy에 따라 바뀝니다.

• 보류 모드: 제안을 대기열에 넣고, 명시적 승인 후 apply 사용
• 자동 모드: apply: false로 대신 대기열에 넣지 않는 한 안전한 작업 영역 Skill 업데이트 적용

비용 및 런타임 동작

휴리스틱 캡처는 모델을 호출하지 않습니다.

LLM 검토는 활성/기본 에이전트 모델에서 임베디드 실행을 사용합니다. 임계값 기반이므로 기본적으로 모든 턴마다 실행되지는 않습니다.

검토자는:

• 사용할 수 있을 때 동일하게 구성된 제공자/모델 컨텍스트를 사용합니다
• 런타임 에이전트 기본값으로 대체됩니다
• reviewTimeoutMs를 가집니다
• 경량 부트스트랩 컨텍스트를 사용합니다
• 도구가 없습니다
• 직접 아무것도 쓰지 않습니다
• 일반 스캐너와 승인/격리 경로를 거치는 제안만 내보낼 수 있습니다

검토자가 실패하거나, 시간이 초과되거나, 잘못된 JSON을 반환하면 Plugin은 경고/디버그 메시지를 기록하고 해당 검토 패스를 건너뜁니다.

운영 패턴

사용자가 다음과 같이 말하면 Skill Workshop을 사용하세요.

• "다음에는 X를 해"
• "이제부터는 Y를 선호해"
• "Z를 확인하도록 해"
• "이것을 워크플로로 저장해"
• "이건 시간이 좀 걸렸으니, 과정을 기억해"
• "이것에 대한 로컬 Skill을 업데이트해"

좋은 Skill 텍스트:

## Workflow - Verify the GIF URL resolves to `image/gif`.- Confirm the file has multiple frames.- Record source URL, license, and attribution.- Store a local copy when the asset will ship with the product.- Verify the local asset renders in the target UI before final reply.

나쁜 Skill 텍스트:

The user asked about a GIF and I searched two websites. Then one was blocked byCloudflare. The final answer said to check attribution.

나쁜 버전을 저장해서는 안 되는 이유:

• transcript 형태임
• 명령형이 아님
• 시끄러운 일회성 세부 정보 포함
• 다음 에이전트에게 무엇을 해야 하는지 알려 주지 않음

디버깅

Plugin이 로드되었는지 확인:

openclaw plugins list --enabled

에이전트/도구 컨텍스트에서 제안 수 확인:

{ "action": "status" }

보류 중인 제안 검사:

{ "action": "list_pending" }

격리된 제안 검사:

{ "action": "list_quarantine" }

일반적인 증상:

관련 로그:

• skill-workshop: queued <skill>
• skill-workshop: applied <skill>
• skill-workshop: quarantined <skill>
• skill-workshop: heuristic capture skipped: ...
• skill-workshop: reviewer skipped: ...
• skill-workshop: reviewer found no update

QA 시나리오

저장소 기반 QA 시나리오:

• qa/scenarios/plugins/skill-workshop-animated-gif-autocreate.md
• qa/scenarios/plugins/skill-workshop-pending-approval.md
• qa/scenarios/plugins/skill-workshop-reviewer-autonomous.md

결정적 커버리지 실행:

pnpm openclaw qa suite \  --scenario skill-workshop-animated-gif-autocreate \  --scenario skill-workshop-pending-approval \  --concurrency 1

검토자 커버리지 실행:

pnpm openclaw qa suite \  --scenario skill-workshop-reviewer-autonomous \  --concurrency 1

검토자 시나리오는 reviewMode: "llm"을 활성화하고 임베디드 검토자 패스를 실행하기 때문에 의도적으로 분리되어 있습니다.

자동 적용을 활성화하지 말아야 할 때

다음 경우 approvalPolicy: "auto"를 피하세요.

• 작업 영역에 민감한 절차가 포함되어 있음
• 에이전트가 신뢰할 수 없는 입력을 처리 중임
• Skills가 광범위한 팀에서 공유됨
• 아직 프롬프트나 스캐너 규칙을 조정 중임
• 모델이 적대적인 웹/이메일 콘텐츠를 자주 처리함

먼저 보류 모드를 사용하세요. 해당 작업 영역에서 에이전트가 제안하는 Skills 종류를 검토한 후에만 자동 모드로 전환하세요.

관련 문서

• Skills
• Plugins
• 테스트