diff --git a/CHANGELOG.md b/CHANGELOG.md index 3891fd10c44..5537a1f7f1f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ Docs: https://docs.openclaw.ai ### Changes +- Skills: add Skill Workshop proposals with pending `PROPOSAL.md` drafts, CLI/Gateway review actions, rollback metadata, and the `skill_research` 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 56ac10b8500..f69c9ee33bd 100644 --- a/docs/cli/skills.md +++ b/docs/cli/skills.md @@ -1,5 +1,5 @@ --- -summary: "CLI reference for `openclaw skills` (search/install/update/verify/list/info/check)" +summary: "CLI reference for `openclaw skills` (search/install/update/verify/list/info/check/workshop)" read_when: - You want to see which skills are available and ready to run - You want to search ClawHub or install skills from ClawHub, Git, or local directories @@ -53,6 +53,13 @@ openclaw skills info --agent openclaw skills check openclaw skills check --agent openclaw skills check --json +openclaw skills workshop propose-create --name "qa-check" --description "QA checklist" --proposal ./PROPOSAL.md +openclaw skills workshop propose-update qa-check --proposal ./PROPOSAL.md +openclaw skills workshop list +openclaw skills workshop inspect +openclaw skills workshop apply +openclaw skills workshop reject --reason "Not reusable" +openclaw skills workshop quarantine --reason "Needs security review" ``` `search`, `update`, and `verify` use ClawHub directly. `install ` installs @@ -116,6 +123,48 @@ Notes: `--json`, that means the machine-readable payload stays on stdout for pipes and scripts. +## Skill Workshop proposals + +`openclaw skills workshop` manages pending skill proposals in the selected +workspace. Proposals are durable drafts under +`/.openclaw/skill-workshop/proposals/`; they are not active skills +until applied. + +Create a proposal from a draft markdown file: + +```bash +openclaw skills workshop propose-create \ + --name "qa-check" \ + --description "Repeatable QA checklist" \ + --proposal ./PROPOSAL.md +``` + +Update an existing workspace skill through the same pending path: + +```bash +openclaw skills workshop propose-update qa-check --proposal ./PROPOSAL.md +``` + +The supplied draft is stored as `PROPOSAL.md` with proposal-only frontmatter: + +```markdown +--- +name: qa-check +description: Repeatable QA checklist +status: proposal +version: v1 +--- +``` + +Applying a proposal writes the active `SKILL.md` into the workspace `skills/` +root, strips `status` and proposal `version` from the frontmatter, scans the +draft, writes rollback metadata, and refuses stale updates when the target skill +changed after the proposal was created. + +Agents can create pending proposals through the `skill_research` tool when they +identify reusable work, but applying, rejecting, or quarantining remains an +explicit operator action through the CLI or Gateway. + ## Related - [CLI reference](/cli) diff --git a/docs/tools/creating-skills.md b/docs/tools/creating-skills.md index ca2ba0654a4..b9e09c41374 100644 --- a/docs/tools/creating-skills.md +++ b/docs/tools/creating-skills.md @@ -94,6 +94,30 @@ For how skills are loaded and prioritized, see [Skills](/tools/skills). +## Propose before applying + +For agent-generated or research-derived procedures, use a Skill Workshop +proposal instead of writing `SKILL.md` directly: + +```bash +openclaw skills workshop propose-create \ + --name "hello-world" \ + --description "A simple skill that says hello." \ + --proposal ./PROPOSAL.md +``` + +The draft is stored under +`/.openclaw/skill-workshop/proposals//PROPOSAL.md` and +stays inactive until an operator reviews and applies it: + +```bash +openclaw skills workshop inspect +openclaw skills workshop apply +``` + +When applied, OpenClaw writes the final `SKILL.md` into the workspace `skills/` +root and removes proposal-only frontmatter such as `status: proposal`. + ## Skill metadata reference The YAML frontmatter supports these fields: diff --git a/docs/tools/skills.md b/docs/tools/skills.md index 763cb0a4f51..ec89df81c22 100644 --- a/docs/tools/skills.md +++ b/docs/tools/skills.md @@ -118,22 +118,46 @@ 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 +## Skill Workshop proposals -The optional, experimental **Skill Workshop** plugin can create or update -workspace skills from reusable procedures observed during agent work. It -is disabled by default and must be explicitly enabled via -`plugins.entries.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 writes only to `/skills`, scans generated -content, supports pending approval or automatic safe writes, quarantines -unsafe proposals, and refreshes the skill snapshot after successful -writes so new skills become available without a Gateway restart. +```text +/.openclaw/skill-workshop/ + proposals.json + proposals// + proposal.json + PROPOSAL.md + rollback.json +``` -Use it for corrections such as _"next time, verify GIF attribution"_ or -hard-won workflows such as media QA checklists. Start with pending -approval; use automatic writes only in trusted workspaces after reviewing -its proposals. Full guide: [Skill Workshop plugin](/plugins/skill-workshop). +`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` and +`version: v1`; those proposal-only fields are stripped when the proposal is +applied as an active `SKILL.md`. + +Only pending proposals can be applied. 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 apply +openclaw skills workshop reject +openclaw skills workshop quarantine +``` + +Agents can draft proposals through the `skill_research` tool when they identify +work worth reusing. The tool creates pending proposals only; it cannot apply or +delete skills. ## ClawHub (install and sync)