feat: add OpenProse plugin skills

docs/plugin.md

@@ -61,6 +61,7 @@ Plugins can register:
 - CLI commands
 - Background services
 - Optional config validation
+- **Skills** (by listing `skills` directories in the plugin manifest)
 
 Plugins run **in‑process** with the Gateway, so treat them as trusted code.
 Tool authoring guide: [Plugin agent tools](/plugins/agent-tools).

docs/plugins/manifest.md

@@ -34,6 +34,7 @@ Optional keys:
 - `kind` (string): plugin kind (example: `"memory"`).
 - `channels` (array): channel ids registered by this plugin (example: `["matrix"]`).
 - `providers` (array): provider ids registered by this plugin.
+- `skills` (array): skill directories to load (relative to the plugin root).
 - `name` (string): display name for the plugin.
 - `description` (string): short plugin summary.
 - `uiHints` (object): config field labels/placeholders/sensitive flags for UI rendering.

docs/prose.md

@@ -0,0 +1,120 @@
+---
+summary: "OpenProse: .prose workflows, slash commands, state, and telemetry in Clawdbot"
+read_when:
+  - You want to run or write .prose workflows
+  - You want to enable the OpenProse plugin
+  - You need to understand telemetry or state storage
+---
+# OpenProse
+
+OpenProse is a portable, markdown-first workflow format for orchestrating AI sessions. In Clawdbot it ships as a plugin that installs an OpenProse skill pack plus a `/prose` slash command. Programs live in `.prose` files and can spawn multiple sub-agents with explicit control flow.
+
+## Install + enable
+
+Bundled plugins are disabled by default. Enable OpenProse:
+
+```bash
+clawdbot plugins enable open-prose
+```
+
+If you're using a local checkout instead of bundled:
+
+```bash
+clawdbot plugins install ./extensions/open-prose
+```
+
+Restart the Gateway after enabling or installing the plugin.
+
+Related docs: [Plugins](/plugin), [Plugin manifest](/plugins/manifest), [Skills](/tools/skills).
+
+## Slash command
+
+OpenProse registers `/prose` as a user-invocable skill command. It routes to the OpenProse VM instructions and uses Clawdbot tools under the hood.
+
+Common commands:
+
+```
+/prose help
+/prose run <file.prose>
+/prose run <handle/slug>
+/prose run <https://example.com/file.prose>
+/prose compile <file.prose>
+/prose examples
+/prose update
+```
+
+## File locations
+
+OpenProse keeps state under `.prose/` in your workspace:
+
+```
+.prose/
+├── .env
+├── runs/
+│   └── {YYYYMMDD}-{HHMMSS}-{random}/
+│       ├── program.prose
+│       ├── state.md
+│       ├── bindings/
+│       └── agents/
+└── agents/
+```
+
+User-level persistent agents live at:
+
+```
+~/.prose/agents/
+```
+
+## State modes
+
+OpenProse supports multiple state backends:
+
+- **filesystem** (default): `.prose/runs/...`
+- **in-context**: transient, for small programs
+- **sqlite** (experimental): requires `sqlite3` binary
+- **postgres** (experimental): requires `psql` and a connection string
+
+Notes:
+- sqlite/postgres are opt-in and experimental.
+- postgres credentials flow into subagent logs; use a dedicated, least-privileged DB.
+
+## Remote programs
+
+`/prose run <handle/slug>` resolves to `https://p.prose.md/<handle>/<slug>`.
+Direct URLs are fetched as-is. This uses the `web_fetch` tool (or `exec` for POST).
+
+## Clawdbot runtime mapping
+
+OpenProse programs map to Clawdbot primitives:
+
+| OpenProse concept | Clawdbot tool |
+| --- | --- |
+| Spawn session / Task tool | `sessions_spawn` |
+| File read/write | `read` / `write` |
+| Web fetch | `web_fetch` |
+
+If your tool allowlist blocks these tools, OpenProse programs will fail. See [Skills config](/tools/skills-config).
+
+## Telemetry
+
+OpenProse telemetry is **enabled by default** and stored in `.prose/.env`:
+
+```
+OPENPROSE_TELEMETRY=enabled
+USER_ID=...
+SESSION_ID=...
+```
+
+Disable permanently:
+
+```
+/prose run ... --no-telemetry
+```
+
+Telemetry posts are best-effort; failures do not block execution.
+
+## Security + approvals
+
+Treat `.prose` files like code. Review before running. Use Clawdbot tool allowlists and approval gates to control side effects.
+
+For deterministic, approval-gated workflows, compare with [Lobster](/tools/lobster).

docs/start/hubs.md

@@ -97,6 +97,7 @@ Use these hubs to discover every page, including deep dives and reference docs t
 ## Tools + automation
 
 - [Tools surface](/tools)
+- [OpenProse](/prose)
 - [CLI reference](/cli)
 - [Exec tool](/tools/exec)
 - [Elevated mode](/tools/elevated)

docs/tools/skills.md

@@ -38,10 +38,12 @@ applies: workspace wins, then managed/local, then bundled.
 
 ## Plugins + skills
 
-Plugins can ship their own skills (for example, `voice-call`) and gate them via
-`metadata.clawdbot.requires.config` on the plugin’s config entry. See
-[Plugins](/plugin) for plugin discovery/config and [Tools](/tools) for the tool
-surface those skills teach.
+Plugins can ship their own skills by listing `skills` directories in
+`clawdbot.plugin.json` (paths relative to the plugin root). Plugin skills load
+when the plugin is enabled and participate in the normal skill precedence rules.
+You can gate them via `metadata.clawdbot.requires.config` on the plugin’s config
+entry. See [Plugins](/plugin) for discovery/config and [Tools](/tools) for the
+tool surface those skills teach.
 
 ## ClawdHub (install + sync)
 

docs/tools/slash-commands.md

@@ -109,6 +109,7 @@ Notes:
   - `/skill <name> [input]` runs a skill by name (useful when native command limits prevent per-skill commands).
   - By default, skill commands are forwarded to the model as a normal request.
   - Skills may optionally declare `command-dispatch: tool` to route the command directly to a tool (deterministic, no model).
+  - Example: `/prose` (OpenProse plugin) — see [OpenProse](/prose).
 - **Native command arguments:** Discord uses autocomplete for dynamic options (and button menus when you omit required args). Telegram and Slack show a button menu when a command supports choices and you omit the arg.
 
 ## Usage surfaces (what shows where)