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.

Note

skill_workshop is a built-in agent tool and is included in tools.profile: "coding". If a stricter policy hides it, add skill_workshop to the active tools.allow list, or use tools.alsoAllow: ["skill_workshop"] when the scope uses a profile without an explicit tools.allow. Sandboxed runs do not construct the host-side Skill Workshop tool, so run proposal review actions from a normal host-side agent session or the CLI.

Approval and autonomy

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

• autonomous.enabled: allows OpenClaw to create pending proposals from durable conversation signals after successful turns. Default: false.
• allowSymlinkTargetWrites: allows apply to write through workspace skill symlinks whose real target is listed in skills.load.allowSymlinkTargets. 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

Problem	Resolution
Skill proposal description is too large	Shorten description to 160 bytes or less.
Skill proposal content is too large	Shorten the proposal body or raise skills.workshop.maxSkillBytes.
Target skill changed after proposal creation	Revise the proposal against the current target, or create a new proposal.
Proposal scan failed	Inspect scanner findings, then revise or quarantine the proposal.
untrusted symlink target	Configure skills.load.allowSymlinkTargets and enable skills.workshop.allowSymlinkTargetWrites only for intentional shared skill roots.
Support file paths must be under one of...	Move support files under assets/, examples/, references/, scripts/, or templates/.
Proposal does not show in list	Check the selected --agent workspace and OPENCLAW_STATE_DIR.
Agent cannot call skill_workshop	Check the active tool policy and run mode. coding includes the tool; restrictive tools.allow policies must list it explicitly, and sandboxed runs must use a normal host-side agent session or the CLI.

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