From decbd611a0928625af9d3d6ea7325ed49da17347 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 17 May 2026 11:49:52 +0100 Subject: [PATCH] docs: refresh embedded skill guidance --- CHANGELOG.md | 1 + skills/1password/SKILL.md | 4 +- skills/apple-notes/SKILL.md | 2 +- skills/apple-reminders/SKILL.md | 20 +- skills/bear-notes/SKILL.md | 14 +- skills/blogwatcher/SKILL.md | 2 +- skills/blucli/SKILL.md | 2 +- skills/camsnap/SKILL.md | 2 +- skills/canvas/SKILL.md | 229 +---- skills/clawhub/SKILL.md | 2 +- skills/coding-agent/SKILL.md | 402 ++------ skills/discord/SKILL.md | 115 +-- skills/eightctl/SKILL.md | 2 +- skills/gemini/SKILL.md | 14 +- skills/gh-issues/SKILL.md | 962 +++--------------- skills/gifgrep/SKILL.md | 4 +- skills/github/SKILL.md | 150 +-- skills/gog/SKILL.md | 2 +- skills/goplaces/SKILL.md | 4 +- skills/healthcheck/SKILL.md | 292 ++---- skills/himalaya/SKILL.md | 235 +---- skills/imsg/SKILL.md | 32 +- skills/mcporter/SKILL.md | 2 +- skills/model-usage/SKILL.md | 2 +- skills/nano-pdf/SKILL.md | 4 +- skills/node-connect/SKILL.md | 2 +- skills/notion/SKILL.md | 282 +++-- skills/obsidian/SKILL.md | 12 +- skills/openai-whisper-api/SKILL.md | 23 +- .../openai-whisper-api/scripts/transcribe.sh | 94 +- skills/openai-whisper/SKILL.md | 2 +- skills/openhue/SKILL.md | 10 +- skills/oracle/SKILL.md | 41 +- skills/ordercli/SKILL.md | 2 +- skills/peekaboo/SKILL.md | 2 +- skills/sag/SKILL.md | 2 +- skills/session-logs/SKILL.md | 2 +- skills/sherpa-onnx-tts/SKILL.md | 8 +- skills/skill-creator/SKILL.md | 396 +------ .../skill-creator/scripts/quick_validate.py | 10 +- skills/slack/SKILL.md | 118 +-- skills/songsee/SKILL.md | 2 +- skills/sonoscli/SKILL.md | 2 +- skills/spotify-player/SKILL.md | 2 +- skills/summarize/SKILL.md | 22 +- skills/taskflow-inbox-triage/SKILL.md | 8 +- skills/taskflow/SKILL.md | 8 +- skills/things-mac/SKILL.md | 4 +- skills/tmux/SKILL.md | 161 +-- skills/trello/SKILL.md | 2 +- skills/video-frames/SKILL.md | 4 +- skills/voice-call/SKILL.md | 2 +- skills/wacli/SKILL.md | 4 +- skills/weather/SKILL.md | 105 +- skills/xurl/SKILL.md | 483 ++------- 55 files changed, 1015 insertions(+), 3300 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 63ac08dd41c1..db7714be3d7d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ Docs: https://docs.openclaw.ai - Agents/tools: shorten built-in tool descriptions and schema hints across media, messaging, sessions, cron, Gateway, web, image/PDF, TTS, nodes, and plan tools while preserving routing guardrails. - Skills: add node inspector debugging, fused diagram generation, and throwaway spike workflow skills. - CLI/plugins: add `defineToolPlugin` plus `openclaw plugins build`, `validate`, and `init` for typed simple tool plugins with generated manifest metadata, optional tool declarations, and context factories. +- Agents/skills: tighten bundled skill prompts and metadata, quote skill descriptions, refresh current CLI/API guidance, and update embedded sherpa-onnx runtime downloads. - Proxy: support HTTPS managed forward-proxy endpoints and scoped `proxy.tls.caFile` CA trust for proxy endpoint TLS. (#79171) Thanks @jesse-merhi. - QA-Lab: add first-hour 20-turn and optional 100-turn runtime parity scenarios, with tier metadata for standard and soak QA gates. (#80323) Thanks @100yenadmin. - QA-Lab: add a live-only Codex Pi-shaped Read vocabulary canary so runtime parity catches native workspace-read prompt compatibility drift. (#80323) Thanks @100yenadmin. diff --git a/skills/1password/SKILL.md b/skills/1password/SKILL.md index f8500bc61924..69ffa4441e48 100644 --- a/skills/1password/SKILL.md +++ b/skills/1password/SKILL.md @@ -1,6 +1,6 @@ --- name: 1password -description: Set up and use 1Password CLI for sign-in, desktop integration, and reading or injecting secrets. +description: "Set up and use 1Password CLI for sign-in, desktop integration, and reading or injecting secrets." homepage: https://developer.1password.com/docs/cli/get-started/ metadata: { @@ -41,7 +41,7 @@ Follow the official CLI get-started steps. Don't guess install commands. 6. Verify access inside tmux: `op whoami` (must succeed before any secret read). 7. If multiple accounts: use `--account` or `OP_ACCOUNT`. -## REQUIRED tmux session (T-Max) +## REQUIRED tmux session (tmux) The shell tool uses a fresh TTY per command. To avoid re-prompts and failures, always run `op` inside a dedicated tmux session with a fresh socket/session name. diff --git a/skills/apple-notes/SKILL.md b/skills/apple-notes/SKILL.md index 1269a2be6a1a..57740cad8539 100644 --- a/skills/apple-notes/SKILL.md +++ b/skills/apple-notes/SKILL.md @@ -1,6 +1,6 @@ --- name: apple-notes -description: Create, view, edit, delete, search, move, or export Apple Notes via the memo CLI on macOS. +description: "Create, view, edit, delete, search, move, or export Apple Notes via the memo CLI on macOS." homepage: https://github.com/antoniorodr/memo metadata: { diff --git a/skills/apple-reminders/SKILL.md b/skills/apple-reminders/SKILL.md index 83dfb7c5cb2a..ecb0220c2286 100644 --- a/skills/apple-reminders/SKILL.md +++ b/skills/apple-reminders/SKILL.md @@ -1,6 +1,6 @@ --- name: apple-reminders -description: List, add, edit, complete, or delete Apple Reminders and reminder lists via remindctl. +description: "List, add, edit, complete, or delete Apple Reminders and reminder lists via remindctl." homepage: https://github.com/steipete/remindctl metadata: { @@ -29,7 +29,7 @@ Use `remindctl` to manage Apple Reminders directly from the terminal. ## When to Use -✅ **USE this skill when:** +Use when: - User explicitly mentions "reminder" or "Reminders app" - Creating personal to-dos with due dates that sync to iOS @@ -38,13 +38,13 @@ Use `remindctl` to manage Apple Reminders directly from the terminal. ## When NOT to Use -❌ **DON'T use this skill when:** +Do not use when: -- Scheduling OpenClaw tasks or alerts → use `cron` tool with systemEvent instead -- Calendar events or appointments → use Apple Calendar -- Project/work task management → use Notion, GitHub Issues, or task queue -- One-time notifications → use `cron` tool for timed alerts -- User says "remind me" but means an OpenClaw alert → clarify first +- Scheduling OpenClaw tasks or alerts -> use `cron` tool with systemEvent instead +- Calendar events or appointments -> use Apple Calendar +- Project/work task management -> use Notion, GitHub Issues, or task queue +- One-time notifications -> use `cron` tool for timed alerts +- User says "remind me" but means an OpenClaw alert -> clarify first ## Setup @@ -114,5 +114,5 @@ User: "Remind me to check on the deploy in 2 hours" **Ask:** "Do you want this in Apple Reminders (syncs to your phone) or as an OpenClaw alert (I'll message you here)?" -- Apple Reminders → use this skill -- OpenClaw alert → use `cron` tool with systemEvent +- Apple Reminders -> use this skill +- OpenClaw alert -> use `cron` tool with systemEvent diff --git a/skills/bear-notes/SKILL.md b/skills/bear-notes/SKILL.md index ca36f1907d41..c1777041c26a 100644 --- a/skills/bear-notes/SKILL.md +++ b/skills/bear-notes/SKILL.md @@ -1,6 +1,6 @@ --- name: bear-notes -description: Create, search, and manage Bear notes via grizzly CLI. +description: "Create, search, and manage Bear notes via grizzly CLI." homepage: https://bear.app metadata: { @@ -36,7 +36,7 @@ Requirements For operations that require a token (add-text, tags, open-note --selected), you need an authentication token: -1. Open Bear → Help → API Token → Copy Token +1. Open Bear -> Help -> API Token -> Copy Token 2. Save it: `echo "YOUR_TOKEN" > ~/.config/grizzly/token` ## Common Commands @@ -76,11 +76,11 @@ grizzly open-tag --name "work" --enable-callback --json Common flags: -- `--dry-run` — Preview the URL without executing -- `--print-url` — Show the x-callback-url -- `--enable-callback` — Wait for Bear's response (needed for reading data) -- `--json` — Output as JSON (when using callbacks) -- `--token-file PATH` — Path to Bear API token file +- `--dry-run` - Preview the URL without executing +- `--print-url` - Show the x-callback-url +- `--enable-callback` - Wait for Bear's response (needed for reading data) +- `--json` - Output as JSON (when using callbacks) +- `--token-file PATH` - Path to Bear API token file ## Configuration diff --git a/skills/blogwatcher/SKILL.md b/skills/blogwatcher/SKILL.md index 8d623a06e9f5..6b7031b69577 100644 --- a/skills/blogwatcher/SKILL.md +++ b/skills/blogwatcher/SKILL.md @@ -1,6 +1,6 @@ --- name: blogwatcher -description: Monitor blogs and RSS/Atom feeds for updates using the blogwatcher CLI. +description: "Monitor blogs and RSS/Atom feeds for updates using the blogwatcher CLI." homepage: https://github.com/Hyaxia/blogwatcher metadata: { diff --git a/skills/blucli/SKILL.md b/skills/blucli/SKILL.md index 5cd56d123d88..2cdaadb86c03 100644 --- a/skills/blucli/SKILL.md +++ b/skills/blucli/SKILL.md @@ -1,6 +1,6 @@ --- name: blucli -description: BluOS CLI (blu) for discovery, playback, grouping, and volume. +description: "BluOS CLI (blu) for discovery, playback, grouping, and volume." homepage: https://blucli.sh metadata: { diff --git a/skills/camsnap/SKILL.md b/skills/camsnap/SKILL.md index ba11a0852a57..f7ad9adfb871 100644 --- a/skills/camsnap/SKILL.md +++ b/skills/camsnap/SKILL.md @@ -1,6 +1,6 @@ --- name: camsnap -description: Capture frames or clips from RTSP/ONVIF cameras. +description: "Capture frames or clips from RTSP/ONVIF cameras." homepage: https://camsnap.ai metadata: { diff --git a/skills/canvas/SKILL.md b/skills/canvas/SKILL.md index d5a9bab0bc51..a3c0ebe930fb 100644 --- a/skills/canvas/SKILL.md +++ b/skills/canvas/SKILL.md @@ -1,199 +1,78 @@ -# Canvas Skill +--- +name: canvas +description: "Present HTML on connected OpenClaw node canvases, navigate/eval/snapshot, and debug canvas host URLs." +metadata: { "openclaw": { "emoji": "🖼️" } } +--- -Display HTML content on connected OpenClaw nodes (Mac app, iOS, Android). +# Canvas -## Overview +Use canvas to show HTML on connected Mac/iOS/Android nodes. -The canvas tool lets you present web content on any connected node's canvas view. Great for: +## Model -- Displaying games, visualizations, dashboards -- Showing generated HTML content -- Interactive demos +- Canvas host serves files from `plugins.entries.canvas.config.host.root`. +- Canvas routes live on the Gateway HTTP port (`gateway.port`, default `18789`). +- Node bridge sends canvas URLs to connected node apps. +- Node apps render URLs in a WebView. +- Host name follows `gateway.bind`: loopback local only, LAN IP for LAN, Tailscale host for tailnet, auto picks best route. +- Localhost URLs only work for a node on the same machine. +- Paired nodes normally receive node-scoped `pluginSurfaceUrls.canvas` capability URLs; prefer those when available. -## How It Works +## Config -### Architecture - -``` -┌─────────────────┐ ┌──────────────────┐ ┌─────────────┐ -│ Canvas Host │────▶│ Node Bridge │────▶│ Node App │ -│ (HTTP Server) │ │ (TCP Server) │ │ (Mac/iOS/ │ -│ Port 18793 │ │ Port 18790 │ │ Android) │ -└─────────────────┘ └──────────────────┘ └─────────────┘ -``` - -1. **Canvas Host Server**: Serves static HTML/CSS/JS files from `canvasHost.root` directory -2. **Node Bridge**: Communicates canvas URLs to connected nodes -3. **Node Apps**: Render the content in a WebView - -### Tailscale Integration - -The canvas host server binds based on `gateway.bind` setting: - -| Bind Mode | Server Binds To | Canvas URL Uses | -| ---------- | ------------------- | -------------------------- | -| `loopback` | 127.0.0.1 | localhost (local only) | -| `lan` | LAN interface | LAN IP address | -| `tailnet` | Tailscale interface | Tailscale hostname | -| `auto` | Best available | Tailscale > LAN > loopback | - -**Key insight:** The `canvasHostHostForBridge` is derived from `bridgeHost`. When bound to Tailscale, nodes receive URLs like: - -``` -http://:18793/__openclaw__/canvas/.html -``` - -This is why localhost URLs don't work - the node receives the Tailscale hostname from the bridge! - -## Actions - -| Action | Description | -| ---------- | ------------------------------------ | -| `present` | Show canvas with optional target URL | -| `hide` | Hide the canvas | -| `navigate` | Navigate to a new URL | -| `eval` | Execute JavaScript in the canvas | -| `snapshot` | Capture screenshot of canvas | - -## Configuration - -In the active OpenClaw config file (`$OPENCLAW_CONFIG_PATH`, default `~/.openclaw/openclaw.json`): +Active config: `$OPENCLAW_CONFIG_PATH` or `~/.openclaw/openclaw.json`. ```json { - "canvasHost": { - "enabled": true, - "port": 18793, - "root": "/Users/you/clawd/canvas", - "liveReload": true + "plugins": { + "entries": { + "canvas": { + "config": { + "host": { + "enabled": true, + "root": "~/.openclaw/canvas", + "liveReload": true + } + } + } + } }, - "gateway": { - "bind": "auto" - } + "gateway": { "bind": "auto" } } ``` -### Live Reload +## Actions -When `liveReload: true` (default), the canvas host: - -- Watches the root directory for changes (via chokidar) -- Injects a WebSocket client into HTML files -- Automatically reloads connected canvases when files change - -Great for development! +- `present`: show canvas, optional URL. +- `hide`: hide canvas. +- `navigate`: open new URL. +- `eval`: run JavaScript in current canvas. +- `snapshot`: capture screenshot. ## Workflow -### 1. Create HTML content +1. Ensure Canvas plugin host is enabled. +2. Put HTML/CSS/JS under `plugins.entries.canvas.config.host.root` or the default state canvas dir. +3. Use a route reachable by the target node. +4. Present the hosted URL: `/__openclaw__/canvas/.html`. +5. Use `snapshot` when the user needs proof. -Place files in the canvas root directory (default `~/clawd/canvas/`): +## URL shape -```bash -cat > ~/clawd/canvas/my-game.html << 'HTML' - - -My Game - -

Hello Canvas!

- - -HTML +```text +http://:/__openclaw__/canvas/index.html +http://:/__openclaw__/canvas/games/snake.html ``` -### 2. Find your canvas host URL +Path mapping: -Check how your gateway is bound: +- `/__openclaw__/canvas/index.html` -> `/index.html` +- `/__openclaw__/canvas/games/snake.html` -> `/games/snake.html` -```bash -CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/openclaw.json}" -cat "$CONFIG_PATH" | jq '.gateway.bind' -``` +## Troubleshooting -Then construct the URL: - -- **loopback**: `http://127.0.0.1:18793/__openclaw__/canvas/.html` -- **lan/tailnet/auto**: `http://:18793/__openclaw__/canvas/.html` - -Find your Tailscale hostname: - -```bash -tailscale status --json | jq -r '.Self.DNSName' | sed 's/\.$//' -``` - -### 3. Find connected nodes - -```bash -openclaw nodes list -``` - -Look for Mac/iOS/Android nodes with canvas capability. - -### 4. Present content - -``` -canvas action:present node: target: -``` - -**Example:** - -``` -canvas action:present node:mac-63599bc4-b54d-4392-9048-b97abd58343a target:http://peters-mac-studio-1.sheep-coho.ts.net:18793/__openclaw__/canvas/snake.html -``` - -### 5. Navigate, snapshot, or hide - -``` -canvas action:navigate node: url: -canvas action:snapshot node: -canvas action:hide node: -``` - -## Debugging - -### White screen / content not loading - -**Cause:** URL mismatch between server bind and node expectation. - -**Debug steps:** - -1. Check server bind: `CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/openclaw.json}"; cat "$CONFIG_PATH" | jq '.gateway.bind'` -2. Check what port canvas is on: `lsof -i :18793` -3. Test URL directly: `curl http://:18793/__openclaw__/canvas/.html` - -**Solution:** Use the full hostname matching your bind mode, not localhost. - -### "node required" error - -Always specify `node:` parameter. - -### "node not connected" error - -Node is offline. Use `openclaw nodes list` to find online nodes. - -### Content not updating - -If live reload isn't working: - -1. Check `liveReload: true` in config -2. Ensure file is in the canvas root directory -3. Check for watcher errors in logs - -## URL Path Structure - -The canvas host serves from `/__openclaw__/canvas/` prefix: - -``` -http://:18793/__openclaw__/canvas/index.html → ~/clawd/canvas/index.html -http://:18793/__openclaw__/canvas/games/snake.html → ~/clawd/canvas/games/snake.html -``` - -The `/__openclaw__/canvas/` prefix is defined by `CANVAS_HOST_PATH` constant. - -## Tips - -- Keep HTML self-contained (inline CSS/JS) for best results -- Use the default index.html as a test page (has bridge diagnostics) -- The canvas persists until you `hide` it or navigate away -- Live reload makes development fast - just save and it updates! -- A2UI JSON push is WIP - use HTML files for now +- Node sees localhost but is remote: fix `gateway.bind` or public URL, regenerate URL. +- LAN node cannot load: verify same network, firewall, Gateway port, and auth/capability URL. +- Tailnet node cannot load: verify Tailscale status and advertised host. +- Blank page: open URL locally, check browser console, then snapshot node. +- Live reload missing: verify `liveReload` and file write under root. diff --git a/skills/clawhub/SKILL.md b/skills/clawhub/SKILL.md index 46f4fc2908a5..3b2a37452119 100644 --- a/skills/clawhub/SKILL.md +++ b/skills/clawhub/SKILL.md @@ -1,6 +1,6 @@ --- name: clawhub -description: Search, install, update, sync, or publish agent skills with the ClawHub CLI and registry. +description: "Search, install, update, sync, or publish agent skills with the ClawHub CLI and registry." metadata: { "openclaw": diff --git a/skills/coding-agent/SKILL.md b/skills/coding-agent/SKILL.md index a35781509d08..03b3f49cf349 100644 --- a/skills/coding-agent/SKILL.md +++ b/skills/coding-agent/SKILL.md @@ -1,6 +1,6 @@ --- name: coding-agent -description: 'Delegate coding tasks to Codex, Claude Code, OpenCode, or Pi agents via immediate background processes. Use when: (1) building or creating features/apps, (2) reviewing PRs in a temp clone/worktree, (3) refactoring large codebases, (4) iterative coding that needs file exploration. NOT for: simple one-line fixes (just edit), reading code (use read tool), thread-bound ACP harness requests in chat (use sessions_spawn with runtime:"acp"), or any work in ~/clawd workspace (never spawn agents here). All coding-agent runs start with background:true immediately. Claude Code: use --print --permission-mode bypassPermissions (no PTY). Codex/Pi/OpenCode: pty:true required. Completion notification must use openclaw message send, not system event/heartbeat.' +description: "Delegate coding work to Codex, Claude Code, OpenCode, or Pi as background workers; not simple edits or read-only code lookup." metadata: { "openclaw": @@ -32,354 +32,118 @@ metadata: } --- -# Coding Agent (always backgrounded) +# Coding Agent -Use **bash** with **background:true** for all coding-agent work. -Do not use a foreground one-shot path here. -Start the agent, get the `sessionId`, monitor with `process`, and require the worker to notify the user directly when it finishes. +Use for background feature builds, PR reviews, large refactors, and issue-to-PR loops. Do not use for simple edits, read-only lookup, ACP thread-bound work, or any run inside `~/.openclaw`, `$OPENCLAW_STATE_DIR`, or active OpenClaw state dirs. -## ⚠️ PTY Mode: Codex/Pi/OpenCode yes, Claude Code no +## Hard rules -For **Codex, Pi, and OpenCode**, PTY is required: +- Always launch with `background:true`. +- Codex, Pi, OpenCode: use `pty:true`. +- Claude Code: no PTY; use `claude --permission-mode bypassPermissions --print`. +- Capture a real notification route before spawning. +- Worker must send completion/failure via `openclaw message send`. +- Do not rely on heartbeat, system events, or notify-on-exit. +- Monitor with `process`; do not kill slow workers without cause. +- If user asked for a specific agent, use that agent. +- If worker fails/hangs, respawn or ask; do not silently hand-code instead. +- Never checkout branches or run background coding agents in `~/Projects/openclaw`; use an isolated checkout. -```bash -# Correct for Codex/Pi/OpenCode -bash pty:true background:true command:"codex exec 'Your prompt'" -``` +## Notification block -For **Claude Code** (`claude` CLI), use `--print --permission-mode bypassPermissions` instead. -Do not use PTY for Claude Code here. - -```bash -# Correct for Claude Code -bash background:true command:"claude --permission-mode bypassPermissions --print 'Your task'" - -# Wrong for Claude Code (PTY, wrong flags, no background) -bash pty:true command:"claude --dangerously-skip-permissions 'task'" -``` - -### Bash Tool Parameters - -| Parameter | Type | Description | -| ------------ | ------- | ------------------------------------------- | -| `command` | string | The shell command to run | -| `pty` | boolean | Use for Codex/Pi/OpenCode | -| `workdir` | string | Working directory | -| `background` | boolean | **Always true for this skill** | -| `timeout` | number | Timeout in seconds | -| `elevated` | boolean | Run on host instead of sandbox (if allowed) | - -### Process Tool Actions - -| Action | Description | -| ----------- | ---------------------------------------------------- | -| `list` | List all running/recent sessions | -| `poll` | Check if session is still running | -| `log` | Get session output (with optional offset/limit) | -| `write` | Send raw data to stdin | -| `submit` | Send data + newline (like typing and pressing Enter) | -| `send-keys` | Send key tokens or hex bytes | -| `paste` | Paste text (with optional bracketed mode) | -| `kill` | Terminate the session | - ---- - -## Mandatory Pattern - -Every coding-agent run follows this pattern: - -1. Capture the notification route from the current conversation before spawning: - - `notifyChannel` - - `notifyTarget` - - `notifyAccount` (if applicable) - - `notifyReplyTo` (if replying to a specific message is desired) - - `notifyThreadId` (Telegram topic / Slack thread when applicable) -2. Start the coding CLI with `background:true` immediately. -3. Include the notification route in the worker prompt and require the worker to call `openclaw message send` on completion. -4. Monitor with `process action:log` / `poll`. -5. If the worker needs input or fails before notifying, handle that explicitly yourself. Do not rely on heartbeat. - -If you do not have a trustworthy notification route, say so and do not claim that completion will notify the user automatically. - -### Multi-hour issue-to-PR builds - -For feature builds, bug fixes, or product work that may take a long time, use a -GitHub issue as the durable spec before starting Codex: - -1. Create or reuse the issue with `gh issue create` / `gh issue view`. -2. Start Codex in the background and include the issue URL, target repo, target - branch/base, expected PR output, required proof, and the notification route. -3. Tell Codex to create a branch, implement, run the relevant checks, run Codex - review/auto-review until there are no accepted actionable findings, and open - a PR linked to the issue. -4. Return the issue URL and background `sessionId` immediately. If a dashboard - task/flow URL exists, return that too. -5. Monitor with `process`. Abort with `process kill` for raw background runs, or - `tasks.cancel` when the work is mirrored into the Task Registry. - -Prefer a dashboard-backed issue-build/task-flow lane over a raw background -process when available. Do not block the user on the issue creation or build -loop; long-running work is expected. - ---- - -## Notification Route - -Do not rely on: - -- `openclaw system event` -- `tools.exec.notifyOnExit` -- heartbeat delivery -- `HEARTBEAT.md` - -Use a direct outbound completion message instead: - -```bash -openclaw message send --channel --target '' --message '' -``` - -Add optional routing flags only when they are real and applicable: - -- `--account ` -- `--reply-to ` -- `--thread-id ` - -`openclaw message send` is a direct outbound send. It does not depend on heartbeat being enabled. - -### Completion Prompt Snippet - -Append something like this to every worker prompt: +Append this shape to every worker prompt with real values: ```text -Notification route for completion: +Notification route: - channel: - target: - account: - reply_to: - thread_id: -When the task is completely finished, send exactly one completion message back to the user with openclaw message send using that route. -If the task fails fatally, send exactly one failure message back to the user with openclaw message send using that route. -Do not use openclaw system event. Do not rely on heartbeat. Do not skip the completion/failure message. +When finished, send exactly one completion or failure message using: +openclaw message send --channel --target '' --message '' +Add --account, --reply-to, or --thread-id only when present above. +Do not use openclaw system event or heartbeat. ``` -### Completion Command Template +If no trustworthy route exists, say completion auto-notify is unavailable. + +## Launch forms + +Write the worker prompt to a temp file first. This avoids shell quoting bugs when the required notification block contains quotes or newlines. ```bash -openclaw message send \ - --channel \ - --target '' \ - --message 'Done: ' +PROMPT=$(mktemp -t openclaw-worker-prompt.XXXXXX) +cat >"$PROMPT" <<'EOF' +Task. + +EOF +printf 'prompt file: %s\n' "$PROMPT" ``` -Optional additions: +Use `$PROMPT` when launching from the same shell/session. If using a separate tool call, substitute the printed path. + +Codex: ```bash - --account \ - --reply-to \ - --thread-id +bash pty:true background:true workdir:/path/repo command:"codex exec - < \"$PROMPT\"" ``` ---- +Claude Code: -## Quick Start +```bash +bash background:true workdir:/path/repo command:"claude --permission-mode bypassPermissions --print < \"$PROMPT\"" +``` -For scratch Codex work, create a temp git repo first, then start the worker in the background with the completion route injected into the prompt: +OpenCode: + +```bash +bash pty:true background:true workdir:/path/repo command:"opencode run < \"$PROMPT\"" +``` + +Pi: + +```bash +bash pty:true background:true workdir:/path/repo command:"pi -p \"$(cat \"$PROMPT\")\"" +``` + +## Long issue-to-PR work + +1. Create/reuse a GitHub issue as durable spec. +2. Include issue URL, repo, base branch, expected PR, proof, and notification route. +3. Tell worker to branch, implement, test, run review until no accepted actionable findings, open PR. +4. Return issue URL and `sessionId` immediately. +5. Monitor with `process`; cancel through Task Registry if mirrored there. + +## Scratch Codex + +Codex needs a trusted git repo: ```bash SCRATCH=$(mktemp -d) -cd "$SCRATCH" && git init - -bash pty:true workdir:$SCRATCH background:true command:"codex exec 'Your prompt here. - -Notification route for completion: -- channel: -- target: -- account: -- reply_to: -- thread_id: - -When the task is completely finished, send exactly one completion message back to the user with openclaw message send using that route. -If the task fails fatally, send exactly one failure message back to the user with openclaw message send using that route. -Do not use openclaw system event. Do not rely on heartbeat. Do not skip the completion/failure message.'" +git -C "$SCRATCH" init +PROMPT=$(mktemp -t openclaw-worker-prompt.XXXXXX) +cat >"$PROMPT" <<'EOF' +Build X. + +EOF +printf 'prompt file: %s\n' "$PROMPT" +bash pty:true background:true workdir:$SCRATCH command:"codex exec - < \"$PROMPT\"" ``` -Codex refuses to run outside a trusted git directory. -Reuse this same notify-route injection block in every example below; only the task-specific prompt body should change. +## Process actions ---- +- `list`: running/recent sessions. +- `poll`: status. +- `log`: output. +- `submit`: send input + Enter. +- `write`: raw stdin. +- `paste`: paste text. +- `kill`: terminate. -## Codex CLI +## Status to user -**Model:** `gpt-5.2-codex` is the default (set in ~/.codex/config.toml) - -### Flags - -| Flag | Effect | -| --------------- | ---------------------------------------- | -| `exec "prompt"` | One-shot execution inside the worker CLI | -| `--full-auto` | Sandboxed but auto-approves in workspace | -| `--yolo` | No sandbox, no approvals | - -### Building/Creating - -```bash -# Always background immediately -bash pty:true workdir:~/project background:true command:"codex exec --full-auto 'Build a dark mode toggle'" - -# More autonomy -bash pty:true workdir:~/project background:true command:"codex --yolo 'Refactor the auth module'" -``` - -### Reviewing PRs - -**Never review PRs in OpenClaw's own project folder.** -Clone to a temp folder or use a worktree. - -```bash -REVIEW_DIR=$(mktemp -d) -git clone https://github.com/user/repo.git $REVIEW_DIR -cd $REVIEW_DIR && gh pr checkout 130 - -bash pty:true workdir:$REVIEW_DIR background:true command:"codex review --base origin/main" -``` - -Or: - -```bash -git worktree add /tmp/pr-130-review pr-130-branch -bash pty:true workdir:/tmp/pr-130-review background:true command:"codex review --base main" -``` - -### Batch PR Reviews - -```bash -git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*' - -bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #86. git diff origin/main...origin/pr/86'" -bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #87. git diff origin/main...origin/pr/87'" - -process action:list -process action:log sessionId:XXX -``` - ---- - -## Claude Code - -```bash -bash workdir:~/project background:true command:"claude --permission-mode bypassPermissions --print 'Your task'" -``` - ---- - -## OpenCode - -```bash -bash pty:true workdir:~/project background:true command:"opencode run 'Your task'" -``` - ---- - -## Pi Coding Agent - -```bash -# Install: npm install -g @earendil-works/pi-coding-agent -bash pty:true workdir:~/project background:true command:"pi 'Your task'" - -# Non-interactive mode -bash pty:true workdir:~/project background:true command:"pi -p 'Summarize src/'" - -# Different provider/model -bash pty:true workdir:~/project background:true command:"pi --provider openai --model gpt-4o-mini -p 'Your task'" -``` - ---- - -## Parallel Issue Fixing with git worktrees - -```bash -git worktree add -b fix/issue-78 /tmp/issue-78 main -git worktree add -b fix/issue-99 /tmp/issue-99 main - -bash pty:true workdir:/tmp/issue-78 background:true command:"pnpm install && codex --yolo 'Fix issue #78: . Commit and push after review. Send the completion message with openclaw message send using the provided notify route.'" -bash pty:true workdir:/tmp/issue-99 background:true command:"pnpm install && codex --yolo 'Fix issue #99 from the approved ticket summary. Implement only the in-scope edits. Send the completion message with openclaw message send using the provided notify route.'" - -process action:list -process action:log sessionId:XXX -``` - ---- - -## ⚠️ Rules - -1. **Use the right execution mode per agent**: - - Codex/Pi/OpenCode: `pty:true` - - Claude Code: `--print --permission-mode bypassPermissions` (no PTY required) -2. **Respect tool choice** - if user asks for Codex, use Codex. - - Orchestrator mode: do NOT hand-code patches yourself. - - If an agent fails/hangs, respawn it or ask the user for direction, but don't silently take over. -3. **Be patient** - don't kill sessions because they're "slow" -4. **Monitor with process:log** - check progress without interfering -5. **--full-auto for building** - auto-approves changes -6. **vanilla for reviewing** - no special flags needed -7. **Parallel is OK** - run many Codex processes at once for batch work -8. **NEVER start Codex inside your OpenClaw state directory** (`$OPENCLAW_STATE_DIR`, default `~/.openclaw`) - it'll read your soul docs and get weird ideas about the org chart! -9. **NEVER checkout branches in ~/Projects/openclaw/** - that's the LIVE OpenClaw instance! -10. **Always inject the Completion Prompt Snippet** into the worker prompt before spawning. The simplified examples below omit it for brevity — never spawn a worker without it. - ---- - -## Progress Updates (Critical) - -When you spawn a coding agent in the background, keep the user in the loop. - -- Send 1 short message when you start: what is running and where. -- Update only when something changes: - - a milestone completes - - the worker asks a question - - you hit an error or need user action - - the worker finishes -- If you kill a session, immediately say you killed it and why. -- If you are expecting the worker to self-notify with `openclaw message send`, say that clearly in your start update. - -This prevents the user from seeing only a missing reply and having no idea what happened. - ---- - -## Rules - -1. **Always background immediately.** - - Use `background:true` for every coding-agent launch. - - Do not use the foreground one-shot path in this skill. -2. **Use the right execution mode per agent.** - - Codex/Pi/OpenCode: `pty:true` - - Claude Code: `--print --permission-mode bypassPermissions` -3. **Respect tool choice.** - - If the user asked for Codex, use Codex. - - Orchestrator mode: do not hand-code the patch yourself instead of using the requested coding agent. -4. **Capture notify routing before spawn.** - - Completion messaging must have a real route. -5. **Use direct completion messaging.** - - Require `openclaw message send`. - - Do not rely on `openclaw system event` or heartbeat. -6. **Do not silently take over.** - - If a worker fails or hangs, respawn it or ask for direction. Do not quietly switch to hand-editing. -7. **Monitor with `process`.** - - `process action:log` is the default low-friction check. -8. **Be patient.** - - Do not kill sessions just because they are slow. -9. **Parallel is OK.** - - Many background Codex sessions can run at once. -10. **Never start Codex in `~/.openclaw/`.** -11. **Never checkout branches in `~/Projects/openclaw/`.** - ---- - -## Learnings - -- **PTY is essential** for Codex/Pi/OpenCode. -- **Git repo required**: Codex needs a trusted git directory. -- **Use `exec` under background orchestration**: short and long tasks follow the same path now. -- **`submit` vs `write`**: use `submit` to send input plus Enter. -- **Direct message send beats heartbeat for completion notification** when the user must be told immediately and heartbeat may be disabled. +- Say what started, where, and `sessionId`. +- Update only on milestone, worker question, error, user action needed, or finish. +- If killed, say why. diff --git a/skills/discord/SKILL.md b/skills/discord/SKILL.md index dfedea1d88be..10186a04d993 100644 --- a/skills/discord/SKILL.md +++ b/skills/discord/SKILL.md @@ -1,47 +1,33 @@ --- name: discord -description: "Discord ops via the message tool (channel=discord)." +description: "Discord message-tool ops: send/read/edit/delete, react, poll, pin, thread, search, presence, media/components." metadata: { "openclaw": { "emoji": "🎮", "requires": { "config": ["channels.discord.token"] } } } allowed-tools: ["message"] --- -# Discord (Via `message`) +# Discord -Use the `message` tool. No provider-specific `discord` tool exposed to the agent. +Use the `message` tool with `channel: "discord"`. No separate Discord tool. -## Musts +## Rules -- Always: `channel: "discord"`. -- Respect gating: `channels.discord.actions.*` (some default off: `roles`, `moderation`, `presence`, `channels`). -- Prefer explicit ids: `guildId`, `channelId`, `messageId`, `userId`. -- Multi-account: optional `accountId`. - -## Guidelines - -- Avoid Markdown tables in outbound Discord messages. +- Respect `channels.discord.actions.*` gates. +- Prefer explicit `guildId`, `channelId`, `messageId`, `userId`. +- Multi-account: pass `accountId` when needed. +- Send targets: `to: "channel:"` or `to: "user:"`. - Mention users as `<@USER_ID>`. -- Prefer Discord components v2 (`components`) for rich UI; use legacy `embeds` only when you must. +- Avoid Markdown tables in outbound Discord messages. +- Prefer components v2 for rich UI; do not mix v2 `components` with legacy `embeds`. -## Targets +## Common actions -- Send-like actions: `to: "channel:"` or `to: "user:"`. -- Message-specific actions: `channelId: ""` (or `to`) + `messageId: ""`. - -## Common Actions (Examples) - -Send message: +Send: ```json -{ - "action": "send", - "channel": "discord", - "to": "channel:123", - "message": "hello", - "silent": true -} +{ "action": "send", "channel": "discord", "to": "channel:123", "message": "hello", "silent": true } ``` -Send with media: +Send media: ```json { @@ -53,61 +39,31 @@ Send with media: } ``` -- Optional `silent: true` to suppress Discord notifications. - -Send with components v2 (recommended for rich UI): +Components v2: ```json { "action": "send", "channel": "discord", "to": "channel:123", - "message": "Status update", + "message": "Status", "components": "[Carbon v2 components]" } ``` -- `components` expects Carbon component instances (Container, TextDisplay, etc.) from JS/TS integrations. -- Do not combine `components` with `embeds` (Discord rejects v2 + embeds). - -Legacy embeds (not recommended): - -```json -{ - "action": "send", - "channel": "discord", - "to": "channel:123", - "message": "Status update", - "embeds": [{ "title": "Legacy", "description": "Embeds are legacy." }] -} -``` - -- `embeds` are ignored when components v2 are present. - React: ```json -{ - "action": "react", - "channel": "discord", - "channelId": "123", - "messageId": "456", - "emoji": "✅" -} +{ "action": "react", "channel": "discord", "channelId": "123", "messageId": "456", "emoji": "👍" } ``` Read: ```json -{ - "action": "read", - "channel": "discord", - "to": "channel:123", - "limit": 20 -} +{ "action": "read", "channel": "discord", "to": "channel:123", "limit": 20 } ``` -Edit / delete: +Edit/delete: ```json { @@ -120,12 +76,7 @@ Edit / delete: ``` ```json -{ - "action": "delete", - "channel": "discord", - "channelId": "123", - "messageId": "456" -} +{ "action": "delete", "channel": "discord", "channelId": "123", "messageId": "456" } ``` Poll: @@ -136,24 +87,18 @@ Poll: "channel": "discord", "to": "channel:123", "pollQuestion": "Lunch?", - "pollOption": ["Pizza", "Sushi", "Salad"], - "pollMulti": false, + "pollOption": ["Pizza", "Sushi"], "pollDurationHours": 24 } ``` -Pins: +Pin: ```json -{ - "action": "pin", - "channel": "discord", - "channelId": "123", - "messageId": "456" -} +{ "action": "pin", "channel": "discord", "channelId": "123", "messageId": "456" } ``` -Threads: +Thread: ```json { @@ -173,25 +118,19 @@ Search: "channel": "discord", "guildId": "999", "query": "release notes", - "channelIds": ["123", "456"], + "channelIds": ["123"], "limit": 10 } ``` -Presence (often gated): +Presence, often gated: ```json { "action": "set-presence", "channel": "discord", "activityType": "playing", - "activityName": "with fire", + "activityName": "OpenClaw", "status": "online" } ``` - -## Writing Style (Discord) - -- Short, conversational, low ceremony. -- No markdown tables. -- Mention users as `<@USER_ID>`. diff --git a/skills/eightctl/SKILL.md b/skills/eightctl/SKILL.md index 80a5f1f4bbb0..1bec8bd40cc7 100644 --- a/skills/eightctl/SKILL.md +++ b/skills/eightctl/SKILL.md @@ -1,6 +1,6 @@ --- name: eightctl -description: Control Eight Sleep pods (status, temperature, alarms, schedules). +description: "Control Eight Sleep pods (status, temperature, alarms, schedules)." homepage: https://eightctl.sh metadata: { diff --git a/skills/gemini/SKILL.md b/skills/gemini/SKILL.md index f573afd6ba66..ca3356d09e95 100644 --- a/skills/gemini/SKILL.md +++ b/skills/gemini/SKILL.md @@ -1,6 +1,6 @@ --- name: gemini -description: Gemini CLI for one-shot Q&A, summaries, and generation. +description: "Gemini CLI one-shot prompts, summaries, generation, skills, hooks, MCP, or Gemma routing." homepage: https://ai.google.dev/ metadata: { @@ -24,18 +24,22 @@ metadata: # Gemini CLI -Use Gemini in one-shot mode with a positional prompt (avoid interactive mode). +Use Gemini in headless one-shot mode. Positional text starts interactive mode; use `-p/--prompt`. Quick start -- `gemini "Answer this question..."` -- `gemini --model "Prompt..."` -- `gemini --output-format json "Return JSON"` +- `gemini -p "Answer this question..."` +- `gemini -m -p "Prompt..."` +- `gemini -p "Return JSON" --output-format json` +- stdin appends to `-p`: `cat notes.md | gemini -p "Summarize"` Extensions - List: `gemini --list-extensions` - Manage: `gemini extensions ` +- Skills: `gemini skills ` +- Hooks: `gemini hooks ` +- MCP: `gemini mcp ` Notes diff --git a/skills/gh-issues/SKILL.md b/skills/gh-issues/SKILL.md index f85b5860ace3..ccbf84919e39 100644 --- a/skills/gh-issues/SKILL.md +++ b/skills/gh-issues/SKILL.md @@ -1,12 +1,12 @@ --- name: gh-issues -description: "Fetch GitHub issues, delegate fixes to subagents, open PRs, watch reviews, or run /gh-issues workflows." +description: "Fetch GitHub issues, select candidates, spawn background fix agents, open PRs, and optionally process PR review comments." user-invocable: true metadata: { "openclaw": { - "requires": { "bins": ["curl", "git", "gh"] }, + "requires": { "bins": ["git", "gh"] }, "primaryEnv": "GH_TOKEN", "install": [ @@ -22,864 +22,192 @@ metadata: } --- -# gh-issues — Auto-fix GitHub Issues with Parallel Sub-agents +# gh-issues -You are an orchestrator. Follow these 6 phases exactly. Do not skip phases. +Use for issue-to-PR automation. Prefer `gh` CLI; fall back to `gh api` only when a high-level command lacks the needed field. -IMPORTANT — No `gh` CLI dependency. This skill uses curl + the GitHub REST API exclusively. The GH_TOKEN env var is already injected by OpenClaw. Pass it as a Bearer token in all API calls: +## Arguments -``` -curl -s -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" ... +- positional `owner/repo`: optional; else infer from `git remote get-url origin`. +- `--label