Skill Workshop: Governed Skill Creation and Modification

Skill Workshop is the governed route OpenClaw offers for building and modifying workspace skills. Following this route, both agents and operators put together a proposal, a pending draft carrying content, target binding, scanner state, hashes, and rollback metadata, which turns into an active skill only at the moment of application.

Only workspace skills are written by Skill Workshop. Bundled, plugin, ClawHub, extra-root, managed, personal-agent, and system skills are never touched.

How it works

• Proposal first: generated content gets stored as PROPOSAL.md, not SKILL.md.
• Apply is the only live write: create, update, and revise leave active skills untouched.
• Workspace scoped: creates point at the workspace skills/ root; updates are permitted solely for writable workspace skills.
• No clobber: create errors out when the target skill already exists.
• Hash bound: update proposals attach to the current target hash and turn stale if the live skill shifts before apply.
• Scanner gated: apply re-executes the security scanner prior to writing. Only critical findings stop apply; warn-level findings stay visible but never block it.
• Recoverable: apply records rollback metadata before any live file is modified.
• Consistent surfaces: chat, CLI, and Gateway all invoke the same service.

Lifecycle

create/update -> pending
revise        -> pending
evaluate      -> pending
apply         -> applied
reject        -> rejected
quarantine    -> quarantined
target change -> stale

Revision, application, rejection, or quarantine is possible only for a pending proposal.

Lifecycle curation

Aggregate skill usage is tracked by the Gateway in the shared state database. Once per day, it checks applied skills that came from agent autocapture. Skills sitting unused beyond 30 days become stale; past 90 days they become archived and get excluded from fresh agent skill snapshots. Archived skill files stay untouched on disk. Skills made by operators, which covers proposals from the CLI or Gateway/Control UI, count as manual and never undergo curation.

Pinned skills skip lifecycle transitions. A stale skill moves back to active once it gets used and the following sweep runs. Archived skills come back only via an explicit restore:

Lifecycle transitions and restores apply to new sessions; running sessions hold onto their current skill snapshot.

openclaw skills curator status
openclaw skills curator pin <skill>
openclaw skills curator unpin <skill>
openclaw skills curator restore <skill>

Every curator command accepts --json. Status additionally reports deterministic overlap candidates purely as suggestions; it never merges skills or invokes a model.

Chat

Ask the agent for the skill you want; it invokes skill_workshop and hands back a proposal id.

Learn from recent work

Turn the current conversation or named sources into one standards-guided skill proposal with /learn:

/learn
/learn docs/runbook.md and https://example.com/guide; focus on recovery

When no request is given, /learn asks the agent to pull out the reusable workflow from the current conversation. When a request is given, the agent treats paths, URLs, pasted notes, and conversation references as sources while respecting focus, scope, and naming requirements. It collects the sources through its existing tools, then calls skill_workshop with action: "create".

The resulting proposal stays pending; /learn never applies it. Review and apply it via the normal approval flow or with openclaw skills workshop.

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 run without an extra approval prompt. Set skills.workshop.approvalPolicy to "pending" to demand operator approval before those actions.

When approval is required, the prompt names the proposal id and target skill, and displays the proposal description, support-file count, and body size. Approval requests are bounded to complete before the agent tool watchdog. If no decision lands before the prompt expires, the lifecycle action does not run: the proposal stays pending and unchanged. Decide later in the Skill Workshop UI or run openclaw skills workshop apply|reject|quarantine <proposal-id>. Agents should not retry an expired lifecycle action in a loop.

CLI

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

# Update 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

# Run installed plugin evaluators against the exact current draft
openclaw skills workshop evaluate <proposal-id>

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

Each subcommand takes --agent <id> (target workspace; defaults to cwd-inferred, then the default agent) and --json (structured output). propose-create, propose-update, and revise also take --goal <text> and --evidence <text> to record proposal context alongside --proposal. evaluate runs through the live Gateway plugin registry, snapshots the current proposal revision before dispatch, and accepts --correlation-id <id> for external orchestration.

Plugin evaluation and lifecycle hooks

Gateway plugins can extend Skill Workshop without owning proposal storage or live skill writes:

• skill_proposal_evaluate takes in a precise candidate bundle and, when an update is proposed, the full baseline skill. It returns attributed findings, metrics, and an optional pass, revise, or block decision.
• skill_proposal_changed tracks durable created, revised, evaluation_completed, applied, rejected, quarantined, and stale events.
• skill_changed monitors committed live skill created, updated, and removed events from Workshop and supported install/uninstall paths.

Explicit evaluation happens via the CLI, Control UI, Gateway skills.proposals.evaluate method, or agent skill_workshop action. Results get stored on the exact proposal revision and in the append-only proposal event ledger. Evaluator failures stay attributed results; only a completed decision: "block" blocks apply. Apply also rechecks the evaluated target tree, so any drift in live skill assets forces a fresh evaluation.

External optimization loops are supported without embedding one into the lifecycle. Controllers can consume skills.proposals.events.list, evaluate an exact revisionHash, revise with expectedRevisionHash and correlationId, then pick up from the returned event sequence. OpenClaw never schedules, auto-revises, or decides when such a loop should stop.

Proposal content

While pending, the proposal is kept 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 strips the 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 live under assets/, examples/, references/, scripts/, or templates/. Skill Workshop scans, hashes, and stores them with the proposal, then writes them beside the live SKILL.md only on apply.

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

Agent tool

The model uses skill_workshop with one required action: create | update | revise | list | inspect | evaluate | apply | reject | quarantine. Other parameters apply depending on the action:

For any skill work that is generated, agents are expected to rely on skill_workshop and refrain from directly creating or editing skill or proposal files. This guidance is advisory and enforced through prompts. At the tool-policy boundary, a hard guard is not yet feasible.

Note

skill_workshop ships as a built-in agent tool and comes with tools.profile: "coding". When a stricter policy makes it unavailable, append skill_workshop to the active tools.allow list, or fall back to tools.alsoAllow: ["skill_workshop"] if the scope's profile lacks an explicit tools.allow. Because sandboxed runs never build the host-side Skill Workshop tool, proposal review actions should be executed from a standard host-side agent session or the CLI.

Self-learning

After enough substantial work has accumulated, a background review running in isolation can turn successful procedures and corrections into Workshop proposals. See Self-learning for details. Assign skills.workshop.autonomous.mode the value propose to queue up pending proposals, or auto to route scanner-approved captures through the standard Workshop service. The Workshop tab in the Control UI indicates whether self-learning is active; the config setting lets you pick any of the three modes.

Scan past sessions

Without enabling autonomous self-learning, the Control UI can still inspect older work. Open Plugins → Workshop and click Find skill ideas. The scan starts from the newest eligible sessions and examines a limited window of substantial work. It excludes cron, heartbeat, hook, subagent, ACP, plugin-owned, and internal review sessions, along with conversations that have fewer than six model turns.

The reviewer runs on the model configured for the selected agent and receives a transcript bundle that is size-bounded and stripped of secrets. The same conservative standard as experience review applies: a concrete recovery pattern or a stable procedure that would save at least two future model or tool calls. Routine work and one-off facts should not generate a proposal.

A single scan can create or update at most three pending proposals. It cannot apply, reject, quarantine, or edit a live skill. The Workshop shows cumulative coverage, for instance 20 sessions reviewed · Jun 18, today · 2 ideas found. Choose Scan earlier work to pick up from the persisted oldest-session cursor. Once the available history is used up, the action changes to Scan new work.

Historical review stays manual even when skills.workshop.autonomous.mode is set to off. Every click triggers a model run, so provider pricing and data-handling terms apply. The cursor and coverage counts live in the shared OpenClaw state database; scan state never stores transcript content.

In propose and auto modes, OpenClaw can also run a conservative review after successful, substantial work and once the whole agent system goes idle. That isolated review can draft at most one pending proposal, which may be a new skill, a patch to an existing workspace skill, a full-body update, or a revision of a pending proposal. It never writes a live skill directly and cannot apply, reject, or quarantine a proposal. Patch proposals quote the exact live text that would change; the tool assembles the full body from the live skill. In auto mode, the orchestrating capture pipeline applies new-skill and patch results afterward through the normal scanner-gated service; full-body update proposals always remain pending for operator review.

For enablement, eligibility, privacy, cost, the proposal threshold, and troubleshooting, see Self-learning.

Approval and autonomy

{
  skills: {
    workshop: {
      autonomous: {
        mode: "auto",
      },
      allowSymlinkTargetWrites: false,
      approvalPolicy: "auto",
      maxPending: 50,
      maxSkillBytes: 40000,
    },
  },
}

In propose and auto modes, an isolated run of the selected model decides whether the completed trajectory meets the evidence-gated proposal bar. The foreground model is not asked to learn before replying. The background reviewer keeps the foreground run as proposal provenance, has no access to general agent tools, and cannot make lifecycle decisions. In auto mode, the capture pipeline applies resulting new-skill and patch proposals only after the isolated run finishes; full-body update proposals always stay pending for operator review, since the reviewer authors them without a mechanical preservation guarantee. The review starts only when the foreground runtime reports its resolved model and confirms that skill_workshop was actually available. Restrictive or unknown tool policy therefore fails closed and produces no proposal.

The complete autonomous review behavior and safety model are covered in Self-learning.

Proposal descriptions are always limited to 160 bytes, regardless of maxSkillBytes.

Gateway methods

Only requestRevision works in Gateway, with no CLI or agent-tool counterpart: rather than swapping in PROPOSAL.md directly, it relays free-text change requests to the owning agent's chat session, meant for interfaces where the agent is told to revise instead of submitting literal new content.

historyStatus and historyScan back the Control UI. historyScan takes direction: "older" | "newer"; whatever it produces is always held as a pending proposal.

Storage

<OPENCLAW_STATE_DIR>/
  state/openclaw.sqlite
  skill-workshop/proposals/<proposal-id>/
    PROPOSAL.md
    assets/
    examples/
    references/
    scripts/
    templates/

Default state directory: ~/.openclaw.

• state/openclaw.sqlite: canonical proposal records, lifecycle status, origin attribution, and apply rollback metadata.
• PROPOSAL.md: pending skill proposal.
• Support files remain beside PROPOSAL.md so operators can review the proposed skill as a normal directory.

After checking each proposal, openclaw doctor --fix pulls the prior proposals.json, proposal.json, and rollback.json metadata into SQLite and deletes the migrated JSON files. Should an agent's configured workspace shift, its earlier proposals stay listed with a previous-workspace marker rather than vanishing.

Limits

Troubleshooting

Tool-policy diagnostic

Within propose and auto modes, the default agent gets the core/doctor/skill-workshop-tool-policy check performed by openclaw doctor. When policy conceals skill_workshop, the warning identifies the first excluding config layer and the precise allow or alsoAllow adjustment needed. Older runbooks might rely on openclaw plugins inspect skill-workshop; that command now clarifies that Skill Workshop comes built in and, when applicable, prints the same policy hint.

Related

• Skills for load order, precedence, and visibility
• Self-learning for cautious post-run skill proposals
• Creating skills for hand-written SKILL.md fundamentals
• Skills config for the complete skills.workshop schema
• Skills CLI for openclaw skills commands