OpenClaw Skill Workshop Guide: Turn Agent Work Into Reusable Skills

OpenClaw is most valuable when it stops repeating the same discovery. If you have already shown it how to prepare a weekly report, triage an inbox, or validate a release, that working procedure can become a skill for future sessions.

The risky part is turning a one-off success into a permanent instruction. A useful answer can be ignored. A bad skill can influence every later run. Skill Workshop is OpenClaw's reviewable path for converting agent work into reusable behavior. It keeps a generated skill as a proposal first, lets you inspect and scan it, and writes the active skill only when you apply it.

This guide covers the current Workshop workflow, including the CLI lifecycle, support files, autonomous learning modes, and the checks to make before a proposal becomes part of an agent's skill set.

What Skill Workshop Does

An OpenClaw skill is a directory containing a SKILL.md file. Its frontmatter describes the skill, and its Markdown body tells the agent how and when to use it. Supporting material can include templates, scripts, examples, and references.

Skill Workshop adds governance around generated skills. Instead of having an agent write directly into an active SKILL.md, it stores a pending bundle as PROPOSAL.md. The proposal records the draft instructions, target binding, scanner state, hashes, and recovery metadata needed to review it safely.

The key rule is simple:

A proposal is not an active skill. Applying the proposal is the live write.

Workshop proposals are scoped to the active agent's Workshop directory, normally under the state directory at ~/.openclaw/agents/<agent-id>/agent/workshop-skills. That separation prevents a generated proposal from silently replacing a bundled, plugin, workspace, or externally installed skill.

If you want to hand-author a skill from scratch, use the normal skills/ workflow described in the OpenClaw custom skills guide. Use Workshop when you want an agent-drafted result or a review checkpoint before generated instructions become active.

Skill Workshop vs. Direct Skill Authoring

Direct authoring is appropriate when you know exactly what the skill should do and are comfortable editing its owning directory. You create a folder, add SKILL.md, run openclaw skills list, and start a new session or restart the Gateway if necessary.

Workshop is better when the procedure came from recent agent work or when another person should review it first. The proposal path gives you:

• A pending state: generated content stays in PROPOSAL.md until applied.
• A review surface: inspect the complete proposal and any support files before activation.
• Hash binding: an update proposal becomes stale if the target skill changes before you apply it.
• Security scanning: apply validates and scans the candidate again.
• Recovery metadata: apply records rollback information before touching the live skill.
• Consistent interfaces: chat, the Control UI, the Gateway, and the CLI use the same Workshop service.

This is not a replacement for operating-system permissions or sandboxing. Skill instructions can guide an agent, but they do not make a shell-capable process trustworthy. Treat third-party skills as untrusted code and combine skill review with appropriate tool policies and sandbox controls.

The Proposal Lifecycle

A proposal moves through a small state machine:

create → pending → evaluate → apply
                    ↘ reject
                    ↘ quarantine

A pending proposal can also be revised. An update can become stale if the target skill changes after the proposal was created. Do not force a stale proposal through; revise it against the current target so the new instructions are reviewed in the context that will actually be applied.

The usual review sequence is:

1. Create or ask OpenClaw to create a proposal.
2. Inspect its description, PROPOSAL.md, and support-file manifest.
3. Evaluate the exact draft when your installation has Workshop evaluators.
4. Revise it if the procedure is too broad, incomplete, or duplicated.
5. Apply it only after the content and scanner state are acceptable.
6. Reject or quarantine proposals that should not become active.

Applied, rejected, quarantined, and stale records remain inspectable. That history is useful when you need to understand why a skill exists or why a proposed change was not activated.

Create a Proposal with the CLI

Start with a small, concrete procedure. For example, create PROPOSAL.md with proposal-only frontmatter:

---
name: weekly-release-notes
description: Build a Friday release summary from verified project changes.
status: proposal
version: v1
date: 2026-09-07T00:00:00.000Z
---

# Weekly release notes

1. Read the approved change list for the current release.
2. Separate shipped changes from follow-up work.
3. Link each claim to its source issue or commit.
4. Draft the summary using the included template.
5. Stop and ask before publishing externally.

Submit it as a new Workshop proposal:

openclaw skills workshop propose-create \
  --name weekly-release-notes \
  --description "Build a Friday release summary from verified project changes." \
  --proposal ./PROPOSAL.md

For an update to an existing Workshop-generated skill, use propose-update and provide the new proposal file:

openclaw skills workshop propose-update weekly-release-notes \
  --proposal ./PROPOSAL.md

You can add context with --goal and --evidence. That context should explain the reusable outcome and the observed work that supports it, not contain secrets or unrelated conversation transcript.

Review, Evaluate, and Apply Safely

List proposals for the current agent, then inspect the one you intend to change:

openclaw skills workshop list
openclaw skills workshop inspect <proposal-id>

Inspection should answer four questions:

1. Does the skill describe a repeatable procedure rather than a one-time answer?
2. Are its triggers and boundaries clear enough that it will not run on unrelated requests?
3. Does it contain secrets, private data, destructive defaults, or instructions that bypass approval?
4. Are its examples and support files necessary, readable, and limited to the stated job?

Run an evaluator when available:

openclaw skills workshop evaluate <proposal-id>

Evaluation is attached to the exact proposal revision. If you revise the proposal, evaluate the new revision rather than relying on an older result. A completed evaluation can recommend pass, revise, or block; apply also performs its own validation and scanner gate.

When the proposal is ready, apply it:

openclaw skills workshop apply <proposal-id>

If the procedure is not reusable, reject it explicitly:

openclaw skills workshop reject <proposal-id> --reason "One-time request, not a durable workflow"

Quarantine is the safer choice when the idea may be useful but needs security review:

openclaw skills workshop quarantine <proposal-id> --reason "Review network and shell access before activation"

After apply, start a new session before testing the skill. OpenClaw refreshes skill snapshots for new sessions; a session that was already running keeps the instructions it loaded earlier.

Add Support Files Without Expanding Scope

A good skill often needs more than its main instructions. A release skill may need a Markdown template. A debugging skill may need sanitized example logs. A deployment skill may need a validation script.

Use a proposal directory when you need these files:

weekly-release-notes-proposal/
├── PROPOSAL.md
├── examples/
│   └── sample-change-list.md
└── templates/
    └── release-summary.md

Submit the directory instead of only the file:

openclaw skills workshop propose-create \
  --name weekly-release-notes \
  --description "Build a Friday release summary from verified project changes." \
  --proposal-dir ./weekly-release-notes-proposal

Support files must be under assets/, examples/, references/, scripts/, or templates/. Workshop rejects absolute paths, traversal such as ../, hidden path segments, overlapping paths, executable files, non-UTF-8 text, and content outside those folders. Those restrictions keep a proposal's write surface inside the skill and make its bundle easier to audit.

Do not put API keys, tokens, copied customer records, or private transcripts in examples. Use placeholders and sanitized data. Also keep helper scripts narrow: a support script should not quietly broaden the skill into arbitrary filesystem or network access.

Choose an Autonomous Learning Mode

OpenClaw's self-learning and Workshop settings determine how background learning is captured:

Set the mode explicitly when you want a stricter review policy:

openclaw config set skills.workshop.autonomous.mode propose

Experience review is deliberately selective. It looks for a durable recovery technique, a repeated workflow, a meaningful correction, or a preflight that would prevent future work. It should not turn a routine successful answer, personal preference, transient outage, or secret into a skill.

The foreground turn does not wait for the review. An eligible review requires substantial foreground work and a quiet period, and it uses the source session's permissions. In propose mode the result remains pending. In auto mode, normal file maintenance can edit the Workshop directory directly, so use propose when every learned change needs a human checkpoint.

Troubleshooting

The proposal is not listed

Check that you are using the same agent and state directory that created it. Every Workshop command accepts --agent <id>, and OPENCLAW_STATE_DIR changes where proposals are stored. A proposal created for another agent will not appear in the current agent's list.

Apply says the target is stale

The live skill changed after the proposal was created. Inspect the current skill, regenerate the proposal against that version, and submit a revision. Do not overwrite the target manually just to make the hash match.

A proposal is still pending in auto mode

Automatic apply is a single attempt, not a retry loop. Inspect the proposal and its scanner findings. A write failure leaves it pending; a critical scanner result moves it to quarantine. Fix the issue or revise the content, then apply manually.

No self-learning capture appears

Confirm that the mode is auto or propose, the turn was eligible foreground work, it reached at least ten model iterations without a provider or prompt error, and the Gateway stayed idle through the quiet period. OpenClaw may also abstain because the evidence does not show a durable procedure. That is an expected result, not necessarily a failure.

Doctor says Workshop is hidden

Run openclaw doctor. In auto and propose modes, Doctor checks whether the active tool policy permits skill_workshop. Follow its exact tools.allow or tools.alsoAllow suggestion, or set autonomous mode to off if you do not want Workshop automation.

The applied skill does not affect the current chat

Start a new session or refresh the Gateway. The current run uses its original skill snapshot by design.

A Practical Review Checklist

Before applying any OpenClaw Skill Workshop proposal, verify:

• The name is lowercase, hyphenated, and matches the intended skill.
• The description states a real trigger and outcome in under 160 bytes.
• The instructions describe a repeatable workflow with a clear stop condition.
• Tools, shell commands, network destinations, and writes are narrowly scoped.
• Examples contain no credentials or private user data.
• Support files use only approved directories and contain no executable payloads.
• The proposal does not duplicate an existing skill.
• The evaluator has run against the current revision when available.
• Scanner findings are understood, and critical findings are resolved.
• A new session will be used to test the applied behavior.

FAQ

Does Skill Workshop automatically activate every learned procedure?

No. In propose mode, learned procedures remain pending until you review and apply them. In auto mode, background maintenance can update the Workshop directory directly, but it still operates within the agent's permissions and can make incorrect edits. Review installed skills regularly when using auto.

Is PROPOSAL.md the same as SKILL.md?

No. PROPOSAL.md is the pending, proposal-only form. On apply, Workshop writes the active SKILL.md and removes proposal-only fields such as status, proposal version, and proposal date.

Can I use Workshop for a hand-written skill?

You can, but direct authoring is simpler when you already know the final content. Workshop is most valuable when generated work needs a reviewable proposal, scanner gate, hash binding, and apply history.

Does a skill's allowlist protect the host?

No. Skill allowlists control what the agent sees and loads; they are not a host shell authorization boundary. Use tool policy, sandboxing, OS permissions, and server-side credentials for isolation.

Where can I learn more?

Start with the official Skill Workshop documentation, then review Skills and loading rules, Skills config, and Self-learning. For the broader product context, see OpenClaw's Skill Workshop announcement.

Sources

• OpenClaw Docs: Skill Workshop
• OpenClaw Docs: Skills
• OpenClaw Docs: Skills config
• OpenClaw Docs: Self-learning
• OpenClaw Docs: Creating skills
• OpenClaw Blog: Skill Workshop announcement