Skill workshop plugin

Skill Workshop is experimental. It is disabled by default, its capture heuristics and reviewer prompts may change between releases, and automatic writes should be used only in trusted workspaces after reviewing pending-mode output first.

Skill Workshop is procedural memory for workspace skills. It lets an agent turn reusable workflows, user corrections, hard-won fixes, and recurring pitfalls into

files under:

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

This is different from long-term memory:

• Memory stores facts, preferences, entities, and past context.
• Skills store reusable procedures the agent should follow on future tasks.
• Skill Workshop is the bridge from a useful turn to a durable workspace skill, with safety checks and optional approval.

Skill Workshop is useful when the agent learns a procedure such as:

• how to validate externally sourced animated GIF assets
• how to replace screenshot assets and verify dimensions
• how to run a repo-specific QA scenario
• how to debug a recurring provider failure
• how to repair a stale local workflow note

It is not intended for:

• facts like “the user likes blue”
• broad autobiographical memory
• raw transcript archiving
• secrets, credentials, or hidden prompt text
• one-off instructions that will not repeat

Default state

The bundled plugin is experimental and disabled by default unless it is explicitly enabled in

.

The plugin manifest does not set

. The default inside the plugin config schema applies only after the plugin entry has already been selected and loaded.

Experimental means:

• the plugin is supported enough for opt-in testing and dogfooding
• proposal storage, reviewer thresholds, and capture heuristics can evolve
• pending approval is the recommended starting mode
• auto apply is for trusted personal/workspace setups, not shared or hostile input-heavy environments

Enable

Minimal safe config:

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

With this config:

• the
  text

  Copy

  skill_workshop
  tool is available
• explicit reusable corrections are queued as pending proposals
• threshold-based reviewer passes can propose skill updates
• no skill file is written until a pending proposal is applied

Use automatic writes only in trusted workspaces:

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

still uses the same scanner and quarantine path. It does not apply proposals with critical findings.

Configuration

Recommended profiles:

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

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

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

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

Capture paths

Skill Workshop has three capture paths.

Tool suggestions

The model can call

directly when it sees a reusable procedure or when the user asks it to save/update a skill.

This is the most explicit path and works even with

.

Heuristic capture

When

is enabled and is or , the plugin scans successful turns for explicit user correction phrases:

• text

  Copy

  next time
• text

  Copy

  from now on
• text

  Copy

  remember to
• text

  Copy

  make sure to
• text

  Copy

  always ... use/check/verify/record/save/prefer
• text

  Copy

  prefer ... when/for/instead/use
• text

  Copy

  when asked

The heuristic creates a proposal from the latest matching user instruction. It uses topic hints to choose skill names for common workflows:

• animated GIF tasks ->
  text

  Copy

  animated-gif-workflow
• screenshot or asset tasks ->
  text

  Copy

  screenshot-asset-workflow
• QA or scenario tasks ->
  text

  Copy

  qa-scenario-workflow
• GitHub PR tasks ->
  text

  Copy

  github-pr-workflow
• fallback ->
  text

  Copy

  learned-workflows

Heuristic capture is intentionally narrow. It is for clear corrections and repeatable process notes, not for general transcript summarization.

LLM reviewer

When

is enabled and is or , the plugin runs a compact embedded reviewer after thresholds are reached.

The reviewer receives:

• the recent transcript text, capped to the last 12,000 characters
• up to 12 existing workspace skills
• up to 2,000 characters from each existing skill
• JSON-only instructions

The reviewer has no tools:

• text

  Copy

  disableTools: true
• text

  Copy

  toolsAllow: []
• text

  Copy

  disableMessageTool: true

The reviewer returns either

or one proposal. The field is , , or — prefer / when a relevant skill already exists; use only when no existing skill fits.

Example

:

json
Copy
{
  "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."
}

adds + . swaps for in the named skill.

Proposal lifecycle

Every generated update becomes a proposal with:

• text

  Copy

  id
• text

  Copy

  createdAt
• text

  Copy

  updatedAt
• text

  Copy

  workspaceDir
• optional
  text

  Copy

  agentId
• optional
  text

  Copy

  sessionId
• text

  Copy

  skillName
• text

  Copy

  title
• text

  Copy

  reason
• text

  Copy

  source
  :
  text

  Copy

  tool
  ,
  text

  Copy

  agent_end
  , or
  text

  Copy

  reviewer
• text

  Copy

  status
• text

  Copy

  change
• optional
  text

  Copy

  scanFindings
• optional
  text

  Copy

  quarantineReason

Proposal statuses:

• text

  Copy

  pending
  - waiting for approval
• text

  Copy

  applied
  - written to
  text

  Copy

  <workspace>/skills
• text

  Copy

  rejected
  - rejected by operator/model
• text

  Copy

  quarantined
  - blocked by critical scanner findings

State is stored per workspace under the Gateway state directory:

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

Pending and quarantined proposals are deduplicated by skill name and change payload. The store keeps the newest pending/quarantined proposals up to

.

Tool reference

The plugin registers one agent tool:

text
Copy
skill_workshop

text

Copy

status

Count proposals by state for the active workspace.

json
Copy
{ "action": "status" }

Result shape:

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

text

Copy

list_pending

List pending proposals.

json
Copy
{ "action": "list_pending" }

To list another status:

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

Valid

values:

• text

  Copy

  pending
• text

  Copy

  applied
• text

  Copy

  rejected
• text

  Copy

  quarantined

text

Copy

list_quarantine

List quarantined proposals.

json
Copy
{ "action": "list_quarantine" }

Use this when automatic capture appears to do nothing and the logs mention

.

text

Copy

inspect

Fetch a proposal by id.

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

text

Copy

suggest

Create a proposal. With

(default), this queues instead of writing.

json
Copy
{
  "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."
}

Force a safe write (apply: true)

Force pending under auto policy (apply: false)

Append to a named section

Replace exact text

text

Copy

apply

Apply a pending proposal.

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

refuses quarantined proposals:

text
Copy
quarantined proposal cannot be applied

text

Copy

reject

Mark a proposal rejected.

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

text

Copy

write_support_file

Write a supporting file inside an existing or proposed skill directory.

Allowed top-level support directories:

• text

  Copy

  references/
• text

  Copy

  templates/
• text

  Copy

  scripts/
• text

  Copy

  assets/

Example:

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

Support files are workspace-scoped, path-checked, byte-limited by

, scanned, and written atomically.

Skill writes

Skill Workshop writes only under:

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

Skill names are normalized:

• lowercased
• non
  text

  Copy

  [a-z0-9_-]
  runs become
  text

  Copy

  -
• leading/trailing non-alphanumerics are removed
• max length is 80 characters
• final name must match
  text

  Copy

  [a-z0-9][a-z0-9_-]{1,79}

For

:

• if the skill does not exist, Skill Workshop writes a new
  text

  Copy

  SKILL.md
• if it already exists, Skill Workshop appends the body to
  text

  Copy

  ## Workflow

For

:

• if the skill exists, Skill Workshop appends to the requested section
• if it does not exist, Skill Workshop creates a minimal skill then appends

For

:

• the skill must already exist
• text

  Copy

  oldText
  must be present exactly
• only the first exact match is replaced

All writes are atomic and refresh the in-memory skills snapshot immediately, so the new or updated skill can become visible without a Gateway restart.

Safety model

Skill Workshop has a safety scanner on generated

content and support files.

Critical findings quarantine proposals:

Warn findings are retained but do not block by themselves:

Quarantined proposals:

• keep
  text

  Copy

  scanFindings
• keep
  text

  Copy

  quarantineReason
• appear in
  text

  Copy

  list_quarantine
• cannot be applied through
  text

  Copy

  apply

To recover from a quarantined proposal, create a new safe proposal with the unsafe content removed. Do not edit the store JSON by hand.

Prompt guidance

When enabled, Skill Workshop injects a short prompt section that tells the agent to use

for durable procedural memory.

The guidance emphasizes:

• procedures, not facts/preferences
• user corrections
• non-obvious successful procedures
• recurring pitfalls
• stale/thin/wrong skill repair through append/replace
• saving reusable procedure after long tool loops or hard fixes
• short imperative skill text
• no transcript dumps

The write mode text changes with

:

• pending mode: queue suggestions; apply only after explicit approval
• auto mode: apply safe workspace-skill updates when clearly reusable

Costs and runtime behavior

Heuristic capture does not call a model.

LLM review uses an embedded run on the active/default agent model. It is threshold-based so it does not run on every turn by default.

The reviewer:

• uses the same configured provider/model context when available
• falls back to runtime agent defaults
• has
  text

  Copy

  reviewTimeoutMs
• uses lightweight bootstrap context
• has no tools
• writes nothing directly
• can only emit a proposal that goes through the normal scanner and approval/quarantine path

If the reviewer fails, times out, or returns invalid JSON, the plugin logs a warning/debug message and skips that review pass.

Operating patterns

Use Skill Workshop when the user says:

• “next time, do X”
• “from now on, prefer Y”
• “make sure to verify Z”
• “save this as a workflow”
• “this took a while; remember the process”
• “update the local skill for this”

Good skill text:

markdown
Copy
## 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.

Poor skill text:

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

Reasons the poor version should not be saved:

• transcript-shaped
• not imperative
• includes noisy one-off details
• does not tell the next agent what to do

Debugging

Check whether the plugin is loaded:

bash
Copy
openclaw plugins list --enabled

Check proposal counts from an agent/tool context:

json
Copy
{ "action": "status" }

Inspect pending proposals:

json
Copy
{ "action": "list_pending" }

Inspect quarantined proposals:

json
Copy
{ "action": "list_quarantine" }

Common symptoms:

Relevant logs:

• text

  Copy

  skill-workshop: queued <skill>
• text

  Copy

  skill-workshop: applied <skill>
• text

  Copy

  skill-workshop: quarantined <skill>
• text

  Copy

  skill-workshop: heuristic capture skipped: ...
• text

  Copy

  skill-workshop: reviewer skipped: ...
• text

  Copy

  skill-workshop: reviewer found no update

QA scenarios

Repo-backed QA scenarios:

• text

  Copy

  qa/scenarios/plugins/skill-workshop-animated-gif-autocreate.md
• text

  Copy

  qa/scenarios/plugins/skill-workshop-pending-approval.md
• text

  Copy

  qa/scenarios/plugins/skill-workshop-reviewer-autonomous.md

Run the deterministic coverage:

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

Run reviewer coverage:

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

The reviewer scenario is intentionally separate because it enables

and exercises the embedded reviewer pass.

When not to enable auto apply

Avoid

when:

• the workspace contains sensitive procedures
• the agent is working on untrusted input
• skills are shared across a broad team
• you are still tuning prompts or scanner rules
• the model frequently handles hostile web/email content

Use pending mode first. Switch to auto mode only after reviewing the kind of skills the agent proposes in that workspace.

Related docs

• Skills
• Plugins
• Testing