openclaw/docs/tools/skill-workshop/proposals.md

Multi-channel AI gateway with extensible messaging integrations

---
summary: "Proposal file format, support-file rules, plugin evaluation, and skill_workshop parameters"
title: "Proposal content, support files, and the agent tool"
read_when:
  - You are writing PROPOSAL.md or its support files
  - You are building a plugin evaluator or lifecycle hook
  - You need the skill_workshop action and parameter reference
---

## 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:

```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 the
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 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](/tools/skill-workshop/collection-review#when-an-older-backup-cannot-be-restored-automatically)
instead of restructuring the live tree.

## Agent tool

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. Personal `list` takes only `action` and `target`;
it returns up to 20 entries and points to My skills for the complete library.
Use an entry's `skillId` as `skill_id` for `read`, not its name or slug.
Personal operations do not accept Workshop-only fields such as `query`, `limit`,
or `skill_name`, or proposal actions such as `inspect` and `prepare_patch`.
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, omit `target`. 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:

| Parameter                  | Used by                                                          | Notes                                                                 |
| -------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------- |
| `name`                     | `create`, `inspect`, `revise`                                    | Required for `create`; resolves a pending proposal by name otherwise  |
| `description`              | `create`, `update`, `revise`                                     | Max 160 bytes                                                         |
| `skill_name`               | `read`, `prepare_patch`, `patch`, `update`                       | Existing skill name or key                                            |
| `old_string`               | `prepare_patch`, `patch`                                         | Exact current text; prepare it when the complete skill cannot be read |
| `new_string`               | `patch`                                                          | Replacement for the exact current text                                |
| `proposal_content`         | `create`, `update`, `revise`                                     | Required for create/update; omit on revise to preserve the body       |
| `support_files`            | `create`, `update`, `revise`                                     | Array of `{ path, content }`                                          |
| `goal`, `evidence`         | `create`, `update`, `revise`                                     | Free-text context                                                     |
| `proposal_id`              | `inspect`, `revise`, `evaluate`, `apply`, `reject`, `quarantine` | Target proposal                                                       |
| `artifact_path`            | `inspect`                                                        | `PROPOSAL.md` or one listed support-file path                         |
| `expected_revision_hash`   | `evaluate`, `apply`, `reject`, `quarantine`                      | Rejects a stale orchestration step                                    |
| `correlation_id`           | `evaluate`, `revise`, `apply`, `reject`, `quarantine`            | External run or experiment correlation                                |
| `reason`                   | `apply`, `reject`, `quarantine`                                  | Optional                                                              |
| `query`, `status`, `limit` | `list`                                                           | Filter/paginate; `limit` max 50, default 20                           |

`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](/tools/skill-workshop/authoring#cli).

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](/tools/skill-workshop/configuration) instead.
The foreground rule is advisory and prompt-enforced. The tool-policy seam does
not enforce it.

<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
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.
</Note>