docs: document skill workshop proposals

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)

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 <name> --agent <id>
 openclaw skills check
 openclaw skills check --agent <id>
 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 <proposal-id>
+openclaw skills workshop apply <proposal-id>
+openclaw skills workshop reject <proposal-id> --reason "Not reusable"
+openclaw skills workshop quarantine <proposal-id> --reason "Needs security review"
 ```
 
 `search`, `update`, and `verify` use ClawHub directly. `install <slug>` 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
+`<workspace>/.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)

docs/tools/creating-skills.md

@@ -94,6 +94,30 @@ For how skills are loaded and prioritized, see [Skills](/tools/skills).
   </Step>
 </Steps>
 
+## 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
+`<workspace>/.openclaw/skill-workshop/proposals/<proposal-id>/PROPOSAL.md` and
+stays inactive until an operator reviews and applies it:
+
+```bash
+openclaw skills workshop inspect <proposal-id>
+openclaw skills workshop apply <proposal-id>
+```
+
+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:

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 `<workspace>/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
+<workspace>/.openclaw/skill-workshop/
+  proposals.json
+  proposals/<proposal-id>/
+    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 <proposal-id>
+openclaw skills workshop apply <proposal-id>
+openclaw skills workshop reject <proposal-id>
+openclaw skills workshop quarantine <proposal-id>
+```
+
+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)