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 -> pending
revise        -> pending
apply         -> applied
reject        -> rejected
quarantine    -> quarantined
target 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 list
openclaw 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: proposal
version: "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.list
skills.proposals.inspect
skills.proposals.create
skills.proposals.update
skills.proposals.revise
skills.proposals.apply
skills.proposals.reject
skills.proposals.quarantine

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

Storage

<OPENCLAW_STATE_DIR>/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