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:
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:
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.
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.
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
Workshop proposal tool. When an authorized personal-library capability is
available, sandbox and cloud runs use its Gateway-backed authoring surface
instead; the library and database are not mounted writable into the worker.
Use a normal host-side session or the CLI for Workshop proposal review.
