Skill Workshop

Skill Workshop is OpenClaw's governed path for creating and updating workspace skills.

Agents and operators do not write active SKILL.md files directly through this path. They create a proposal first. A proposal is a pending draft containing the proposed skill content, target binding, scanner state, hashes, support-file metadata, and rollback metadata. It becomes a live skill only when applied.

Skill Workshop writes workspace skills only. It does not mutate bundled, plugin, ClawHub, extra-root, managed, personal-agent, or system skills.

How it works

• Proposal first: generated skill content is stored as PROPOSAL.md, not SKILL.md.
• Apply is the only live write: create, update, and revise do not change active skills.
• Workspace scoped: creates target the workspace skills/ root. Updates are allowed only for writable workspace skills.
• No clobber: create fails if the target skill already exists.
• Hash bound: update proposals bind to the current target hash and become stale if the live skill changes before apply.
• Scanner gated: apply reruns scanning before writing.
• Recoverable: apply writes rollback metadata before changing live files.
• Consistent surfaces: chat, CLI, and Gateway all call the same Skill Workshop service.

Lifecycle

create/update -> pendingrevise        -> pendingapply         -> appliedreject        -> rejectedquarantine    -> quarantinedtarget change -> stale

Only pending proposals can be revised, applied, rejected, or quarantined.

Chat

Ask the agent for the skill you want. The agent calls skill_workshop and returns a proposal id.

Create:

Make a skill called morning-catchup that runs my Monday inbox routine.

Update an existing workspace skill:

Update trip-planning to also check seat maps before booking.

Iterate on a pending proposal:

Show me the morning-catchup proposal.Revise it to also flag anything marked urgent.Apply the morning-catchup proposal.

By default, agent-initiated apply, reject, and quarantine show an approval prompt before they run. Set skills.workshop.approvalPolicy to "auto" to skip the prompt for trusted environments.

CLI

Create a new skill proposal:

openclaw skills workshop propose-create \  --name morning-catchup \  --description "Daily inbox catch-up: triage, archive, surface, draft, plan" \  --proposal ./PROPOSAL.md

Create an update proposal for an existing workspace skill:

openclaw skills workshop propose-update trip-planning --proposal ./PROPOSAL.md

List and inspect:

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

Revise before approval:

openclaw skills workshop revise <proposal-id> --proposal ./PROPOSAL.md

Close out the proposal:

openclaw skills workshop apply <proposal-id>openclaw skills workshop reject <proposal-id> --reason "Duplicate"openclaw skills workshop quarantine <proposal-id> --reason "Needs security review"

Proposal content

While pending, the proposal is stored as PROPOSAL.md with proposal-only frontmatter:

---name: "morning-catchup"description: "Daily inbox catch-up: triage, archive, surface, draft, plan"status: proposalversion: "v1"date: "2026-05-30T00:00:00.000Z"---

On apply, Skill Workshop writes the active SKILL.md and removes proposal-only fields: status, proposal version, and proposal date.

Support files

Use --proposal-dir when the proposed skill needs files beside PROPOSAL.md:

openclaw skills workshop propose-create \  --name weekly-update \  --description "Friday wrap-up: stats, highlights, next week's top three" \  --proposal-dir ./weekly-update-proposal

The directory must contain PROPOSAL.md. Support files must be under:

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

Skill Workshop scans, hashes, and stores support files with the proposal. They are written beside the live SKILL.md only on apply.

Rejected support-file paths include absolute paths, hidden path segments, path traversal, overlapping paths, executable files from proposal directories, non-UTF-8 text, null bytes, and files outside the standard support folders.

Agent tool

The model uses skill_workshop:

action: create | update | revise | list | inspect | apply | reject | quarantine

Agents must use skill_workshop for generated skill work. They must not create or change proposal files through write, edit, exec, shell commands, or direct filesystem operations.

Approval and autonomy

{  skills: {    workshop: {      autonomous: {        enabled: false,      },      approvalPolicy: "pending",      maxPending: 50,      maxSkillBytes: 40000,    },  },}

• autonomous.enabled: allows OpenClaw to create pending proposals from durable conversation signals after successful turns. Default: false.
• approvalPolicy: "pending": requires an approval prompt before agent-initiated apply, reject, or quarantine.
• approvalPolicy: "auto": skips that approval prompt. The agent must still call the action.
• maxPending: caps pending and quarantined proposals per workspace.
• maxSkillBytes: caps proposal body size. Default: 40000.

Proposal descriptions are always capped at 160 bytes.

Gateway methods

skills.proposals.listskills.proposals.inspectskills.proposals.createskills.proposals.updateskills.proposals.reviseskills.proposals.applyskills.proposals.rejectskills.proposals.quarantine

Read-only methods require operator.read. Mutating methods require operator.admin.

Storage

&lt;OPENCLAW_STATE_DIR&gt;/skill-workshop/  proposals.json  proposals/<proposal-id>/    proposal.json    PROPOSAL.md    rollback.json    assets/    examples/    references/    scripts/    templates/

Default state directory: ~/.openclaw.

• proposal.json: canonical proposal record.
• proposals.json: fast listing index, rebuildable from proposal folders.
• PROPOSAL.md: pending skill proposal.
• rollback.json: recovery metadata written before apply changes live files.

Limits

• Description: 160 bytes.
• Proposal body: skills.workshop.maxSkillBytes (default 40,000).
• Support files: 64 per proposal.
• Support file size: 256 KB each, 2 MB total.
• Pending and quarantined proposals: skills.workshop.maxPending per workspace (default 50).

Troubleshooting

Related

• Skills for load order, precedence, and visibility
• Creating skills for hand-written SKILL.md basics
• Skills config for the full skills.workshop schema
• Skills CLI for openclaw skills commands