Proposal content, support files, and the agent tool

Plugin evaluation and lifecycle hooks

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

• skill_proposal_evaluate receives an exact candidate bundle and, for update proposals, the complete baseline skill. It returns attributed findings, metrics, and an optional pass, revise, or block decision.
• skill_proposal_changed observes durable created, revised, evaluation_completed, applied, rejected, quarantined, and stale events.
• skill_changed observes committed live skill created, updated, and removed events from Workshop and supported install/uninstall paths.

Evaluations are explicit from the CLI, Control UI, Gateway skills.proposals.evaluate method, or agent skill_workshop action. Results are stored on the exact proposal revision and in the append-only proposal event ledger. Evaluator failures remain attributed results; only a completed decision: "block" prevents apply. Apply also revalidates the evaluated target tree, so any live skill asset drift requires a fresh evaluation.

The lifecycle supports external optimization loops without embedding one. Controllers can consume skills.proposals.events.list, evaluate an exact revisionHash, revise with expectedRevisionHash and correlationId, then continue from the returned event sequence. OpenClaw does not schedule, auto-revise, or decide when such a loop should stop.

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 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.

Directory drafts must be completely readable and fit within eight path components, including the filename. Evaluator bundles require all included target content to be readable and within sixteen path components. Root .clawhub, .clawdhub, and .openclaw metadata entries are excluded; those names nested elsewhere remain included. Unreadable included directories or deeper content produce an error. Fix the reported directory or reduce its nesting, then retry. For a collection restore failure, follow the manual recovery guidance instead of restructuring the live tree.

Agent tool

For personal library operations, skill_workshop exposes list | read | create | update | share | unshare | transfer | activate | remove | rollback. The Gateway chooses the authorized namespace. When Workshop authoring is also available, target: "personal" selects the personal library. Reads return a stable skill ID and revision. Updates require skill_id and expected_revision; omit proposal_content to preserve the instructions. Use files for named support-file upserts and delete_files for explicit removals. Unmentioned support files are preserved. Large instructions are returned whole or explicitly omitted with directions to the operator workflow; binary supporting content is not injected into model context.

For Workshop proposals, the tool uses one required action: create | read | prepare_patch | patch | update | revise | list | inspect | evaluate | apply | reject | quarantine | history | restore_collection. Other Workshop parameters apply depending on the action:

read and prepare_patch return the resolved skillName. Reuse that name as skill_name in follow-up calls; a metadata skillKey can match a different skill's exact name. Update proposals and revisions preserve the existing skill's frontmatter name.

Only one prepared patch span may be active per skill. A second prepare_patch is rejected until a patch attempt consumes or invalidates the active authorization.

inspect returns proposal metadata, a bounded artifact manifest, and one complete artifact when it fits the selected model's context budget. It selects PROPOSAL.md by default. Set artifact_path to read one support file separately. When the selected artifact does not fit, the result omits its body, reports the original size, and points to smaller per-artifact reads or the unbounded operator CLI command.

Agents must use skill_workshop for generated skill work and must not create or change skill or proposal files directly during foreground authoring. Automatic background maintenance uses the rooted file-tool path described in Self-learning and approval settings instead. The foreground rule is advisory and prompt-enforced. A hard guard is not currently possible at the tool-policy seam.