From 5a8bb1a7d2c4b621236299a249d2f8561c33151c Mon Sep 17 00:00:00 2001 From: Shakker Date: Sun, 31 May 2026 09:04:37 +0100 Subject: [PATCH] docs: add Skill Workshop guide --- CHANGELOG.md | 9 +- docs/cli/skills.md | 64 ++------ docs/docs.json | 1 + docs/tools/creating-skills.md | 24 +-- docs/tools/index.md | 21 +-- docs/tools/skill-workshop.md | 267 ++++++++++++++++++++++++++++++++++ docs/tools/skills-config.md | 12 +- docs/tools/skills.md | 65 +-------- 8 files changed, 322 insertions(+), 141 deletions(-) create mode 100644 docs/tools/skill-workshop.md diff --git a/CHANGELOG.md b/CHANGELOG.md index dad57a6a4f93..3b2fa6fa75fe 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,10 +15,11 @@ Docs: https://docs.openclaw.ai ### Changes -- Skills: let the `skill_research` agent tool apply, reject, and quarantine explicit Skill Workshop proposals through the guarded proposal lifecycle. Thanks @shakkernerd. -- Skills: let Skill Workshop proposals carry approved support files under standard skill folders, with scanner, hash, and rollback safeguards. Thanks @shakkernerd. -- Skills: let pending Skill Workshop proposals be revised in place with versioned, dated proposal frontmatter before approval. Thanks @shakkernerd. -- Skills: add Skill Workshop proposals with pending `PROPOSAL.md` drafts, CLI/Gateway review actions, rollback metadata, and the `skill_research` agent tool. Thanks @shakkernerd. +- Docs: add a dedicated Skill Workshop guide covering governed skill creation, reviewable proposals, CLI, Gateway, agent tool behavior, approval policy, support files, and recovery. Thanks @shakkernerd. +- Skills: let the `skill_workshop` agent tool apply, reject, and quarantine explicit proposals through the guarded review flow. Thanks @shakkernerd. +- Skills: let proposals carry approved support files under standard skill folders, with scanner, hash, and rollback safeguards. Thanks @shakkernerd. +- Skills: let pending proposals be revised in place with versioned, dated proposal frontmatter before approval. Thanks @shakkernerd. +- Skills: add Skill Workshop with pending proposals, CLI/Gateway review actions, rollback metadata, and the `skill_workshop` agent tool. Thanks @shakkernerd. - Plugins: externalize Tokenjuice as the official `@openclaw/tokenjuice` plugin with npm and ClawHub publish metadata. - Plugins: externalize the GitHub Copilot agent runtime as the official `@openclaw/copilot` plugin with npm and ClawHub publish metadata. - iOS: add hosted push relay defaults, realtime Talk playback, and a guarded WebSocket ping path for more reliable mobile sessions. (#88096, #88105, #88231) diff --git a/docs/cli/skills.md b/docs/cli/skills.md index 146f545b7ae9..7e9e233c36a5 100644 --- a/docs/cli/skills.md +++ b/docs/cli/skills.md @@ -16,6 +16,7 @@ directories, verify ClawHub skills, and update ClawHub-tracked installs. Related: - Skills system: [Skills](/tools/skills) +- Skill Workshop: [Skill Workshop](/tools/skill-workshop) - Skills config: [Skills config](/tools/skills-config) - ClawHub installs: [ClawHub](/clawhub/cli) @@ -124,76 +125,31 @@ Notes: `--json`, that means the machine-readable payload stays on stdout for pipes and scripts. -## Skill Workshop proposals +## Skill Workshop `openclaw skills workshop` manages pending skill proposals in the selected -workspace. Proposals are durable OpenClaw state under -`/skill-workshop/proposals/`; they are not active skills -until applied. The default state directory is `~/.openclaw`. Proposal bodies -honor `skills.workshop.maxSkillBytes`, and proposal descriptions are capped at -160 bytes because they can appear in discovery and listing output. - -Create a proposal from a draft markdown file: +workspace. Proposals are not active skills until applied. For proposal storage, +support-file safeguards, Gateway methods, and approval policy, see +[Skill Workshop](/tools/skill-workshop). ```bash openclaw skills workshop propose-create \ --name "qa-check" \ --description "Repeatable QA checklist" \ --proposal ./PROPOSAL.md -``` - -Or create a proposal from a full draft skill directory: - -```bash openclaw skills workshop propose-create \ --name "qa-check" \ --description "Repeatable QA checklist" \ --proposal-dir ./qa-check-proposal -``` - -Update an existing workspace skill through the same pending path: - -```bash openclaw skills workshop propose-update qa-check --proposal ./PROPOSAL.md -``` - -Revise a pending proposal before approval: - -```bash +openclaw skills workshop list +openclaw skills workshop inspect openclaw skills workshop revise --proposal ./PROPOSAL.md +openclaw skills workshop apply +openclaw skills workshop reject --reason "Duplicate" +openclaw skills workshop quarantine --reason "Needs security review" ``` -The supplied draft is stored as `PROPOSAL.md` with proposal-only frontmatter: - -```markdown ---- -name: qa-check -description: Repeatable QA checklist -status: proposal -version: v1 -date: "2026-05-30T00:00:00.000Z" ---- -``` - -Applying a proposal writes the active `SKILL.md` into the workspace `skills/` -root, strips `status`, proposal `version`, and proposal `date` from the -frontmatter, scans the draft, writes rollback metadata, and refuses stale -updates when the target skill changed after the proposal was created. - -When `--proposal-dir` is used, the directory must contain `PROPOSAL.md`. -Support files can be included under `assets/`, `examples/`, `references/`, -`scripts/`, or `templates/`. OpenClaw stores support files with the proposal, -scans them, verifies their hashes before apply, and writes them beside the -active `SKILL.md` only after the proposal is applied. - -Agents can create, revise, list, and inspect pending proposals through the -`skill_workshop` tool when the user asks for reusable work to be captured. -Autonomous proposal capture from durable conversation signals is off by -default and is enabled with `skills.workshop.autonomous.enabled`. If the user -explicitly asks to approve/use/apply, reject, or quarantine a specific -proposal, `skill_workshop` can also perform that proposal lifecycle action -through the same Skill Workshop safeguards. - ## Related - [CLI reference](/cli) diff --git a/docs/docs.json b/docs/docs.json index 803027d9b2c4..55e480fc54ff 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1255,6 +1255,7 @@ "group": "Skills", "pages": [ "tools/skills", + "tools/skill-workshop", "tools/creating-skills", "tools/skills-config", "tools/slash-commands", diff --git a/docs/tools/creating-skills.md b/docs/tools/creating-skills.md index c5ae7eac67c4..873bc0247af5 100644 --- a/docs/tools/creating-skills.md +++ b/docs/tools/creating-skills.md @@ -9,7 +9,9 @@ read_when: Skills teach the agent how and when to use tools. Each skill is a directory containing a `SKILL.md` file with YAML frontmatter and markdown instructions. -For how skills are loaded and prioritized, see [Skills](/tools/skills). +For how skills are loaded and prioritized, see [Skills](/tools/skills). For +agent-generated or reviewed skill changes, see +[Skill Workshop](/tools/skill-workshop). ## Create your first skill @@ -94,10 +96,11 @@ For how skills are loaded and prioritized, see [Skills](/tools/skills). -## Propose before applying +## Use Skill Workshop for generated skills -For agent-generated procedures, use a Skill Workshop proposal instead of -writing `SKILL.md` directly: +For agent-generated procedures, use Skill Workshop instead of writing `SKILL.md` +directly. Skill Workshop creates a pending proposal first; it becomes an active +skill only after review and apply: ```bash openclaw skills workshop propose-create \ @@ -115,12 +118,9 @@ openclaw skills workshop propose-create \ --proposal-dir ./hello-world-proposal ``` -The draft is stored under -`/skill-workshop/proposals//PROPOSAL.md` and -stays inactive until an operator reviews and applies it. The default state -directory is `~/.openclaw`. Proposal directories must contain `PROPOSAL.md`. -Support files can be included under `assets/`, `examples/`, `references/`, -`scripts/`, or `templates/`; OpenClaw stores and scans them with the proposal: +The proposal stays inactive until an operator reviews and applies it. +Proposal directories must contain `PROPOSAL.md`. Support files can be included +under `assets/`, `examples/`, `references/`, `scripts/`, or `templates/`: ```bash openclaw skills workshop inspect @@ -133,6 +133,9 @@ root, writes approved support files beside it, and removes proposal-only frontmatter such as `status: proposal`, proposal `version`, and proposal `date`. +Full proposal storage, review, Gateway, and approval-policy details are in +[Skill Workshop](/tools/skill-workshop). + ## Skill metadata reference The YAML frontmatter supports these fields: @@ -192,6 +195,7 @@ Each skills root can contain direct skill folders such as ## Related - [Skills reference](/tools/skills) — loading, precedence, and gating rules +- [Skill Workshop](/tools/skill-workshop) — governed creation for generated or reviewed skill changes - [Skills config](/tools/skills-config) — `skills.*` config schema - [ClawHub](/clawhub) — public skill registry - [Building Plugins](/plugins/building-plugins) — plugins can ship skills diff --git a/docs/tools/index.md b/docs/tools/index.md index 83504a6388c7..457952d24d33 100644 --- a/docs/tools/index.md +++ b/docs/tools/index.md @@ -21,15 +21,15 @@ group membership, provider restrictions, and configuration fields, use For most agents, start with the built-in tool categories, then adjust policy only when the agent should see fewer tools or needs explicit host access. -| If you need to... | Use this first | Then read | -| ------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------- | -| Let an agent act with existing capabilities | [Built-in tools](#built-in-tool-categories) | [Tool categories](#built-in-tool-categories) | -| Control what an agent can call | [Tool policy](#configure-access-and-approvals) | [Tools and custom providers](/gateway/config-tools) | -| Teach an agent a workflow | [Skills](#choose-tools-skills-or-plugins) | [Skills](/tools/skills) and [Creating skills](/tools/creating-skills) | -| Add a new integration or runtime surface | [Plugins](#extend-capabilities) | [Plugins](/tools/plugin) and [Build plugins](/plugins/building-plugins) | -| Run work later or in the background | [Automation](/automation) | [Automation overview](/automation) | -| Coordinate multiple agents or harnesses | [Sub-agents](/tools/subagents) | [ACP agents](/tools/acp-agents) and [Agent send](/tools/agent-send) | -| Search a large OpenClaw tool catalog | [Tool Search](/tools/tool-search) | [Tool Search](/tools/tool-search) | +| If you need to... | Use this first | Then read | +| ------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | +| Let an agent act with existing capabilities | [Built-in tools](#built-in-tool-categories) | [Tool categories](#built-in-tool-categories) | +| Control what an agent can call | [Tool policy](#configure-access-and-approvals) | [Tools and custom providers](/gateway/config-tools) | +| Teach an agent a workflow | [Skills](#choose-tools-skills-or-plugins) | [Skills](/tools/skills), [Creating skills](/tools/creating-skills), and [Skill Workshop](/tools/skill-workshop) | +| Add a new integration or runtime surface | [Plugins](#extend-capabilities) | [Plugins](/tools/plugin) and [Build plugins](/plugins/building-plugins) | +| Run work later or in the background | [Automation](/automation) | [Automation overview](/automation) | +| Coordinate multiple agents or harnesses | [Sub-agents](/tools/subagents) | [ACP agents](/tools/acp-agents) and [Agent send](/tools/agent-send) | +| Search a large OpenClaw tool catalog | [Tool Search](/tools/tool-search) | [Tool Search](/tools/tool-search) | ## Choose tools, skills, or plugins @@ -55,7 +55,7 @@ only when the agent should see fewer tools or needs explicit host access. Skills can live in a workspace, shared skill directory, managed OpenClaw skill root, or plugin package. - [Skills](/tools/skills) | [Creating skills](/tools/creating-skills) | [Skills config](/tools/skills-config) + [Skills](/tools/skills) | [Skill Workshop](/tools/skill-workshop) | [Creating skills](/tools/creating-skills) | [Skills config](/tools/skills-config) @@ -172,4 +172,5 @@ current turn: - [Plugins](/tools/plugin) for plugin installation and management - [Plugin SDK](/plugins/sdk-overview) for plugin author reference - [Skills](/tools/skills) for skill load order, gating, and config +- [Skill Workshop](/tools/skill-workshop) for generated and reviewed skill creation - [Tool Search](/tools/tool-search) for compact OpenClaw tool catalog discovery diff --git a/docs/tools/skill-workshop.md b/docs/tools/skill-workshop.md new file mode 100644 index 000000000000..69712ab8a88c --- /dev/null +++ b/docs/tools/skill-workshop.md @@ -0,0 +1,267 @@ +--- +summary: "Create and update workspace skills through Skill Workshop review" +read_when: + - You want the agent to create or update a skill from chat + - You need to review, apply, reject, or quarantine a generated skill draft + - You are configuring Skill Workshop approval, autonomy, storage, or limits +title: "Skill Workshop" +sidebarTitle: "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 + +```text +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: + +```text +Make a skill called morning-catchup that runs my Monday inbox routine. +``` + +Update an existing workspace skill: + +```text +Update trip-planning to also check seat maps before booking. +``` + +Iterate on a pending proposal: + +```text +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: + +```bash +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: + +```bash +openclaw skills workshop propose-update trip-planning --proposal ./PROPOSAL.md +``` + +List and inspect: + +```bash +openclaw skills workshop list +openclaw skills workshop inspect +``` + +Revise before approval: + +```bash +openclaw skills workshop revise --proposal ./PROPOSAL.md +``` + +Close out the proposal: + +```bash +openclaw skills workshop apply +openclaw skills workshop reject --reason "Duplicate" +openclaw skills workshop quarantine --reason "Needs security review" +``` + +## Proposal content + +While pending, the proposal is stored as `PROPOSAL.md` with proposal-only +frontmatter: + +```markdown +--- +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`: + +```bash +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`: + +```text +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 + +```json5 +{ + 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 + +```text +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 + +```text +/skill-workshop/ + proposals.json + proposals// + 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. | +| `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`. | + +## Related + +- [Skills](/tools/skills) for load order, precedence, and visibility +- [Creating skills](/tools/creating-skills) for hand-written `SKILL.md` + basics +- [Skills config](/tools/skills-config) for the full `skills.workshop` schema +- [Skills CLI](/cli/skills) for `openclaw skills` commands diff --git a/docs/tools/skills-config.md b/docs/tools/skills-config.md index ec16dd66dbfa..4805f67e4db0 100644 --- a/docs/tools/skills-config.md +++ b/docs/tools/skills-config.md @@ -8,7 +8,9 @@ title: "Skills config" Most skills loader/install configuration lives under `skills` in `~/.openclaw/openclaw.json`. Agent-specific skill visibility lives under -`agents.defaults.skills` and `agents.list[].skills`. +`agents.defaults.skills` and `agents.list[].skills`. Skill Workshop behavior is +configured under `skills.workshop`; see +[Skill Workshop](/tools/skill-workshop) for the full creation and review flow. ```json5 { @@ -118,10 +120,10 @@ Rules: clients to install private zip archives staged through `skills.upload.*` (default: false). This only enables the uploaded-archive path; normal ClawHub installs do not require it. -- `workshop.autonomous.enabled`: allow agents to create pending Skill Workshop - proposals from durable conversation signals after successful turns (default: - false). User-prompted skill creation still goes through Skill Workshop. -- `workshop.approvalPolicy`: proposal lifecycle policy. `pending` requires +- `workshop.autonomous.enabled`: allow agents to create pending proposals from + durable conversation signals after successful turns (default: false). + User-prompted skill creation still goes through Skill Workshop. +- `workshop.approvalPolicy`: Skill Workshop review policy. `pending` requires approval before agent-initiated apply/reject/quarantine actions; `auto` allows those actions without approval. - `workshop.maxPending`: maximum pending/quarantined proposals retained per diff --git a/docs/tools/skills.md b/docs/tools/skills.md index 2ad4a6a86cfb..f9ba121e7f26 100644 --- a/docs/tools/skills.md +++ b/docs/tools/skills.md @@ -118,66 +118,15 @@ workspace skill overrides them. You can gate them via See [Plugins](/tools/plugin) for discovery/config and [Tools](/tools) for the tool surface those skills teach. -## Skill Workshop proposals +## Skill Workshop -Skill Workshop proposals are durable drafts for creating or updating workspace -skills without silently mutating active `SKILL.md` files. OpenClaw stores them -under: +[Skill Workshop](/tools/skill-workshop) is the governed path for +agent-generated or reviewed skill creation and improvement. It turns reusable +work into a pending proposal, scans and hashes the proposal bundle, supports +review and revision, and writes the final `SKILL.md` only after apply. -```text -/skill-workshop/ - proposals.json - proposals// - proposal.json - PROPOSAL.md - references/ - scripts/ - rollback.json -``` - -The default state directory is `~/.openclaw`. - -`proposal.json` is the canonical proposal record. `proposals.json` is the fast -listing manifest and can be rebuilt from proposal folders when missing or stale. -`PROPOSAL.md` marks draft content explicitly with `status: proposal`, -`version: v1`, and `date`; those proposal-only fields are stripped when the -proposal is applied as an active `SKILL.md`. - -Proposal bodies honor `skills.workshop.maxSkillBytes`, and proposal -descriptions are capped at 160 bytes because they can appear in discovery and -listing output. - -Proposal folders can also carry support files under `assets/`, `examples/`, -`references/`, `scripts/`, or `templates/`. OpenClaw records support file -metadata in `proposal.json`, stores the file contents beside `PROPOSAL.md`, -scans them with the proposal, and verifies their hashes before apply. Approved -support files are written into the active skill directory beside `SKILL.md`. - -Only pending proposals can be revised or applied. Revision keeps the same -proposal id, increments the proposal version, refreshes the proposal date, -reruns scanner metadata, and preserves existing support files unless a new -support-file list is supplied. Apply writes to the selected workspace `skills/` -root, runs the skill scanner, writes rollback metadata, refuses to overwrite an -existing create target, and marks update proposals stale when the target skill -changed since proposal creation. Reject and quarantine update only proposal -metadata; they do not touch active skills. - -Use the CLI for operator review: - -```bash -openclaw skills workshop list -openclaw skills workshop inspect -openclaw skills workshop revise --proposal ./PROPOSAL.md -openclaw skills workshop apply -openclaw skills workshop reject -openclaw skills workshop quarantine -``` - -Agents can draft proposals through the `skill_workshop` tool when they identify -work worth reusing and can revise pending proposals during review. When the -user explicitly asks to approve/use/apply, reject, or quarantine a specific -proposal, the tool can perform that lifecycle action through Skill Workshop -instead of shell or direct filesystem changes. +Use it when an agent or operator wants to capture reusable work without +silently mutating active workspace skills. ## ClawHub (install and sync)