vilvona 1.0.0

package/docs/tools/skill-workshop.md

@@ -0,0 +1,283 @@
+---
+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 <proposal-id>
+```
+
+Revise before approval:
+
+```bash
+openclaw skills workshop revise <proposal-id> --proposal ./PROPOSAL.md
+```
+
+Close out the proposal:
+
+```bash
+openclaw skills workshop apply <proposal-id>
+openclaw skills workshop reject <proposal-id> --reason "Duplicate"
+openclaw skills workshop quarantine <proposal-id> --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.
+
+<Note>
+`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
+Skill Workshop tool, so run proposal review actions from a normal host-side
+agent session or the CLI.
+</Note>
+
+## Approval and autonomy
+
+```json5
+{
+  skills: {
+    workshop: {
+      autonomous: {
+        enabled: false,
+      },
+      allowSymlinkTargetWrites: false,
+      approvalPolicy: "pending",
+      maxPending: 50,
+      maxSkillBytes: 40000,
+    },
+  },
+}
+```
+
+- `autonomous.enabled`: allows OpenClaw to create pending proposals from durable
+  conversation signals after successful turns. Default: `false`.
+- `allowSymlinkTargetWrites`: allows apply to write through workspace skill
+  symlinks whose real target is listed in `skills.load.allowSymlinkTargets`.
+  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
+<OPENCLAW_STATE_DIR>/skill-workshop/
+  proposals.json
+  proposals/<proposal-id>/
+    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.                                                                                                                                           |
+| `untrusted symlink target`                     | Configure `skills.load.allowSymlinkTargets` and enable `skills.workshop.allowSymlinkTargetWrites` only for intentional shared skill roots.                                                                  |
+| `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`.                                                                                                                                            |
+| Agent cannot call `skill_workshop`             | Check the active tool policy and run mode. `coding` includes the tool; restrictive `tools.allow` policies must list it explicitly, and sandboxed runs must use a normal host-side agent session or the CLI. |
+
+## 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