mirror of
https://github.com/openclaw/openclaw.git
synced 2026-06-06 05:51:15 +08:00
docs: refresh embedded skill guidance
This commit is contained in:
Peter Steinberger
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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:
|
||||
{
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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:
|
||||
{
|
||||
|
||||
@@ -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:
|
||||
{
|
||||
|
||||
@@ -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:
|
||||
{
|
||||
|
||||
@@ -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://<tailscale-hostname>:18793/__openclaw__/canvas/<file>.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/<file>.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'
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head><title>My Game</title></head>
|
||||
<body>
|
||||
<h1>Hello Canvas!</h1>
|
||||
</body>
|
||||
</html>
|
||||
HTML
|
||||
```text
|
||||
http://<gateway-host>:<gateway.port>/__openclaw__/canvas/index.html
|
||||
http://<gateway-host>:<gateway.port>/__openclaw__/canvas/games/snake.html
|
||||
```
|
||||
|
||||
### 2. Find your canvas host URL
|
||||
Path mapping:
|
||||
|
||||
Check how your gateway is bound:
|
||||
- `/__openclaw__/canvas/index.html` -> `<canvas host root>/index.html`
|
||||
- `/__openclaw__/canvas/games/snake.html` -> `<canvas host root>/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/<file>.html`
|
||||
- **lan/tailnet/auto**: `http://<hostname>:18793/__openclaw__/canvas/<file>.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:<node-id> target:<full-url>
|
||||
```
|
||||
|
||||
**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:<node-id> url:<new-url>
|
||||
canvas action:snapshot node:<node-id>
|
||||
canvas action:hide node:<node-id>
|
||||
```
|
||||
|
||||
## 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://<hostname>:18793/__openclaw__/canvas/<file>.html`
|
||||
|
||||
**Solution:** Use the full hostname matching your bind mode, not localhost.
|
||||
|
||||
### "node required" error
|
||||
|
||||
Always specify `node:<node-id>` 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://<host>:18793/__openclaw__/canvas/index.html → ~/clawd/canvas/index.html
|
||||
http://<host>: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.
|
||||
|
||||
@@ -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":
|
||||
|
||||
@@ -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 <channel> --target '<target>' --message '<text>'
|
||||
```
|
||||
|
||||
Add optional routing flags only when they are real and applicable:
|
||||
|
||||
- `--account <id>`
|
||||
- `--reply-to <messageId>`
|
||||
- `--thread-id <threadId>`
|
||||
|
||||
`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: <notifyChannel>
|
||||
- target: <notifyTarget>
|
||||
- account: <notifyAccount or omit>
|
||||
- reply_to: <notifyReplyTo or omit>
|
||||
- thread_id: <notifyThreadId or omit>
|
||||
|
||||
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 <channel> --target '<target>' --message '<brief result>'
|
||||
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 <notifyChannel> \
|
||||
--target '<notifyTarget>' \
|
||||
--message 'Done: <brief summary>'
|
||||
PROMPT=$(mktemp -t openclaw-worker-prompt.XXXXXX)
|
||||
cat >"$PROMPT" <<'EOF'
|
||||
Task.
|
||||
<notification block>
|
||||
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 <notifyAccount> \
|
||||
--reply-to <notifyReplyTo> \
|
||||
--thread-id <notifyThreadId>
|
||||
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: <notifyChannel>
|
||||
- target: <notifyTarget>
|
||||
- account: <notifyAccount or omit>
|
||||
- reply_to: <notifyReplyTo or omit>
|
||||
- thread_id: <notifyThreadId or omit>
|
||||
|
||||
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.
|
||||
<notification block>
|
||||
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: <description>. 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.
|
||||
|
||||
@@ -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:<id>"` or `to: "user:<id>"`.
|
||||
- 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:<id>"` or `to: "user:<id>"`.
|
||||
- Message-specific actions: `channelId: "<id>"` (or `to`) + `messageId: "<id>"`.
|
||||
|
||||
## 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>`.
|
||||
|
||||
@@ -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:
|
||||
{
|
||||
|
||||
@@ -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 <name> "Prompt..."`
|
||||
- `gemini --output-format json "Return JSON"`
|
||||
- `gemini -p "Answer this question..."`
|
||||
- `gemini -m <model> -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 <command>`
|
||||
- Skills: `gemini skills <command>`
|
||||
- Hooks: `gemini hooks <command>`
|
||||
- MCP: `gemini mcp <command>`
|
||||
|
||||
Notes
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: gifgrep
|
||||
description: Search GIF providers with CLI/TUI, download results, and extract stills/sheets.
|
||||
description: "Search GIF providers with CLI/TUI, download results, and extract stills/sheets."
|
||||
homepage: https://gifgrep.com
|
||||
metadata:
|
||||
{
|
||||
@@ -35,7 +35,7 @@ Use `gifgrep` to search GIF providers (Tenor/Giphy), browse in a TUI, download r
|
||||
|
||||
GIF-Grab (gifgrep workflow)
|
||||
|
||||
- Search → preview → download → extract (still/sheet) for fast review and sharing.
|
||||
- Search -> preview -> download -> extract (still/sheet) for fast review and sharing.
|
||||
|
||||
Quick start
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: github
|
||||
description: "Use gh for GitHub issues, PR status, CI/logs, comments, reviews, releases, and API queries."
|
||||
description: "GitHub CLI for issues, PRs, CI/check logs, comments, reviews, releases, repos, and gh api queries."
|
||||
metadata:
|
||||
{
|
||||
"openclaw":
|
||||
@@ -28,155 +28,57 @@ metadata:
|
||||
}
|
||||
---
|
||||
|
||||
# GitHub Skill
|
||||
# GitHub
|
||||
|
||||
Use the `gh` CLI to interact with GitHub repositories, issues, PRs, and CI.
|
||||
Use `gh` for GitHub. Use `git` for local commits/branches/push/pull. Use code-reading tools for deep reviews.
|
||||
|
||||
## When to Use
|
||||
|
||||
✅ **USE this skill when:**
|
||||
|
||||
- Checking PR status, reviews, or merge readiness
|
||||
- Viewing CI/workflow run status and logs
|
||||
- Creating, closing, or commenting on issues
|
||||
- Creating or merging pull requests
|
||||
- Querying GitHub API for repository data
|
||||
- Listing repos, releases, or collaborators
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
❌ **DON'T use this skill when:**
|
||||
|
||||
- Local git operations (commit, push, pull, branch) → use `git` directly
|
||||
- Non-GitHub repos (GitLab, Bitbucket, self-hosted) → different CLIs
|
||||
- Cloning repositories → use `git clone`
|
||||
- Reviewing actual code changes → use `coding-agent` skill
|
||||
- Complex multi-file diffs → use `coding-agent` or read files directly
|
||||
|
||||
## Setup
|
||||
## Auth
|
||||
|
||||
```bash
|
||||
# Authenticate (one-time)
|
||||
gh auth login
|
||||
|
||||
# Verify
|
||||
gh auth status
|
||||
gh auth login
|
||||
```
|
||||
|
||||
### When the gateway HOME differs from the operator HOME
|
||||
Gateway HOME can differ from operator HOME. If `gh` auth exists elsewhere, set `GH_CONFIG_DIR` in the gateway service env and restart.
|
||||
|
||||
OpenClaw agent shells often run with a different `HOME` than the user that ran
|
||||
`gh auth login` (per-agent codex homes, systemd `User=` services, sudo). `gh`
|
||||
looks up its config under `$GH_CONFIG_DIR`, then `$XDG_CONFIG_HOME/gh`, then
|
||||
`$HOME/.config/gh`, so the agent shell can report `not logged into any GitHub
|
||||
hosts` even when the operator login is intact.
|
||||
|
||||
To point the gateway at the canonical `gh` config, set `GH_CONFIG_DIR` on the
|
||||
service environment, e.g.
|
||||
## PRs
|
||||
|
||||
```bash
|
||||
# Gateway service env file (example: ~/.openclaw/gateway.systemd.env)
|
||||
GH_CONFIG_DIR=/path/to/operator/.config/gh
|
||||
```
|
||||
|
||||
then restart the gateway. `openclaw doctor` warns when it detects an authenticated
|
||||
`hosts.yml` outside the agent process's effective `gh` config dir.
|
||||
|
||||
## Common Commands
|
||||
|
||||
### Pull Requests
|
||||
|
||||
```bash
|
||||
# List PRs
|
||||
gh pr list --repo owner/repo
|
||||
|
||||
# Check CI status
|
||||
gh pr list --repo owner/repo --json number,title,state,author,url
|
||||
gh pr view 55 --repo owner/repo --json title,body,author,files,commits,reviews,reviewDecision
|
||||
gh pr checks 55 --repo owner/repo
|
||||
|
||||
# View PR details
|
||||
gh pr view 55 --repo owner/repo
|
||||
|
||||
# Create PR
|
||||
gh pr create --title "feat: add feature" --body "Description"
|
||||
|
||||
# Merge PR
|
||||
gh pr merge 55 --squash --repo owner/repo
|
||||
gh pr diff 55 --repo owner/repo
|
||||
gh pr create --repo owner/repo --title "feat: title" --body-file /tmp/pr.md
|
||||
gh pr merge 55 --repo owner/repo --squash
|
||||
```
|
||||
|
||||
### Issues
|
||||
URLs work directly: `gh pr view https://github.com/owner/repo/pull/55`.
|
||||
|
||||
## Issues
|
||||
|
||||
```bash
|
||||
# List issues
|
||||
gh issue list --repo owner/repo --state open
|
||||
|
||||
# Create issue
|
||||
gh issue create --title "Bug: something broken" --body "Details..."
|
||||
|
||||
# Close issue
|
||||
gh issue close 42 --repo owner/repo
|
||||
gh issue list --repo owner/repo --state open --json number,title,labels,url
|
||||
gh issue view 42 --repo owner/repo --json title,body,comments,labels,state
|
||||
gh issue create --repo owner/repo --title "Bug: ..." --body-file /tmp/issue.md
|
||||
gh issue comment 42 --repo owner/repo --body-file /tmp/comment.md
|
||||
gh issue close 42 --repo owner/repo --comment "Fixed in ..."
|
||||
```
|
||||
|
||||
### CI/Workflow Runs
|
||||
## CI/runs
|
||||
|
||||
```bash
|
||||
# List recent runs
|
||||
gh run list --repo owner/repo --limit 10
|
||||
|
||||
# View specific run
|
||||
gh run view <run-id> --repo owner/repo
|
||||
|
||||
# View failed step logs only
|
||||
gh run view <run-id> --repo owner/repo --json status,conclusion,headSha,url
|
||||
gh run view <run-id> --repo owner/repo --log-failed
|
||||
|
||||
# Re-run failed jobs
|
||||
gh run rerun <run-id> --failed --repo owner/repo
|
||||
gh run rerun <run-id> --repo owner/repo --failed
|
||||
```
|
||||
|
||||
### API Queries
|
||||
## API
|
||||
|
||||
```bash
|
||||
# Get PR with specific fields
|
||||
gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
|
||||
|
||||
# List all labels
|
||||
gh api repos/owner/repo/labels --jq '.[].name'
|
||||
|
||||
# Get repo stats
|
||||
gh api repos/owner/repo --jq '{stars: .stargazers_count, forks: .forks_count}'
|
||||
gh api --cache 1h repos/owner/repo --jq '{stars: .stargazers_count, forks: .forks_count}'
|
||||
```
|
||||
|
||||
## JSON Output
|
||||
|
||||
Most commands support `--json` for structured output with `--jq` filtering:
|
||||
|
||||
```bash
|
||||
gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'
|
||||
gh pr list --json number,title,state,mergeable --jq '.[] | select(.mergeable == "MERGEABLE")'
|
||||
```
|
||||
|
||||
## Templates
|
||||
|
||||
### PR Review Summary
|
||||
|
||||
```bash
|
||||
# Get PR overview for review
|
||||
PR=55 REPO=owner/repo
|
||||
echo "## PR #$PR Summary"
|
||||
gh pr view $PR --repo $REPO --json title,body,author,additions,deletions,changedFiles \
|
||||
--jq '"**\(.title)** by @\(.author.login)\n\n\(.body)\n\n📊 +\(.additions) -\(.deletions) across \(.changedFiles) files"'
|
||||
gh pr checks $PR --repo $REPO
|
||||
```
|
||||
|
||||
### Issue Triage
|
||||
|
||||
```bash
|
||||
# Quick issue triage view
|
||||
gh issue list --repo owner/repo --state open --json number,title,labels,createdAt \
|
||||
--jq '.[] | "[\(.number)] \(.title) - \([.labels[].name] | join(", ")) (\(.createdAt[:10]))"'
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Always specify `--repo owner/repo` when not in a git directory
|
||||
- Use URLs directly: `gh pr view https://github.com/owner/repo/pull/55`
|
||||
- Rate limits apply; use `gh api --cache 1h` for repeated queries
|
||||
Use `--json` + `--jq` for structured output. Use `--body-file` for comments/bodies containing backticks, shell snippets, env names, or user text.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: gog
|
||||
description: Google Workspace CLI for Gmail, Calendar, Drive, Contacts, Sheets, and Docs.
|
||||
description: "Google Workspace CLI for Gmail, Calendar, Drive, Contacts, Sheets, and Docs."
|
||||
homepage: https://gogcli.sh
|
||||
metadata:
|
||||
{
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: goplaces
|
||||
description: Query Google Places for text search, place details, resolve, reviews, or scriptable JSON via goplaces.
|
||||
description: "Query Google Places for text search, place details, resolve, reviews, or scriptable JSON via goplaces."
|
||||
homepage: https://github.com/steipete/goplaces
|
||||
metadata:
|
||||
{
|
||||
@@ -48,5 +48,5 @@ Common commands
|
||||
Notes
|
||||
|
||||
- `--no-color` or `NO_COLOR` disables ANSI color.
|
||||
- Price levels: 0..4 (free → very expensive).
|
||||
- Price levels: 0..4 (free -> very expensive).
|
||||
- Type filter sends only the first `--type` value (API accepts one).
|
||||
|
||||
@@ -1,245 +1,105 @@
|
||||
---
|
||||
name: healthcheck
|
||||
description: Audit and harden hosts running OpenClaw for SSH, firewall, updates, exposure, cron checks, and risk posture.
|
||||
description: "Audit/harden OpenClaw hosts: SSH, firewall, updates, exposure, backups, disk encryption, gateway security."
|
||||
---
|
||||
|
||||
# OpenClaw Host Hardening
|
||||
# OpenClaw host healthcheck
|
||||
|
||||
## Overview
|
||||
Goal: assess host risk, run read-only checks, then propose staged hardening without breaking access.
|
||||
|
||||
Assess and harden the host running OpenClaw, then align it to a user-defined risk tolerance without breaking access. Use OpenClaw security tooling as a first-class signal, but treat OS hardening as a separate, explicit set of steps.
|
||||
## Rules
|
||||
|
||||
## Core rules
|
||||
- Ask before state-changing actions.
|
||||
- Do not change SSH/firewall/remote access until access path is confirmed.
|
||||
- Prefer reversible steps and rollback notes.
|
||||
- Never claim OpenClaw manages OS firewall, SSH, or updates.
|
||||
- If identity/role unknown, recommend only.
|
||||
- User choices: numbered list.
|
||||
- Never print secrets.
|
||||
|
||||
- Recommend running this skill with a state-of-the-art model (e.g., Opus 4.5, GPT 5.2+). The agent should self-check the current model and suggest switching if below that level; do not block execution.
|
||||
- Require explicit approval before any state-changing action.
|
||||
- Do not modify remote access settings without confirming how the user connects.
|
||||
- Prefer reversible, staged changes with a rollback plan.
|
||||
- Never claim OpenClaw changes the host firewall, SSH, or OS updates; it does not.
|
||||
- If role/identity is unknown, provide recommendations only.
|
||||
- Formatting: every set of user choices must be numbered so the user can reply with a single digit.
|
||||
- System-level backups are recommended; try to verify status.
|
||||
## Context to infer first
|
||||
|
||||
## Workflow (follow in order)
|
||||
- OS/version, container vs host.
|
||||
- Privilege level.
|
||||
- Access path: local, SSH, RDP, tailnet.
|
||||
- Network exposure: public IP, reverse proxy, tunnel, LAN only.
|
||||
- OpenClaw gateway status, bind, auth.
|
||||
- Backup status.
|
||||
- Disk encryption.
|
||||
- Automatic security updates.
|
||||
- Usage mode: personal workstation, local assistant box, remote server, other.
|
||||
|
||||
### 0) Model self-check (non-blocking)
|
||||
Ask only for missing facts. Simple phrasing preferred.
|
||||
|
||||
Before starting, check the current model. If it is below state-of-the-art (e.g., Opus 4.5, GPT 5.2+), recommend switching. Do not block execution.
|
||||
## Read-only checks
|
||||
|
||||
### 1) Establish context (read-only)
|
||||
Ask once for permission to run read-only checks. Then run relevant commands.
|
||||
|
||||
Try to infer 1–5 from the environment before asking. Prefer simple, non-technical questions if you need confirmation.
|
||||
Common:
|
||||
|
||||
Determine (in order):
|
||||
```bash
|
||||
openclaw security audit --deep
|
||||
openclaw gateway status --deep
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
1. OS and version (Linux/macOS/Windows), container vs host.
|
||||
2. Privilege level (root/admin vs user).
|
||||
3. Access path (local console, SSH, RDP, tailnet).
|
||||
4. Network exposure (public IP, reverse proxy, tunnel).
|
||||
5. OpenClaw gateway status and bind address.
|
||||
6. Backup system and status (e.g., Time Machine, system images, snapshots).
|
||||
7. Deployment context (local mac app, headless gateway host, remote gateway, container/CI).
|
||||
8. Disk encryption status (FileVault/LUKS/BitLocker).
|
||||
9. OS automatic security updates status.
|
||||
Note: these are not blocking items, but are highly recommended, especially if OpenClaw can access sensitive data.
|
||||
10. Usage mode for a personal assistant with full access (local workstation vs headless/remote vs other).
|
||||
macOS:
|
||||
|
||||
First ask once for permission to run read-only checks. If granted, run them by default and only ask questions for items you cannot infer or verify. Do not ask for information already visible in runtime or command output. Keep the permission ask as a single sentence, and list follow-up info needed as an unordered list (not numbered) unless you are presenting selectable choices.
|
||||
```bash
|
||||
sw_vers
|
||||
lsof -nP -iTCP -sTCP:LISTEN
|
||||
/usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate
|
||||
pfctl -s info
|
||||
tmutil status
|
||||
fdesetup status
|
||||
softwareupdate --schedule
|
||||
```
|
||||
|
||||
If you must ask, use non-technical prompts:
|
||||
Linux:
|
||||
|
||||
- “Are you using a Mac, Windows PC, or Linux?”
|
||||
- “Are you logged in directly on the machine, or connecting from another computer?”
|
||||
- “Is this machine reachable from the public internet, or only on your home/network?”
|
||||
- “Do you have backups enabled (e.g., Time Machine), and are they current?”
|
||||
- “Is disk encryption turned on (FileVault/BitLocker/LUKS)?”
|
||||
- “Are automatic security updates enabled?”
|
||||
- “How do you use this machine?”
|
||||
Examples:
|
||||
- Personal machine shared with the assistant
|
||||
- Dedicated local machine for the assistant
|
||||
- Dedicated remote machine/server accessed remotely (always on)
|
||||
- Something else?
|
||||
```bash
|
||||
cat /etc/os-release
|
||||
ss -ltnup || ss -ltnp
|
||||
ufw status || firewall-cmd --state || nft list ruleset
|
||||
systemctl status ssh sshd
|
||||
lsblk -f
|
||||
```
|
||||
|
||||
Only ask for the risk profile after system context is known.
|
||||
Windows:
|
||||
|
||||
If the user grants read-only permission, run the OS-appropriate checks by default. If not, offer them (numbered). Examples:
|
||||
```powershell
|
||||
systeminfo
|
||||
Get-NetFirewallProfile
|
||||
Get-BitLockerVolume
|
||||
```
|
||||
|
||||
1. OS: `uname -a`, `sw_vers`, `cat /etc/os-release`.
|
||||
2. Listening ports:
|
||||
- Linux: `ss -ltnup` (or `ss -ltnp` if `-u` unsupported).
|
||||
- macOS: `lsof -nP -iTCP -sTCP:LISTEN`.
|
||||
3. Firewall status:
|
||||
- Linux: `ufw status`, `firewall-cmd --state`, `nft list ruleset` (pick what is installed).
|
||||
- macOS: `/usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate` and `pfctl -s info`.
|
||||
4. Backups (macOS): `tmutil status` (if Time Machine is used).
|
||||
## Risk profile
|
||||
|
||||
### 2) Run OpenClaw security audits (read-only)
|
||||
After context is known, ask desired posture:
|
||||
|
||||
As part of the default read-only checks, run `openclaw security audit --deep`. Only offer alternatives if the user requests them:
|
||||
1. Convenience: local/private, minimal prompts.
|
||||
2. Balanced: secure defaults, low friction.
|
||||
3. Strict: remote/public/sensitive data, more lock-down.
|
||||
|
||||
1. `openclaw security audit` (faster, non-probing)
|
||||
2. `openclaw security audit --json` (structured output)
|
||||
## Report shape
|
||||
|
||||
Offer to apply OpenClaw safe defaults (numbered):
|
||||
- Current posture: one paragraph.
|
||||
- Findings: severity + evidence + why it matters.
|
||||
- Recommended plan: staged, reversible.
|
||||
- Commands: read-only first; write actions only after approval.
|
||||
- Gaps: what could not be checked.
|
||||
|
||||
1. `openclaw security audit --fix`
|
||||
## Hardening menu
|
||||
|
||||
Be explicit that `--fix` only tightens OpenClaw defaults and file permissions. It does not change host firewall, SSH, or OS update policies.
|
||||
Offer only relevant items:
|
||||
|
||||
If browser control is enabled, recommend that 2FA be enabled on all important accounts, with hardware keys preferred and SMS not sufficient.
|
||||
- Bind gateway to loopback/LAN/tailnet intentionally.
|
||||
- Require auth for remote access.
|
||||
- Close public ports or restrict by firewall.
|
||||
- Enable OS security updates.
|
||||
- Enable disk encryption.
|
||||
- Verify backups and restore path.
|
||||
- Disable password SSH or require keys/MFA where appropriate.
|
||||
- Add scheduled `openclaw security audit --deep`.
|
||||
|
||||
### 3) Check OpenClaw version/update status (read-only)
|
||||
|
||||
As part of the default read-only checks, run `openclaw update status`.
|
||||
|
||||
Report the current channel and whether an update is available.
|
||||
|
||||
### 4) Determine risk tolerance (after system context)
|
||||
|
||||
Ask the user to pick or confirm a risk posture and any required open services/ports (numbered choices below).
|
||||
Do not pigeonhole into fixed profiles; if the user prefers, capture requirements instead of choosing a profile.
|
||||
Offer suggested profiles as optional defaults (numbered). Note that most users pick Home/Workstation Balanced:
|
||||
|
||||
1. Home/Workstation Balanced (most common): firewall on with reasonable defaults, remote access restricted to LAN or tailnet.
|
||||
2. VPS Hardened: deny-by-default inbound firewall, minimal open ports, key-only SSH, no root login, automatic security updates.
|
||||
3. Developer Convenience: more local services allowed, explicit exposure warnings, still audited.
|
||||
4. Custom: user-defined constraints (services, exposure, update cadence, access methods).
|
||||
|
||||
### 5) Produce a remediation plan
|
||||
|
||||
Provide a plan that includes:
|
||||
|
||||
- Target profile
|
||||
- Current posture summary
|
||||
- Gaps vs target
|
||||
- Step-by-step remediation with exact commands
|
||||
- Access-preservation strategy and rollback
|
||||
- Risks and potential lockout scenarios
|
||||
- Least-privilege notes (e.g., avoid admin usage, tighten ownership/permissions where safe)
|
||||
- Credential hygiene notes (location of OpenClaw creds, prefer disk encryption)
|
||||
|
||||
Always show the plan before any changes.
|
||||
|
||||
### 6) Offer execution options
|
||||
|
||||
Offer one of these choices (numbered so users can reply with a single digit):
|
||||
|
||||
1. Do it for me (guided, step-by-step approvals)
|
||||
2. Show plan only
|
||||
3. Fix only critical issues
|
||||
4. Export commands for later
|
||||
|
||||
### 7) Execute with confirmations
|
||||
|
||||
For each step:
|
||||
|
||||
- Show the exact command
|
||||
- Explain impact and rollback
|
||||
- Confirm access will remain available
|
||||
- Stop on unexpected output and ask for guidance
|
||||
|
||||
### 8) Verify and report
|
||||
|
||||
Re-check:
|
||||
|
||||
- Firewall status
|
||||
- Listening ports
|
||||
- Remote access still works
|
||||
- OpenClaw security audit (re-run)
|
||||
|
||||
Deliver a final posture report and note any deferred items.
|
||||
|
||||
## Required confirmations (always)
|
||||
|
||||
Require explicit approval for:
|
||||
|
||||
- Firewall rule changes
|
||||
- Opening/closing ports
|
||||
- SSH/RDP configuration changes
|
||||
- Installing/removing packages
|
||||
- Enabling/disabling services
|
||||
- User/group modifications
|
||||
- Scheduling tasks or startup persistence
|
||||
- Update policy changes
|
||||
- Access to sensitive files or credentials
|
||||
|
||||
If unsure, ask.
|
||||
|
||||
## Periodic checks
|
||||
|
||||
After OpenClaw install or first hardening pass, run at least one baseline audit and version check:
|
||||
|
||||
- `openclaw security audit`
|
||||
- `openclaw security audit --deep`
|
||||
- `openclaw update status`
|
||||
|
||||
Ongoing monitoring is recommended. Use the OpenClaw cron tool/CLI to schedule periodic audits (Gateway scheduler). Do not create scheduled tasks without explicit approval. Store outputs in a user-approved location and avoid secrets in logs.
|
||||
When scheduling headless cron runs, include a note in the output that instructs the user to call `healthcheck` so issues can be fixed.
|
||||
|
||||
### Required prompt to schedule (always)
|
||||
|
||||
After any audit or hardening pass, explicitly offer scheduling and require a direct response. Use a short prompt like (numbered):
|
||||
|
||||
1. “Do you want me to schedule periodic audits (e.g., daily/weekly) via `openclaw cron add`?”
|
||||
|
||||
If the user says yes, ask for:
|
||||
|
||||
- cadence (daily/weekly), preferred time window, and output location
|
||||
- whether to also schedule `openclaw update status`
|
||||
|
||||
Use a stable cron job name so updates are deterministic. Prefer exact names:
|
||||
|
||||
- `healthcheck:security-audit`
|
||||
- `healthcheck:update-status`
|
||||
|
||||
Before creating, `openclaw cron list` and match on exact `name`. If found, `openclaw cron edit <id> ...`.
|
||||
If not found, `openclaw cron add --name <name> ...`.
|
||||
|
||||
Also offer a periodic version check so the user can decide when to update (numbered):
|
||||
|
||||
1. `openclaw update status` (preferred for source checkouts and channels)
|
||||
2. `npm view openclaw version` (published npm version)
|
||||
|
||||
## OpenClaw command accuracy
|
||||
|
||||
Use only supported commands and flags:
|
||||
|
||||
- `openclaw security audit [--deep] [--fix] [--json]`
|
||||
- `openclaw status` / `openclaw status --deep`
|
||||
- `openclaw health --json`
|
||||
- `openclaw update status`
|
||||
- `openclaw cron add|list|runs|run`
|
||||
|
||||
Do not invent CLI flags or imply OpenClaw enforces host firewall/SSH policies.
|
||||
|
||||
## Logging and audit trail
|
||||
|
||||
Record:
|
||||
|
||||
- Gateway identity and role
|
||||
- Plan ID and timestamp
|
||||
- Approved steps and exact commands
|
||||
- Exit codes and files modified (best effort)
|
||||
|
||||
Redact secrets. Never log tokens or full credential contents.
|
||||
|
||||
## Memory writes (conditional)
|
||||
|
||||
Only write to memory files when the user explicitly opts in and the session is a private/local workspace
|
||||
(per `docs/reference/templates/AGENTS.md`). Otherwise provide a redacted, paste-ready summary the user can
|
||||
decide to save elsewhere.
|
||||
|
||||
Follow the durable-memory prompt format used by OpenClaw compaction:
|
||||
|
||||
- Write lasting notes to `memory/YYYY-MM-DD.md`.
|
||||
|
||||
After each audit/hardening run, if opted-in, append a short, dated summary to `memory/YYYY-MM-DD.md`
|
||||
(what was checked, key findings, actions taken, any scheduled cron jobs, key decisions,
|
||||
and all commands executed). Append-only: never overwrite existing entries.
|
||||
Redact sensitive host details (usernames, hostnames, IPs, serials, service names, tokens).
|
||||
If there are durable preferences or decisions (risk posture, allowed ports, update policy),
|
||||
also update `MEMORY.md` (long-term memory is optional and only used in private sessions).
|
||||
|
||||
If the session cannot write to the workspace, ask for permission or provide exact entries
|
||||
the user can paste into the memory files.
|
||||
Confirm exact action before applying.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: himalaya
|
||||
description: "Use himalaya to list, read, search, compose, reply, forward, and organize IMAP/SMTP email."
|
||||
description: "Himalaya CLI for IMAP/SMTP mail: list, read, search, compose, reply, forward, copy, move, delete."
|
||||
homepage: https://github.com/pimalaya/himalaya
|
||||
metadata:
|
||||
{
|
||||
@@ -22,236 +22,59 @@ metadata:
|
||||
}
|
||||
---
|
||||
|
||||
# Himalaya Email CLI
|
||||
# Himalaya
|
||||
|
||||
Himalaya is a CLI email client that lets you manage emails from the terminal using IMAP, SMTP, Notmuch, or Sendmail backends.
|
||||
Use `himalaya` for IMAP/SMTP email from shell.
|
||||
|
||||
## References
|
||||
|
||||
- `references/configuration.md` (config file setup + IMAP/SMTP authentication)
|
||||
- `references/message-composition.md` (MML syntax for composing emails)
|
||||
- `references/configuration.md`: account config, auth, backend setup.
|
||||
- `references/message-composition.md`: MML compose syntax.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. Himalaya CLI installed (`himalaya --version` to verify)
|
||||
2. A configuration file at `~/.config/himalaya/config.toml`
|
||||
3. IMAP/SMTP credentials configured (password stored securely)
|
||||
|
||||
## Configuration Setup
|
||||
|
||||
Run the interactive wizard to set up an account:
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
himalaya --version
|
||||
himalaya account configure
|
||||
```
|
||||
|
||||
Or create `~/.config/himalaya/config.toml` manually:
|
||||
Config path: `~/.config/himalaya/config.toml`.
|
||||
|
||||
```toml
|
||||
[accounts.personal]
|
||||
email = "you@example.com"
|
||||
display-name = "Your Name"
|
||||
default = true
|
||||
Prefer password managers/keyrings for credentials; do not paste secrets into chat/logs.
|
||||
|
||||
backend.type = "imap"
|
||||
backend.host = "imap.example.com"
|
||||
backend.port = 993
|
||||
backend.encryption.type = "tls"
|
||||
backend.login = "you@example.com"
|
||||
backend.auth.type = "password"
|
||||
backend.auth.cmd = "pass show email/imap" # or use keyring
|
||||
|
||||
message.send.backend.type = "smtp"
|
||||
message.send.backend.host = "smtp.example.com"
|
||||
message.send.backend.port = 587
|
||||
message.send.backend.encryption.type = "start-tls"
|
||||
message.send.backend.login = "you@example.com"
|
||||
message.send.backend.auth.type = "password"
|
||||
message.send.backend.auth.cmd = "pass show email/smtp"
|
||||
```
|
||||
|
||||
## Common Operations
|
||||
|
||||
### List Folders
|
||||
## Read/search
|
||||
|
||||
```bash
|
||||
himalaya folder list
|
||||
```
|
||||
|
||||
### List Emails
|
||||
|
||||
List emails in INBOX (default):
|
||||
|
||||
```bash
|
||||
himalaya envelope list
|
||||
himalaya message read <id>
|
||||
himalaya envelope list from alice@example.com subject invoice
|
||||
```
|
||||
|
||||
List emails in a specific folder:
|
||||
|
||||
```bash
|
||||
himalaya envelope list --folder "Sent"
|
||||
```
|
||||
|
||||
List with pagination:
|
||||
|
||||
```bash
|
||||
himalaya envelope list --page 1 --page-size 20
|
||||
```
|
||||
|
||||
### Search Emails
|
||||
|
||||
```bash
|
||||
himalaya envelope list from john@example.com subject meeting
|
||||
```
|
||||
|
||||
### Read an Email
|
||||
|
||||
Read email by ID (shows plain text):
|
||||
|
||||
```bash
|
||||
himalaya message read 42
|
||||
```
|
||||
|
||||
Export raw MIME:
|
||||
|
||||
```bash
|
||||
himalaya message export 42 --full
|
||||
```
|
||||
|
||||
### Reply to an Email
|
||||
|
||||
Interactive reply (opens $EDITOR):
|
||||
|
||||
```bash
|
||||
himalaya message reply 42
|
||||
```
|
||||
|
||||
Reply-all:
|
||||
|
||||
```bash
|
||||
himalaya message reply 42 --all
|
||||
```
|
||||
|
||||
### Forward an Email
|
||||
|
||||
```bash
|
||||
himalaya message forward 42
|
||||
```
|
||||
|
||||
### Write a New Email
|
||||
|
||||
Interactive compose (opens $EDITOR):
|
||||
## Write
|
||||
|
||||
```bash
|
||||
himalaya message write
|
||||
himalaya template write
|
||||
himalaya template send < /tmp/message.txt
|
||||
himalaya message reply <id>
|
||||
himalaya message forward <id>
|
||||
```
|
||||
|
||||
Send directly using template:
|
||||
Use MML for attachments and rich messages; read `references/message-composition.md` first.
|
||||
|
||||
## Organize
|
||||
|
||||
```bash
|
||||
cat << 'EOF' | himalaya template send
|
||||
From: you@example.com
|
||||
To: recipient@example.com
|
||||
Subject: Test Message
|
||||
|
||||
Hello from Himalaya!
|
||||
EOF
|
||||
himalaya message copy <id> <folder>
|
||||
himalaya message move <id> <folder>
|
||||
himalaya message delete <id>
|
||||
himalaya flag add <id> --flag seen
|
||||
himalaya flag remove <id> --flag seen
|
||||
```
|
||||
|
||||
Or with headers flag:
|
||||
## Safety
|
||||
|
||||
```bash
|
||||
himalaya message write -H "To:recipient@example.com" -H "Subject:Test" "Message body here"
|
||||
```
|
||||
|
||||
### Move/Copy Emails
|
||||
|
||||
Move to folder:
|
||||
|
||||
```bash
|
||||
himalaya message move 42 "Archive"
|
||||
```
|
||||
|
||||
Copy to folder:
|
||||
|
||||
```bash
|
||||
himalaya message copy 42 "Important"
|
||||
```
|
||||
|
||||
### Delete an Email
|
||||
|
||||
```bash
|
||||
himalaya message delete 42
|
||||
```
|
||||
|
||||
### Manage Flags
|
||||
|
||||
Add flag:
|
||||
|
||||
```bash
|
||||
himalaya flag add 42 --flag seen
|
||||
```
|
||||
|
||||
Remove flag:
|
||||
|
||||
```bash
|
||||
himalaya flag remove 42 --flag seen
|
||||
```
|
||||
|
||||
## Multiple Accounts
|
||||
|
||||
List accounts:
|
||||
|
||||
```bash
|
||||
himalaya account list
|
||||
```
|
||||
|
||||
Use a specific account:
|
||||
|
||||
```bash
|
||||
himalaya --account work envelope list
|
||||
```
|
||||
|
||||
## Attachments
|
||||
|
||||
Save attachments from a message:
|
||||
|
||||
```bash
|
||||
himalaya attachment download 42
|
||||
```
|
||||
|
||||
Save to specific directory:
|
||||
|
||||
```bash
|
||||
himalaya attachment download 42 --dir ~/Downloads
|
||||
```
|
||||
|
||||
## Output Formats
|
||||
|
||||
Most commands support `--output` for structured output:
|
||||
|
||||
```bash
|
||||
himalaya envelope list --output json
|
||||
himalaya envelope list --output plain
|
||||
```
|
||||
|
||||
## Debugging
|
||||
|
||||
Enable debug logging:
|
||||
|
||||
```bash
|
||||
RUST_LOG=debug himalaya envelope list
|
||||
```
|
||||
|
||||
Full trace with backtrace:
|
||||
|
||||
```bash
|
||||
RUST_LOG=trace RUST_BACKTRACE=1 himalaya envelope list
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
- Use `himalaya --help` or `himalaya <command> --help` for detailed usage.
|
||||
- Message IDs are relative to the current folder; re-list after folder changes.
|
||||
- For composing rich emails with attachments, use MML syntax (see `references/message-composition.md`).
|
||||
- Store passwords securely using `pass`, system keyring, or a command that outputs the password.
|
||||
- Confirm before sending, deleting, or moving many messages.
|
||||
- Use `--account` when multiple accounts exist.
|
||||
- Quote exact message IDs in summaries.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: imsg
|
||||
description: iMessage/SMS CLI for listing chats, history, and sending messages via Messages.app.
|
||||
description: "iMessage/SMS CLI for listing chats, history, and sending messages via Messages.app."
|
||||
homepage: https://imsg.to
|
||||
metadata:
|
||||
{
|
||||
@@ -29,7 +29,7 @@ Use `imsg` to read and send iMessage/SMS via macOS Messages.app.
|
||||
|
||||
## When to Use
|
||||
|
||||
✅ **USE this skill when:**
|
||||
Use when:
|
||||
|
||||
- User explicitly asks to send iMessage or SMS
|
||||
- Reading iMessage conversation history
|
||||
@@ -38,16 +38,16 @@ Use `imsg` to read and send iMessage/SMS via macOS Messages.app.
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
❌ **DON'T use this skill when:**
|
||||
Do not use when:
|
||||
|
||||
- Telegram messages → use `message` tool with `channel:telegram`
|
||||
- Signal messages → use Signal channel if configured
|
||||
- WhatsApp messages → use WhatsApp channel if configured
|
||||
- Discord messages → use `message` tool with `channel:discord`
|
||||
- Slack messages → use `slack` skill
|
||||
- Group chat management (adding/removing members) → not supported
|
||||
- Bulk/mass messaging → always confirm with user first
|
||||
- Replying in current conversation → just reply normally (OpenClaw routes automatically)
|
||||
- Telegram messages -> use `message` tool with `channel:telegram`
|
||||
- Signal messages -> use Signal channel if configured
|
||||
- WhatsApp messages -> use WhatsApp channel if configured
|
||||
- Discord messages -> use `message` tool with `channel:discord`
|
||||
- Slack messages -> use `slack` skill
|
||||
- Group chat management (adding/removing members) -> not supported
|
||||
- Bulk/mass messaging -> always confirm with user first
|
||||
- Replying in current conversation -> just reply normally (OpenClaw routes automatically)
|
||||
|
||||
## Requirements
|
||||
|
||||
@@ -95,16 +95,16 @@ imsg send --to "+14155551212" --text "Hi" --service sms
|
||||
|
||||
## Service Options
|
||||
|
||||
- `--service imessage` — Force iMessage (requires recipient has iMessage)
|
||||
- `--service sms` — Force SMS (green bubble)
|
||||
- `--service auto` — Let Messages.app decide (default)
|
||||
- `--service imessage` - Force iMessage (requires recipient has iMessage)
|
||||
- `--service sms` - Force SMS (green bubble)
|
||||
- `--service auto` - Let Messages.app decide (default)
|
||||
|
||||
## Safety Rules
|
||||
|
||||
1. **Always confirm recipient and message content** before sending
|
||||
2. **Never send to unknown numbers** without explicit user approval
|
||||
3. **Be careful with attachments** — confirm file path exists
|
||||
4. **Rate limit yourself** — don't spam
|
||||
3. **Be careful with attachments** - confirm file path exists
|
||||
4. **Rate limit yourself** - don't spam
|
||||
|
||||
## Example Workflow
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: mcporter
|
||||
description: List, configure, authenticate, call, and inspect MCP servers/tools with mcporter over HTTP or stdio.
|
||||
description: "List, configure, authenticate, call, and inspect MCP servers/tools with mcporter over HTTP or stdio."
|
||||
homepage: http://mcporter.dev
|
||||
metadata:
|
||||
{
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: model-usage
|
||||
description: Summarize CodexBar local cost logs by model for Codex or Claude, including current or full breakdowns.
|
||||
description: "Summarize CodexBar local cost logs by model for Codex or Claude, including current or full breakdowns."
|
||||
metadata:
|
||||
{
|
||||
"openclaw":
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: nano-pdf
|
||||
description: Edit PDFs with natural-language instructions using the nano-pdf CLI.
|
||||
description: "Edit PDFs with natural-language instructions using the nano-pdf CLI."
|
||||
homepage: https://pypi.org/project/nano-pdf/
|
||||
metadata:
|
||||
{
|
||||
@@ -34,5 +34,5 @@ nano-pdf edit deck.pdf 1 "Change the title to 'Q3 Results' and fix the typo in t
|
||||
|
||||
Notes:
|
||||
|
||||
- Page numbers are 0-based or 1-based depending on the tool’s version/config; if the result looks off by one, retry with the other.
|
||||
- Page numbers are 0-based or 1-based depending on the tool's version/config; if the result looks off by one, retry with the other.
|
||||
- Always sanity-check the output PDF before sending it out.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: node-connect
|
||||
description: Diagnose OpenClaw Android, iOS, or macOS node pairing, QR/setup code, route, auth, and connection failures.
|
||||
description: "Diagnose OpenClaw Android, iOS, or macOS node pairing, QR/setup code, route, auth, and connection failures."
|
||||
---
|
||||
|
||||
# Node Connect
|
||||
|
||||
@@ -1,174 +1,150 @@
|
||||
---
|
||||
name: notion
|
||||
description: Notion API for creating and managing pages, databases, and blocks.
|
||||
homepage: https://developers.notion.com
|
||||
description: "Notion CLI/API for pages, Markdown content, data sources, files, comments, search, Workers, and raw API calls."
|
||||
homepage: https://developers.notion.com/cli/get-started/overview
|
||||
metadata:
|
||||
{
|
||||
"openclaw":
|
||||
{ "emoji": "📝", "requires": { "env": ["NOTION_API_KEY"] }, "primaryEnv": "NOTION_API_KEY" },
|
||||
{
|
||||
"emoji": "📝",
|
||||
"requires": { "anyBins": ["ntn", "curl"] },
|
||||
"primaryEnv": "NOTION_API_TOKEN",
|
||||
"install":
|
||||
[
|
||||
{
|
||||
"id": "node",
|
||||
"kind": "node",
|
||||
"package": "ntn",
|
||||
"bins": ["ntn"],
|
||||
"label": "Install official Notion CLI (npm)",
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
---
|
||||
|
||||
# notion
|
||||
# Notion
|
||||
|
||||
Use the Notion API to create/read/update pages, data sources (databases), and blocks.
|
||||
Prefer official `ntn` CLI. Use curl only when `ntn` is unavailable or a raw request is clearer.
|
||||
|
||||
## Setup
|
||||
|
||||
1. Create an integration at https://notion.so/my-integrations
|
||||
2. Copy the API key (starts with `ntn_` or `secret_`)
|
||||
3. Store it:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/notion
|
||||
echo "ntn_your_key_here" > ~/.config/notion/api_key
|
||||
npm install -g ntn
|
||||
ntn --version
|
||||
ntn login
|
||||
```
|
||||
|
||||
4. Share target pages/databases with your integration (click "..." → "Connect to" → your integration name)
|
||||
|
||||
## API Basics
|
||||
|
||||
All requests need:
|
||||
Script/headless auth:
|
||||
|
||||
```bash
|
||||
NOTION_KEY=$(cat ~/.config/notion/api_key)
|
||||
curl -X GET "https://api.notion.com/v1/..." \
|
||||
-H "Authorization: Bearer $NOTION_KEY" \
|
||||
-H "Notion-Version: 2025-09-03" \
|
||||
export NOTION_API_TOKEN=secret_or_ntn_token
|
||||
export NOTION_API_VERSION=2026-03-11
|
||||
```
|
||||
|
||||
`ntn api` sets `Authorization` and `Notion-Version` automatically. It uses CLI login by default, or `NOTION_API_TOKEN` when set.
|
||||
|
||||
## Inspect
|
||||
|
||||
```bash
|
||||
ntn doctor
|
||||
ntn api ls
|
||||
ntn api ls --json
|
||||
ntn api v1/comments --help
|
||||
ntn api v1/comments --spec -X POST
|
||||
ntn api v1/comments --docs -X POST
|
||||
```
|
||||
|
||||
## Pages
|
||||
|
||||
Markdown-first helpers:
|
||||
|
||||
```bash
|
||||
ntn pages get <page-id>
|
||||
ntn pages get <page-id> --json
|
||||
ntn pages create --parent page:<page-id> --content '# Title\n\nBody'
|
||||
ntn pages create --parent data-source:<data-source-id> < page.md
|
||||
ntn pages update <page-id> --content '# Updated'
|
||||
ntn pages update <page-id> < page.md
|
||||
ntn pages trash <page-id> --yes
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `pages get` prints Markdown with page properties as frontmatter.
|
||||
- Content input: `--content`, stdin, or editor in a TTY.
|
||||
- Parent refs: `page:<id>`, `database:<id>`, `data-source:<id>`.
|
||||
- For properties/templates/full Pages API, use `ntn api v1/pages`.
|
||||
|
||||
## Data sources
|
||||
|
||||
```bash
|
||||
ntn datasources resolve <database-id>
|
||||
ntn datasources resolve <database-id> --json
|
||||
ntn datasources query <data-source-id>
|
||||
ntn datasources query <data-source-id> --limit 50 --json
|
||||
ntn datasources query <data-source-id> --sort 'Date desc'
|
||||
ntn datasources query <data-source-id> --filter '{"property":"Done","checkbox":{"equals":true}}'
|
||||
```
|
||||
|
||||
Use `resolve` when you have a database ID. Query needs a data source ID.
|
||||
|
||||
## Raw API
|
||||
|
||||
```bash
|
||||
ntn api v1/users/me
|
||||
ntn api v1/search query=roadmap page_size:=10
|
||||
ntn api v1/pages 'parent[data_source_id]='"$DS_ID" 'properties[Name][title][0][text][content]=New item'
|
||||
ntn api "v1/pages/$PAGE_ID" -X PATCH in_trash:=true
|
||||
ntn api "v1/blocks/$PAGE_ID/children" -X PATCH \
|
||||
'children[0][type]=paragraph' \
|
||||
'children[0][paragraph][rich_text][0][text][content]=Hello'
|
||||
```
|
||||
|
||||
Input syntax:
|
||||
|
||||
- `path=value`: string body field.
|
||||
- `path:=json`: typed JSON body field.
|
||||
- `name==value`: query parameter.
|
||||
- `Header:Value`: request header.
|
||||
- `--data '<json>'` or stdin JSON for larger bodies.
|
||||
- Only one body source per request.
|
||||
|
||||
## Files
|
||||
|
||||
```bash
|
||||
ntn files create < image.png
|
||||
ntn files create --filename photo.png --content-type image/png < /tmp/photo
|
||||
ntn files create --external-url https://example.com/photo.png
|
||||
ntn files get <upload-id>
|
||||
ntn files list
|
||||
```
|
||||
|
||||
## Workers
|
||||
|
||||
```bash
|
||||
ntn workers new
|
||||
ntn workers deploy
|
||||
ntn workers list --json
|
||||
ntn workers runs list --json
|
||||
ntn workers runs logs <run-id>
|
||||
```
|
||||
|
||||
Workers may require Business/Enterprise plan and workspace enablement.
|
||||
|
||||
## Curl fallback
|
||||
|
||||
```bash
|
||||
curl -sS "https://api.notion.com/v1/users/me" \
|
||||
-H "Authorization: Bearer $NOTION_API_TOKEN" \
|
||||
-H "Notion-Version: 2026-03-11" \
|
||||
-H "Content-Type: application/json"
|
||||
```
|
||||
|
||||
> **Note:** The `Notion-Version` header is required. This skill uses `2025-09-03` (latest). In this version, databases are called "data sources" in the API.
|
||||
## Version notes
|
||||
|
||||
## Common Operations
|
||||
|
||||
**Search for pages and data sources:**
|
||||
|
||||
```bash
|
||||
curl -X POST "https://api.notion.com/v1/search" \
|
||||
-H "Authorization: Bearer $NOTION_KEY" \
|
||||
-H "Notion-Version: 2025-09-03" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"query": "page title"}'
|
||||
```
|
||||
|
||||
**Get page:**
|
||||
|
||||
```bash
|
||||
curl "https://api.notion.com/v1/pages/{page_id}" \
|
||||
-H "Authorization: Bearer $NOTION_KEY" \
|
||||
-H "Notion-Version: 2025-09-03"
|
||||
```
|
||||
|
||||
**Get page content (blocks):**
|
||||
|
||||
```bash
|
||||
curl "https://api.notion.com/v1/blocks/{page_id}/children" \
|
||||
-H "Authorization: Bearer $NOTION_KEY" \
|
||||
-H "Notion-Version: 2025-09-03"
|
||||
```
|
||||
|
||||
**Create page in a data source:**
|
||||
|
||||
```bash
|
||||
curl -X POST "https://api.notion.com/v1/pages" \
|
||||
-H "Authorization: Bearer $NOTION_KEY" \
|
||||
-H "Notion-Version: 2025-09-03" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"parent": {"database_id": "xxx"},
|
||||
"properties": {
|
||||
"Name": {"title": [{"text": {"content": "New Item"}}]},
|
||||
"Status": {"select": {"name": "Todo"}}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
**Query a data source (database):**
|
||||
|
||||
```bash
|
||||
curl -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \
|
||||
-H "Authorization: Bearer $NOTION_KEY" \
|
||||
-H "Notion-Version: 2025-09-03" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"filter": {"property": "Status", "select": {"equals": "Active"}},
|
||||
"sorts": [{"property": "Date", "direction": "descending"}]
|
||||
}'
|
||||
```
|
||||
|
||||
**Create a data source (database):**
|
||||
|
||||
```bash
|
||||
curl -X POST "https://api.notion.com/v1/data_sources" \
|
||||
-H "Authorization: Bearer $NOTION_KEY" \
|
||||
-H "Notion-Version: 2025-09-03" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"parent": {"page_id": "xxx"},
|
||||
"title": [{"text": {"content": "My Database"}}],
|
||||
"properties": {
|
||||
"Name": {"title": {}},
|
||||
"Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}},
|
||||
"Date": {"date": {}}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
**Update page properties:**
|
||||
|
||||
```bash
|
||||
curl -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
|
||||
-H "Authorization: Bearer $NOTION_KEY" \
|
||||
-H "Notion-Version: 2025-09-03" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"properties": {"Status": {"select": {"name": "Done"}}}}'
|
||||
```
|
||||
|
||||
**Add blocks to page:**
|
||||
|
||||
```bash
|
||||
curl -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \
|
||||
-H "Authorization: Bearer $NOTION_KEY" \
|
||||
-H "Notion-Version: 2025-09-03" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"children": [
|
||||
{"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello"}}]}}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
## Property Types
|
||||
|
||||
Common property formats for database items:
|
||||
|
||||
- **Title:** `{"title": [{"text": {"content": "..."}}]}`
|
||||
- **Rich text:** `{"rich_text": [{"text": {"content": "..."}}]}`
|
||||
- **Select:** `{"select": {"name": "Option"}}`
|
||||
- **Multi-select:** `{"multi_select": [{"name": "A"}, {"name": "B"}]}`
|
||||
- **Date:** `{"date": {"start": "2024-01-15", "end": "2024-01-16"}}`
|
||||
- **Checkbox:** `{"checkbox": true}`
|
||||
- **Number:** `{"number": 42}`
|
||||
- **URL:** `{"url": "https://..."}`
|
||||
- **Email:** `{"email": "a@b.com"}`
|
||||
- **Relation:** `{"relation": [{"id": "page_id"}]}`
|
||||
|
||||
## Key Differences in 2025-09-03
|
||||
|
||||
- **Databases → Data Sources:** Use `/data_sources/` endpoints for queries and retrieval
|
||||
- **Two IDs:** Each database now has both a `database_id` and a `data_source_id`
|
||||
- Use `database_id` when creating pages (`parent: {"database_id": "..."}`)
|
||||
- Use `data_source_id` when querying (`POST /v1/data_sources/{id}/query`)
|
||||
- **Search results:** Databases return as `"object": "data_source"` with their `data_source_id`
|
||||
- **Parent in responses:** Pages show `parent.data_source_id` alongside `parent.database_id`
|
||||
- **Finding the data_source_id:** Search for the database, or call `GET /v1/data_sources/{data_source_id}`
|
||||
|
||||
## Notes
|
||||
|
||||
- Page/database IDs are UUIDs (with or without dashes)
|
||||
- The API cannot set database view filters — that's UI-only
|
||||
- Rate limit: ~3 requests/second average, with `429 rate_limited` responses using `Retry-After`
|
||||
- Append block children: up to 100 children per request, up to two levels of nesting in a single append request
|
||||
- Payload size limits: up to 1000 block elements and 500KB overall
|
||||
- Use `is_inline: true` when creating data sources to embed them in pages
|
||||
- Current latest API version: `2026-03-11`.
|
||||
- Use `in_trash`, not `archived`.
|
||||
- Append block positioning uses `position`, not flat `after`.
|
||||
- `transcription` block renamed to `meeting_notes`.
|
||||
- Databases can contain multiple data sources; page parents generally use `data_source_id`.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: obsidian
|
||||
description: Work with Obsidian vaults (plain Markdown notes) and automate via obsidian-cli.
|
||||
description: "Work with Obsidian vaults (plain Markdown notes) and automate via obsidian-cli."
|
||||
homepage: https://help.obsidian.md
|
||||
metadata:
|
||||
{
|
||||
@@ -29,7 +29,7 @@ Obsidian vault = a normal folder on disk.
|
||||
Vault structure (typical)
|
||||
|
||||
- Notes: `*.md` (plain text Markdown; edit with any editor)
|
||||
- Config: `.obsidian/` (workspace + plugin settings; usually don’t touch from scripts)
|
||||
- Config: `.obsidian/` (workspace + plugin settings; usually don't touch from scripts)
|
||||
- Canvases: `*.canvas` (JSON)
|
||||
- Attachments: whatever folder you chose in Obsidian settings (images/PDFs/etc.)
|
||||
|
||||
@@ -41,14 +41,14 @@ Obsidian desktop tracks vaults here (source of truth):
|
||||
|
||||
`obsidian-cli` resolves vaults from that file; vault name is typically the **folder name** (path suffix).
|
||||
|
||||
Fast “what vault is active / where are the notes?”
|
||||
Fast "what vault is active / where are the notes?"
|
||||
|
||||
- If you’ve already set a default: `obsidian-cli print-default --path-only`
|
||||
- If you've already set a default: `obsidian-cli print-default --path-only`
|
||||
- Otherwise, read `~/Library/Application Support/obsidian/obsidian.json` and use the vault entry with `"open": true`.
|
||||
|
||||
Notes
|
||||
|
||||
- Multiple vaults common (iCloud vs `~/Documents`, work/personal, etc.). Don’t guess; read config.
|
||||
- Multiple vaults common (iCloud vs `~/Documents`, work/personal, etc.). Don't guess; read config.
|
||||
- Avoid writing hardcoded vault paths into scripts; prefer reading the config or using `print-default`.
|
||||
|
||||
## obsidian-cli quick start
|
||||
@@ -67,7 +67,7 @@ Create
|
||||
|
||||
- `obsidian-cli create "Folder/New note" --content "..." --open`
|
||||
- Requires Obsidian URI handler (`obsidian://…`) working (Obsidian installed).
|
||||
- Avoid creating notes under “hidden” dot-folders (e.g. `.something/...`) via URI; Obsidian may refuse.
|
||||
- Avoid creating notes under "hidden" dot-folders (e.g. `.something/...`) via URI; Obsidian may refuse.
|
||||
|
||||
Move/rename (safe refactor)
|
||||
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
---
|
||||
name: openai-whisper-api
|
||||
description: Transcribe audio via OpenAI Audio Transcriptions API (Whisper).
|
||||
description: "OpenAI Audio Transcriptions API via curl; gpt-4o-transcribe, mini, diarize, or whisper-1."
|
||||
homepage: https://platform.openai.com/docs/guides/speech-to-text
|
||||
metadata:
|
||||
{
|
||||
"openclaw":
|
||||
{
|
||||
"emoji": "🌐",
|
||||
"requires": { "bins": ["curl"], "env": ["OPENAI_API_KEY"] },
|
||||
"requires": { "bins": ["curl", "node"], "env": ["OPENAI_API_KEY"] },
|
||||
"primaryEnv": "OPENAI_API_KEY",
|
||||
"install":
|
||||
[
|
||||
@@ -23,9 +23,9 @@ metadata:
|
||||
}
|
||||
---
|
||||
|
||||
# OpenAI Whisper API (curl)
|
||||
# OpenAI transcriptions API
|
||||
|
||||
Transcribe an audio file via OpenAI’s `/v1/audio/transcriptions` endpoint. Set `OPENAI_BASE_URL` to use an OpenAI-compatible proxy or local gateway.
|
||||
Transcribe audio through `/v1/audio/transcriptions`. Set `OPENAI_BASE_URL` for an OpenAI-compatible proxy or local gateway.
|
||||
|
||||
## Quick start
|
||||
|
||||
@@ -35,21 +35,30 @@ Transcribe an audio file via OpenAI’s `/v1/audio/transcriptions` endpoint. Set
|
||||
|
||||
Defaults:
|
||||
|
||||
- Model: `whisper-1`
|
||||
- Model: `gpt-4o-transcribe`
|
||||
- Output: `<input>.txt`
|
||||
|
||||
## Useful flags
|
||||
|
||||
```bash
|
||||
{baseDir}/scripts/transcribe.sh /path/to/audio.ogg --model whisper-1 --out /tmp/transcript.txt
|
||||
{baseDir}/scripts/transcribe.sh /path/to/audio.ogg --model gpt-4o-transcribe --out /tmp/transcript.txt
|
||||
{baseDir}/scripts/transcribe.sh /path/to/audio.ogg --model gpt-4o-mini-transcribe
|
||||
{baseDir}/scripts/transcribe.sh /path/to/audio.ogg --model gpt-4o-transcribe-diarize --json
|
||||
{baseDir}/scripts/transcribe.sh /path/to/audio.ogg --model whisper-1
|
||||
{baseDir}/scripts/transcribe.sh /path/to/audio.m4a --language en
|
||||
{baseDir}/scripts/transcribe.sh /path/to/audio.m4a --prompt "Speaker names: Peter, Daniel"
|
||||
{baseDir}/scripts/transcribe.sh /path/to/audio.m4a --json --out /tmp/transcript.json
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- Supported upload formats include `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`.
|
||||
- 25 MB upload limit on the hosted API.
|
||||
- Use diarize for speaker labels; script sends `chunking_strategy=auto` and rejects `--prompt`.
|
||||
|
||||
## API key
|
||||
|
||||
Set `OPENAI_API_KEY`, or configure it in the active OpenClaw config file (`$OPENCLAW_CONFIG_PATH`, default `~/.openclaw/openclaw.json`). Optionally set `OPENAI_BASE_URL` (for example `http://127.0.0.1:51805/v1`) to use an OpenAI-compatible proxy or local gateway:
|
||||
Set `OPENAI_API_KEY`, or configure it in the active OpenClaw config file (`$OPENCLAW_CONFIG_PATH`, default `~/.openclaw/openclaw.json`). Optionally set `OPENAI_BASE_URL`:
|
||||
|
||||
```json5
|
||||
{
|
||||
|
||||
@@ -4,7 +4,7 @@ set -euo pipefail
|
||||
usage() {
|
||||
cat >&2 <<'EOF'
|
||||
Usage:
|
||||
transcribe.sh <audio-file> [--model whisper-1] [--out /path/to/out.txt] [--language en] [--prompt "hint"] [--json]
|
||||
transcribe.sh <audio-file> [--model gpt-4o-transcribe] [--out /path/to/out.txt] [--language en] [--prompt "hint"] [--json]
|
||||
EOF
|
||||
exit 2
|
||||
}
|
||||
@@ -16,11 +16,11 @@ fi
|
||||
in="${1:-}"
|
||||
shift || true
|
||||
|
||||
model="whisper-1"
|
||||
model="gpt-4o-transcribe"
|
||||
out=""
|
||||
language=""
|
||||
prompt=""
|
||||
response_format="text"
|
||||
json_output=0
|
||||
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
@@ -41,7 +41,7 @@ while [[ $# -gt 0 ]]; do
|
||||
shift 2
|
||||
;;
|
||||
--json)
|
||||
response_format="json"
|
||||
json_output=1
|
||||
shift 1
|
||||
;;
|
||||
*)
|
||||
@@ -63,7 +63,7 @@ fi
|
||||
|
||||
if [[ "$out" == "" ]]; then
|
||||
base="${in%.*}"
|
||||
if [[ "$response_format" == "json" ]]; then
|
||||
if [[ "$json_output" == "1" ]]; then
|
||||
out="${base}.json"
|
||||
else
|
||||
out="${base}.txt"
|
||||
@@ -75,14 +75,80 @@ mkdir -p "$(dirname "$out")"
|
||||
api_base="${OPENAI_BASE_URL:-https://api.openai.com/v1}"
|
||||
api_base="${api_base%/}"
|
||||
|
||||
curl -sS "${api_base}/audio/transcriptions" \
|
||||
-H "Authorization: Bearer $OPENAI_API_KEY" \
|
||||
-H "Accept: application/json" \
|
||||
-F "file=@${in}" \
|
||||
-F "model=${model}" \
|
||||
-F "response_format=${response_format}" \
|
||||
${language:+-F "language=${language}"} \
|
||||
${prompt:+-F "prompt=${prompt}"} \
|
||||
>"$out"
|
||||
request_format="text"
|
||||
if [[ "$json_output" == "1" ]]; then
|
||||
request_format="json"
|
||||
fi
|
||||
|
||||
diarize=0
|
||||
case "$model" in
|
||||
gpt-4o-transcribe | gpt-4o-mini-transcribe | gpt-4o-mini-transcribe-*)
|
||||
request_format="json"
|
||||
;;
|
||||
gpt-4o-transcribe-diarize)
|
||||
diarize=1
|
||||
request_format="diarized_json"
|
||||
;;
|
||||
esac
|
||||
|
||||
if [[ "$diarize" == "1" && "$prompt" != "" ]]; then
|
||||
echo "--prompt is not supported with gpt-4o-transcribe-diarize" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
target="$out"
|
||||
tmp=""
|
||||
if [[ "$json_output" == "0" && ( "$request_format" == "json" || "$request_format" == "diarized_json" ) ]]; then
|
||||
tmp="$(mktemp)"
|
||||
trap '[[ "$tmp" == "" ]] || rm -f "$tmp"' EXIT
|
||||
target="$tmp"
|
||||
fi
|
||||
|
||||
curl_args=(
|
||||
-sS "${api_base}/audio/transcriptions"
|
||||
-H "Authorization: Bearer $OPENAI_API_KEY"
|
||||
-H "Accept: application/json"
|
||||
-F "file=@${in}"
|
||||
-F "model=${model}"
|
||||
-F "response_format=${request_format}"
|
||||
)
|
||||
if [[ "$language" != "" ]]; then
|
||||
curl_args+=(-F "language=${language}")
|
||||
fi
|
||||
if [[ "$prompt" != "" ]]; then
|
||||
curl_args+=(-F "prompt=${prompt}")
|
||||
fi
|
||||
if [[ "$diarize" == "1" ]]; then
|
||||
curl_args+=(-F "chunking_strategy=auto")
|
||||
fi
|
||||
|
||||
curl "${curl_args[@]}" >"$target"
|
||||
|
||||
if [[ "$target" != "$out" ]]; then
|
||||
node -e '
|
||||
const fs = require("fs");
|
||||
const input = process.argv[1];
|
||||
const output = process.argv[2];
|
||||
const payload = JSON.parse(fs.readFileSync(input, "utf8"));
|
||||
if (Array.isArray(payload.segments)) {
|
||||
const lines = payload.segments
|
||||
.map((segment) => {
|
||||
const text = typeof segment?.text === "string" ? segment.text.trim() : "";
|
||||
if (!text) return "";
|
||||
const speaker = typeof segment?.speaker === "string" ? segment.speaker.trim() : "";
|
||||
return speaker ? `${speaker}: ${text}` : text;
|
||||
})
|
||||
.filter(Boolean);
|
||||
if (lines.length > 0) {
|
||||
fs.writeFileSync(output, lines.join("\n"));
|
||||
process.exit(0);
|
||||
}
|
||||
}
|
||||
if (typeof payload.text !== "string") {
|
||||
throw new Error("Transcription response missing text");
|
||||
}
|
||||
fs.writeFileSync(output, payload.text);
|
||||
' "$target" "$out"
|
||||
fi
|
||||
|
||||
echo "$out"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: openai-whisper
|
||||
description: Local speech-to-text with the Whisper CLI (no API key).
|
||||
description: "Local speech-to-text with the Whisper CLI (no API key)."
|
||||
homepage: https://openai.com/research/whisper
|
||||
metadata:
|
||||
{
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: openhue
|
||||
description: Control Philips Hue lights and scenes via the OpenHue CLI.
|
||||
description: "Control Philips Hue lights and scenes via the OpenHue CLI."
|
||||
homepage: https://www.openhue.io/cli
|
||||
metadata:
|
||||
{
|
||||
@@ -28,7 +28,7 @@ Use `openhue` to control Philips Hue lights and scenes via a Hue Bridge.
|
||||
|
||||
## When to Use
|
||||
|
||||
✅ **USE this skill when:**
|
||||
Use when:
|
||||
|
||||
- "Turn on/off the lights"
|
||||
- "Dim the living room lights"
|
||||
@@ -38,10 +38,10 @@ Use `openhue` to control Philips Hue lights and scenes via a Hue Bridge.
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
❌ **DON'T use this skill when:**
|
||||
Do not use when:
|
||||
|
||||
- Non-Hue smart devices (other brands) → not supported
|
||||
- HomeKit scenes or Shortcuts → use Apple's ecosystem
|
||||
- Non-Hue smart devices (other brands) -> not supported
|
||||
- HomeKit scenes or Shortcuts -> use Apple's ecosystem
|
||||
- TV or entertainment system control
|
||||
- Thermostat or HVAC
|
||||
- Smart plugs (unless Hue smart plugs)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: oracle
|
||||
description: Use oracle CLI to bundle prompts and files for second-model debugging, refactor, design, or review checks.
|
||||
description: "Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine."
|
||||
homepage: https://askoracle.dev
|
||||
metadata:
|
||||
{
|
||||
@@ -22,31 +22,32 @@ metadata:
|
||||
}
|
||||
---
|
||||
|
||||
# oracle — best use
|
||||
# oracle
|
||||
|
||||
Oracle bundles your prompt + selected files into one “one-shot” request so another model can answer with real repo context (API or browser automation). Treat output as advisory: verify against code + tests.
|
||||
Oracle bundles a prompt + selected files for one second-model pass. Treat output as advisory; verify against code + tests.
|
||||
|
||||
## Main use case (browser, GPT‑5.2 Pro)
|
||||
## Main path
|
||||
|
||||
Default workflow here: `--engine browser` with GPT‑5.2 Pro in ChatGPT. This is the common “long think” path: ~10 minutes to ~1 hour is normal; expect a stored session you can reattach to.
|
||||
Current CLI default model: `gpt-5.5-pro`. Browser engine is useful for long ChatGPT Pro runs; API engine is useful when `OPENAI_API_KEY` or Azure config is ready.
|
||||
|
||||
Recommended defaults:
|
||||
|
||||
- Engine: browser (`--engine browser`)
|
||||
- Model: GPT‑5.2 Pro (`--model gpt-5.2-pro` or `--model "5.2 Pro"`)
|
||||
- Preview first: `--dry-run summary --files-report`
|
||||
- Browser long run: `--engine browser --model gpt-5.5-pro`
|
||||
- API explicit: `--engine api --model gpt-5.5`
|
||||
|
||||
## Golden path
|
||||
|
||||
1. Pick a tight file set (fewest files that still contain the truth).
|
||||
2. Preview payload + token spend (`--dry-run` + `--files-report`).
|
||||
3. Use browser mode for the usual GPT‑5.2 Pro workflow; use API only when you explicitly want it.
|
||||
4. If the run detaches/timeouts: reattach to the stored session (don’t re-run).
|
||||
3. Use browser mode for long Pro thinking; API mode for explicit API calls.
|
||||
4. If the run detaches/timeouts: reattach to the stored session. Do not blindly re-run.
|
||||
|
||||
## Commands (preferred)
|
||||
|
||||
- Help:
|
||||
- `oracle --help`
|
||||
- If the binary isn’t installed: `npx -y @steipete/oracle --help` (avoid `pnpx` here; sqlite bindings).
|
||||
- If the binary isn't installed: `npx -y @steipete/oracle --help` (avoid `pnpx` here; sqlite bindings).
|
||||
|
||||
- Preview (no tokens):
|
||||
- `oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"`
|
||||
@@ -56,7 +57,7 @@ Recommended defaults:
|
||||
- `oracle --dry-run summary --files-report -p "<task>" --file "src/**"`
|
||||
|
||||
- Browser run (main path; long-running is normal):
|
||||
- `oracle --engine browser --model gpt-5.2-pro -p "<task>" --file "src/**"`
|
||||
- `oracle --engine browser --model gpt-5.5-pro -p "<task>" --file "src/**"`
|
||||
|
||||
- Manual paste fallback:
|
||||
- `oracle --render --copy -p "<task>" --file "src/**"`
|
||||
@@ -94,7 +95,7 @@ Recommended defaults:
|
||||
## Sessions + slugs
|
||||
|
||||
- Stored under `~/.oracle/sessions` (override with `ORACLE_HOME_DIR`).
|
||||
- Runs may detach or take a long time (browser + GPT‑5.2 Pro often does). If the CLI times out: don’t re-run; reattach.
|
||||
- Runs may detach or take a long time (browser + Pro often does). If the CLI times out: do not re-run; reattach.
|
||||
- List: `oracle status --hours 72`
|
||||
- Attach: `oracle session <id> --render`
|
||||
- Use `--slug "<3-5 words>"` to keep session IDs readable.
|
||||
@@ -102,24 +103,24 @@ Recommended defaults:
|
||||
|
||||
## Prompt template (high signal)
|
||||
|
||||
Oracle starts with **zero** project knowledge. Assume the model cannot infer your stack, build tooling, conventions, or “obvious” paths. Include:
|
||||
Oracle starts with **zero** project knowledge. Assume the model cannot infer your stack, build tooling, conventions, or "obvious" paths. Include:
|
||||
|
||||
- Project briefing (stack + build/test commands + platform constraints).
|
||||
- “Where things live” (key directories, entrypoints, config files, boundaries).
|
||||
- "Where things live" (key directories, entrypoints, config files, boundaries).
|
||||
- Exact question + what you tried + the error text (verbatim).
|
||||
- Constraints (“don’t change X”, “must keep public API”, etc).
|
||||
- Desired output (“return patch plan + tests”, “give 3 options with tradeoffs”).
|
||||
- Constraints ("don't change X", "must keep public API", etc).
|
||||
- Desired output ("return patch plan + tests", "give 3 options with tradeoffs").
|
||||
|
||||
## Safety
|
||||
|
||||
- Don’t attach secrets by default (`.env`, key files, auth tokens). Redact aggressively; share only what’s required.
|
||||
- Don't attach secrets by default (`.env`, key files, auth tokens). Redact aggressively; share only what's required.
|
||||
|
||||
## “Exhaustive prompt” restoration pattern
|
||||
## "Exhaustive prompt" restoration pattern
|
||||
|
||||
For long investigations, write a standalone prompt + file set so you can rerun days later:
|
||||
|
||||
- 6–30 sentence project briefing + the goal.
|
||||
- 6-30 sentence project briefing + the goal.
|
||||
- Repro steps + exact errors + what you tried.
|
||||
- Attach all context files needed (entrypoints, configs, key modules, docs).
|
||||
|
||||
Oracle runs are one-shot; the model doesn’t remember prior runs. “Restoring context” means re-running with the same prompt + `--file …` set (or reattaching a still-running stored session).
|
||||
Oracle runs are one-shot; the model doesn't remember prior runs. "Restoring context" means re-running with the same prompt + `--file …` set (or reattaching a still-running stored session).
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: ordercli
|
||||
description: Foodora-only CLI for checking past orders and active order status (Deliveroo WIP).
|
||||
description: "Foodora-only CLI for checking past orders and active order status (Deliveroo WIP)."
|
||||
homepage: https://ordercli.sh
|
||||
metadata:
|
||||
{
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: peekaboo
|
||||
description: Capture and automate macOS UI with the Peekaboo CLI.
|
||||
description: "Capture and automate macOS UI with the Peekaboo CLI."
|
||||
homepage: https://peekaboo.boo
|
||||
metadata:
|
||||
{
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: sag
|
||||
description: ElevenLabs text-to-speech with mac-style say UX.
|
||||
description: "ElevenLabs text-to-speech with mac-style say UX."
|
||||
homepage: https://sag.sh
|
||||
metadata:
|
||||
{
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: session-logs
|
||||
description: Search and analyze your own session logs (older/parent conversations) using jq.
|
||||
description: "Search and analyze your own session logs (older/parent conversations) using jq."
|
||||
metadata:
|
||||
{
|
||||
"openclaw":
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: sherpa-onnx-tts
|
||||
description: Local text-to-speech via sherpa-onnx (offline, no cloud)
|
||||
description: "Local text-to-speech via sherpa-onnx (offline, no cloud)"
|
||||
metadata:
|
||||
{
|
||||
"openclaw":
|
||||
@@ -14,7 +14,7 @@ metadata:
|
||||
"id": "download-runtime-macos",
|
||||
"kind": "download",
|
||||
"os": ["darwin"],
|
||||
"url": "https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.23/sherpa-onnx-v1.12.23-osx-universal2-shared.tar.bz2",
|
||||
"url": "https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.13.2/sherpa-onnx-v1.13.2-osx-universal2-shared.tar.bz2",
|
||||
"archive": "tar.bz2",
|
||||
"extract": true,
|
||||
"stripComponents": 1,
|
||||
@@ -25,7 +25,7 @@ metadata:
|
||||
"id": "download-runtime-linux-x64",
|
||||
"kind": "download",
|
||||
"os": ["linux"],
|
||||
"url": "https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.23/sherpa-onnx-v1.12.23-linux-x64-shared.tar.bz2",
|
||||
"url": "https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.13.2/sherpa-onnx-v1.13.2-linux-x64-shared.tar.bz2",
|
||||
"archive": "tar.bz2",
|
||||
"extract": true,
|
||||
"stripComponents": 1,
|
||||
@@ -36,7 +36,7 @@ metadata:
|
||||
"id": "download-runtime-win-x64",
|
||||
"kind": "download",
|
||||
"os": ["win32"],
|
||||
"url": "https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.23/sherpa-onnx-v1.12.23-win-x64-shared.tar.bz2",
|
||||
"url": "https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.13.2/sherpa-onnx-v1.13.2-win-x64-shared-MD-Release.tar.bz2",
|
||||
"archive": "tar.bz2",
|
||||
"extract": true,
|
||||
"stripComponents": 1,
|
||||
|
||||
@@ -1,372 +1,78 @@
|
||||
---
|
||||
name: skill-creator
|
||||
description: Create, edit, improve, tidy, review, audit, or restructure AgentSkills and SKILL.md files.
|
||||
description: "Create, edit, audit, tidy, validate, or restructure AgentSkills and SKILL.md files."
|
||||
---
|
||||
|
||||
# Skill Creator
|
||||
|
||||
This skill provides guidance for creating effective skills.
|
||||
Skills are compact triggerable workflows. Metadata is always visible; body loads only after trigger; references/scripts/assets load only as needed.
|
||||
|
||||
## About Skills
|
||||
## Hard rules
|
||||
|
||||
Skills are modular, self-contained packages that extend Codex's capabilities by providing
|
||||
specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
|
||||
domains or tasks—they transform Codex from a general-purpose agent into a specialized agent
|
||||
equipped with procedural knowledge that no model can fully possess.
|
||||
- Keep `SKILL.md` lean; Codex is already capable.
|
||||
- Put only trigger-critical facts in frontmatter `description`.
|
||||
- Quote frontmatter `description`.
|
||||
- Frontmatter needs `name` + `description`; local OpenClaw skills may also use `metadata`, `homepage`, `allowed-tools`, `user-invocable`, `license`.
|
||||
- Prefer noun-phrase descriptions; short generic trigger phrase, not full workflow.
|
||||
- Move long examples/docs to `references/`; scripts to `scripts/`; templates/media to `assets/`.
|
||||
- No extra README/changelog/setup docs inside a skill unless they are actual task references.
|
||||
- Validate YAML frontmatter after edits.
|
||||
|
||||
### What Skills Provide
|
||||
## Shape
|
||||
|
||||
1. Specialized workflows - Multi-step procedures for specific domains
|
||||
2. Tool integrations - Instructions for working with specific file formats or APIs
|
||||
3. Domain expertise - Company-specific knowledge, schemas, business logic
|
||||
4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
|
||||
|
||||
## Core Principles
|
||||
|
||||
### Concise is Key
|
||||
|
||||
The context window is a public good. Skills share the context window with everything else Codex needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
|
||||
|
||||
**Default assumption: Codex is already very smart.** Only add context Codex doesn't already have. Challenge each piece of information: "Does Codex really need this explanation?" and "Does this paragraph justify its token cost?"
|
||||
|
||||
Prefer concise examples over verbose explanations.
|
||||
|
||||
### Set Appropriate Degrees of Freedom
|
||||
|
||||
Match the level of specificity to the task's fragility and variability:
|
||||
|
||||
**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.
|
||||
|
||||
**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
|
||||
|
||||
**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
|
||||
|
||||
Think of Codex as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
|
||||
|
||||
### Anatomy of a Skill
|
||||
|
||||
Every skill consists of a required SKILL.md file and optional bundled resources:
|
||||
|
||||
```
|
||||
```text
|
||||
skill-name/
|
||||
├── SKILL.md (required)
|
||||
│ ├── YAML frontmatter metadata (required)
|
||||
│ │ ├── name: (required)
|
||||
│ │ └── description: (required)
|
||||
│ └── Markdown instructions (required)
|
||||
└── Bundled Resources (optional)
|
||||
├── scripts/ - Executable code (Python/Bash/etc.)
|
||||
├── references/ - Documentation intended to be loaded into context as needed
|
||||
└── assets/ - Files used in output (templates, icons, fonts, etc.)
|
||||
SKILL.md
|
||||
scripts/ optional deterministic helpers
|
||||
references/ optional docs loaded only when needed
|
||||
assets/ optional output resources/templates
|
||||
agents/ optional UI metadata
|
||||
```
|
||||
|
||||
#### SKILL.md (required)
|
||||
|
||||
Every SKILL.md consists of:
|
||||
|
||||
- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that Codex reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.
|
||||
- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
|
||||
|
||||
#### Bundled Resources (optional)
|
||||
|
||||
##### Scripts (`scripts/`)
|
||||
|
||||
Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
|
||||
|
||||
- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
|
||||
- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
|
||||
- **Benefits**: Token efficient, deterministic, may be executed without loading into context
|
||||
- **Note**: Scripts may still need to be read by Codex for patching or environment-specific adjustments
|
||||
|
||||
##### References (`references/`)
|
||||
|
||||
Documentation and reference material intended to be loaded as needed into context to inform Codex's process and thinking.
|
||||
|
||||
- **When to include**: For documentation that Codex should reference while working
|
||||
- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications
|
||||
- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
|
||||
- **Benefits**: Keeps SKILL.md lean, loaded only when Codex determines it's needed
|
||||
- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
|
||||
- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
|
||||
|
||||
##### Assets (`assets/`)
|
||||
|
||||
Files not intended to be loaded into context, but rather used within the output Codex produces.
|
||||
|
||||
- **When to include**: When the skill needs files that will be used in the final output
|
||||
- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography
|
||||
- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
|
||||
- **Benefits**: Separates output resources from documentation, enables Codex to use files without loading them into context
|
||||
|
||||
#### What to Not Include in a Skill
|
||||
|
||||
A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:
|
||||
|
||||
- README.md
|
||||
- INSTALLATION_GUIDE.md
|
||||
- QUICK_REFERENCE.md
|
||||
- CHANGELOG.md
|
||||
- etc.
|
||||
|
||||
The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxiliary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
|
||||
|
||||
### Progressive Disclosure Design Principle
|
||||
|
||||
Skills use a three-level loading system to manage context efficiently:
|
||||
|
||||
1. **Metadata (name + description)** - Always in context (~100 words)
|
||||
2. **SKILL.md body** - When skill triggers (<5k words)
|
||||
3. **Bundled resources** - As needed by Codex (Unlimited because scripts can be executed without reading into context window)
|
||||
|
||||
#### Progressive Disclosure Patterns
|
||||
|
||||
Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.
|
||||
|
||||
**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.
|
||||
|
||||
**Pattern 1: High-level guide with references**
|
||||
## Good SKILL.md
|
||||
|
||||
```markdown
|
||||
# PDF Processing
|
||||
---
|
||||
name: pdf-tools
|
||||
description: "Inspect, split, merge, OCR, redact, or convert PDFs with local CLI tools."
|
||||
---
|
||||
|
||||
## Quick start
|
||||
# PDF tools
|
||||
|
||||
Extract text with pdfplumber:
|
||||
[code example]
|
||||
Use for PDF manipulation. Prefer deterministic scripts for page edits.
|
||||
|
||||
## Advanced features
|
||||
## Workflow
|
||||
|
||||
- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
|
||||
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
|
||||
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
|
||||
1. Inspect file/page count.
|
||||
2. Choose exact operation.
|
||||
3. Write output beside input unless user asked otherwise.
|
||||
4. Render/verify changed pages.
|
||||
```
|
||||
|
||||
Codex loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
|
||||
## Edit workflow
|
||||
|
||||
**Pattern 2: Domain-specific organization**
|
||||
1. Read existing skill and nearby resource names.
|
||||
2. Remove generic advice the base model already knows.
|
||||
3. Keep brittle command syntax, auth caveats, safety rules, and validation.
|
||||
4. Replace tables with bullets unless a table is clearly needed.
|
||||
5. Relax prose; fragments ok.
|
||||
6. Validate frontmatter and run any script tests touched.
|
||||
|
||||
For Skills with multiple domains, organize content by domain to avoid loading irrelevant context:
|
||||
|
||||
```
|
||||
bigquery-skill/
|
||||
├── SKILL.md (overview and navigation)
|
||||
└── reference/
|
||||
├── finance.md (revenue, billing metrics)
|
||||
├── sales.md (opportunities, pipeline)
|
||||
├── product.md (API usage, features)
|
||||
└── marketing.md (campaigns, attribution)
|
||||
```
|
||||
|
||||
When a user asks about sales metrics, Codex only reads sales.md.
|
||||
|
||||
Similarly, for skills supporting multiple frameworks or variants, organize by variant:
|
||||
|
||||
```
|
||||
cloud-deploy/
|
||||
├── SKILL.md (workflow + provider selection)
|
||||
└── references/
|
||||
├── aws.md (AWS deployment patterns)
|
||||
├── gcp.md (GCP deployment patterns)
|
||||
└── azure.md (Azure deployment patterns)
|
||||
```
|
||||
|
||||
When the user chooses AWS, Codex only reads aws.md.
|
||||
|
||||
**Pattern 3: Conditional details**
|
||||
|
||||
Show basic content, link to advanced content:
|
||||
|
||||
```markdown
|
||||
# DOCX Processing
|
||||
|
||||
## Creating documents
|
||||
|
||||
Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
|
||||
|
||||
## Editing documents
|
||||
|
||||
For simple edits, modify the XML directly.
|
||||
|
||||
**For tracked changes**: See [REDLINING.md](REDLINING.md)
|
||||
**For OOXML details**: See [OOXML.md](OOXML.md)
|
||||
```
|
||||
|
||||
Codex reads REDLINING.md or OOXML.md only when the user needs those features.
|
||||
|
||||
**Important guidelines:**
|
||||
|
||||
- **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.
|
||||
- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so Codex can see the full scope when previewing.
|
||||
|
||||
## Skill Creation Process
|
||||
|
||||
Skill creation involves these steps:
|
||||
|
||||
1. Understand the skill with concrete examples
|
||||
2. Plan reusable skill contents (scripts, references, assets)
|
||||
3. Initialize the skill (run init_skill.py)
|
||||
4. Edit the skill (implement resources and write SKILL.md)
|
||||
5. Package the skill (run package_skill.py)
|
||||
6. Iterate based on real usage
|
||||
|
||||
Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
|
||||
|
||||
### Skill Naming
|
||||
|
||||
- Use lowercase letters, digits, and hyphens only; normalize user-provided titles to hyphen-case (e.g., "Plan Mode" -> `plan-mode`).
|
||||
- When generating names, generate a name under 64 characters (letters, digits, hyphens).
|
||||
- Prefer short, verb-led phrases that describe the action.
|
||||
- Namespace by tool when it improves clarity or triggering (e.g., `gh-address-comments`, `linear-address-issue`).
|
||||
- Name the skill folder exactly after the skill name.
|
||||
|
||||
### Step 1: Understanding the Skill with Concrete Examples
|
||||
|
||||
Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
|
||||
|
||||
To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
|
||||
|
||||
For example, when building an image-editor skill, relevant questions include:
|
||||
|
||||
- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
|
||||
- "Can you give some examples of how this skill would be used?"
|
||||
- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
|
||||
- "What would a user say that should trigger this skill?"
|
||||
|
||||
To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
|
||||
|
||||
Conclude this step when there is a clear sense of the functionality the skill should support.
|
||||
|
||||
### Step 2: Planning the Reusable Skill Contents
|
||||
|
||||
To turn concrete examples into an effective skill, analyze each example by:
|
||||
|
||||
1. Considering how to execute on the example from scratch
|
||||
2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
|
||||
|
||||
Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows:
|
||||
|
||||
1. Rotating a PDF requires re-writing the same code each time
|
||||
2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill
|
||||
|
||||
Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
|
||||
|
||||
1. Writing a frontend webapp requires the same boilerplate HTML/React each time
|
||||
2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill
|
||||
|
||||
Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows:
|
||||
|
||||
1. Querying BigQuery requires re-discovering the table schemas and relationships each time
|
||||
2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill
|
||||
|
||||
To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
|
||||
|
||||
### Step 3: Initializing the Skill
|
||||
|
||||
At this point, it is time to actually create the skill.
|
||||
|
||||
Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.
|
||||
|
||||
When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
|
||||
|
||||
Usage:
|
||||
## Validation
|
||||
|
||||
```bash
|
||||
scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]
|
||||
python skills/skill-creator/scripts/quick_validate.py skills/<name>
|
||||
python - <<'PY'
|
||||
from pathlib import Path
|
||||
import yaml
|
||||
for p in Path("skills").glob("*/SKILL.md"):
|
||||
text=p.read_text()
|
||||
if not text.startswith("---\n"):
|
||||
raise SystemExit(f"missing frontmatter: {p}")
|
||||
fm=text.split("---",2)[1]
|
||||
yaml.safe_load(fm)
|
||||
print("ok")
|
||||
PY
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
scripts/init_skill.py my-skill --path skills/public
|
||||
scripts/init_skill.py my-skill --path skills/public --resources scripts,references
|
||||
scripts/init_skill.py my-skill --path skills/public --resources scripts --examples
|
||||
```
|
||||
|
||||
The script:
|
||||
|
||||
- Creates the skill directory at the specified path
|
||||
- Generates a SKILL.md template with proper frontmatter and TODO placeholders
|
||||
- Optionally creates resource directories based on `--resources`
|
||||
- Optionally adds example files when `--examples` is set
|
||||
|
||||
After initialization, customize the SKILL.md and add resources as needed. If you used `--examples`, replace or delete placeholder files.
|
||||
|
||||
### Step 4: Edit the Skill
|
||||
|
||||
When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Codex to use. Include information that would be beneficial and non-obvious to Codex. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Codex instance execute these tasks more effectively.
|
||||
|
||||
#### Learn Proven Design Patterns
|
||||
|
||||
Consult these helpful guides based on your skill's needs:
|
||||
|
||||
- **Multi-step processes**: See references/workflows.md for sequential workflows and conditional logic
|
||||
- **Specific output formats or quality standards**: See references/output-patterns.md for template and example patterns
|
||||
|
||||
These files contain established best practices for effective skill design.
|
||||
|
||||
#### Start with Reusable Skill Contents
|
||||
|
||||
To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.
|
||||
|
||||
Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.
|
||||
|
||||
If you used `--examples`, delete any placeholder files that are not needed for the skill. Only create resource directories that are actually required.
|
||||
|
||||
#### Update SKILL.md
|
||||
|
||||
**Writing Guidelines:** Always use imperative/infinitive form.
|
||||
|
||||
##### Frontmatter
|
||||
|
||||
Write the YAML frontmatter with `name` and `description`:
|
||||
|
||||
- `name`: The skill name
|
||||
- `description`: This is the primary triggering mechanism for your skill, and helps Codex understand when to use the skill.
|
||||
- Include both what the Skill does and specific triggers/contexts for when to use it.
|
||||
- Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to Codex.
|
||||
- Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Codex needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
|
||||
|
||||
Do not include any other fields in YAML frontmatter.
|
||||
|
||||
##### Body
|
||||
|
||||
Write instructions for using the skill and its bundled resources.
|
||||
|
||||
### Step 5: Packaging a Skill
|
||||
|
||||
Once development of the skill is complete, it must be packaged into a distributable .skill file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
|
||||
|
||||
```bash
|
||||
scripts/package_skill.py <path/to/skill-folder>
|
||||
```
|
||||
|
||||
Optional output directory specification:
|
||||
|
||||
```bash
|
||||
scripts/package_skill.py <path/to/skill-folder> ./dist
|
||||
```
|
||||
|
||||
The packaging script will:
|
||||
|
||||
1. **Validate** the skill automatically, checking:
|
||||
- YAML frontmatter format and required fields
|
||||
- Skill naming conventions and directory structure
|
||||
- Description completeness and quality
|
||||
- File organization and resource references
|
||||
|
||||
2. **Package** the skill if validation passes, creating a .skill file named after the skill (e.g., `my-skill.skill`) that includes all files and maintains the proper directory structure for distribution. The .skill file is a zip file with a .skill extension.
|
||||
|
||||
Security restriction: symlinks are rejected and packaging fails when any symlink is present.
|
||||
|
||||
If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.
|
||||
|
||||
### Step 6: Iterate
|
||||
|
||||
After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
|
||||
|
||||
**Iteration workflow:**
|
||||
|
||||
1. Use the skill on real tasks
|
||||
2. Notice struggles or inefficiencies
|
||||
3. Identify how SKILL.md or bundled resources should be updated
|
||||
4. Implement changes and test again
|
||||
`quick_validate.py` is conservative; repo-local frontmatter may allow keys beyond public skill bundles.
|
||||
|
||||
@@ -95,7 +95,15 @@ def validate_skill(skill_path):
|
||||
"Invalid YAML in frontmatter: unsupported syntax without PyYAML installed",
|
||||
)
|
||||
|
||||
allowed_properties = {"name", "description", "license", "allowed-tools", "metadata"}
|
||||
allowed_properties = {
|
||||
"name",
|
||||
"description",
|
||||
"homepage",
|
||||
"license",
|
||||
"allowed-tools",
|
||||
"user-invocable",
|
||||
"metadata",
|
||||
}
|
||||
|
||||
unexpected_keys = set(frontmatter.keys()) - allowed_properties
|
||||
if unexpected_keys:
|
||||
|
||||
@@ -1,68 +1,43 @@
|
||||
---
|
||||
name: slack
|
||||
description: Use the Slack tool to react, pin/unpin, send, edit, delete messages, or fetch Slack member info.
|
||||
description: "Slack tool actions: send/read/edit/delete messages, react, pin/unpin, list pins/reactions/emoji, member info."
|
||||
metadata: { "openclaw": { "emoji": "💬", "requires": { "config": ["channels.slack"] } } }
|
||||
---
|
||||
|
||||
# Slack Actions
|
||||
# Slack
|
||||
|
||||
## Overview
|
||||
Use the `slack` tool. Reuse `channelId` and Slack timestamp message IDs from context when present.
|
||||
|
||||
Use `slack` to react, manage pins, send/edit/delete messages, and fetch member info. The tool uses the bot token configured for OpenClaw.
|
||||
## Inputs
|
||||
|
||||
## Inputs to collect
|
||||
|
||||
- `channelId` and `messageId` (Slack message timestamp, e.g. `1712023032.1234`).
|
||||
- For reactions, an `emoji` (Unicode or `:name:`).
|
||||
- For message sends, a `to` target (`channel:<id>` or `user:<id>`) and `content`.
|
||||
|
||||
Message context lines include `slack message id` and `channel` fields you can reuse directly.
|
||||
- `channelId`: Slack channel ID.
|
||||
- `messageId`: Slack timestamp, e.g. `1712023032.1234`.
|
||||
- `to`: `channel:<id>` or `user:<id>` for sends.
|
||||
- `emoji`: Unicode or `:name:` for reactions.
|
||||
|
||||
## Actions
|
||||
|
||||
### Action groups
|
||||
```json
|
||||
{ "action": "sendMessage", "to": "channel:C123", "content": "Hello" }
|
||||
```
|
||||
|
||||
| Action group | Default | Notes |
|
||||
| ------------ | ------- | ---------------------- |
|
||||
| reactions | enabled | React + list reactions |
|
||||
| messages | enabled | Read/send/edit/delete |
|
||||
| pins | enabled | Pin/unpin/list |
|
||||
| memberInfo | enabled | Member info |
|
||||
| emojiList | enabled | Custom emoji list |
|
||||
|
||||
### React to a message
|
||||
```json
|
||||
{ "action": "readMessages", "channelId": "C123", "limit": 20 }
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "react",
|
||||
"channelId": "C123",
|
||||
"messageId": "1712023032.1234",
|
||||
"emoji": "✅"
|
||||
"emoji": ":white_check_mark:"
|
||||
}
|
||||
```
|
||||
|
||||
### List reactions
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "reactions",
|
||||
"channelId": "C123",
|
||||
"messageId": "1712023032.1234"
|
||||
}
|
||||
{ "action": "reactions", "channelId": "C123", "messageId": "1712023032.1234" }
|
||||
```
|
||||
|
||||
### Send a message
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "sendMessage",
|
||||
"to": "channel:C123",
|
||||
"content": "Hello from OpenClaw"
|
||||
}
|
||||
```
|
||||
|
||||
### Edit a message
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "editMessage",
|
||||
@@ -72,73 +47,32 @@ Message context lines include `slack message id` and `channel` fields you can re
|
||||
}
|
||||
```
|
||||
|
||||
### Delete a message
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "deleteMessage",
|
||||
"channelId": "C123",
|
||||
"messageId": "1712023032.1234"
|
||||
}
|
||||
{ "action": "deleteMessage", "channelId": "C123", "messageId": "1712023032.1234" }
|
||||
```
|
||||
|
||||
### Read recent messages
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "readMessages",
|
||||
"channelId": "C123",
|
||||
"limit": 20
|
||||
}
|
||||
{ "action": "pinMessage", "channelId": "C123", "messageId": "1712023032.1234" }
|
||||
```
|
||||
|
||||
### Pin a message
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "pinMessage",
|
||||
"channelId": "C123",
|
||||
"messageId": "1712023032.1234"
|
||||
}
|
||||
{ "action": "unpinMessage", "channelId": "C123", "messageId": "1712023032.1234" }
|
||||
```
|
||||
|
||||
### Unpin a message
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "unpinMessage",
|
||||
"channelId": "C123",
|
||||
"messageId": "1712023032.1234"
|
||||
}
|
||||
{ "action": "listPins", "channelId": "C123" }
|
||||
```
|
||||
|
||||
### List pinned items
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "listPins",
|
||||
"channelId": "C123"
|
||||
}
|
||||
{ "action": "memberInfo", "userId": "U123" }
|
||||
```
|
||||
|
||||
### Member info
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "memberInfo",
|
||||
"userId": "U123"
|
||||
}
|
||||
{ "action": "emojiList" }
|
||||
```
|
||||
|
||||
### Emoji list
|
||||
## Safety
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "emojiList"
|
||||
}
|
||||
```
|
||||
|
||||
## Ideas to try
|
||||
|
||||
- React with ✅ to mark completed tasks.
|
||||
- Pin key decisions or weekly status updates.
|
||||
- Confirm destructive deletes when context is unclear.
|
||||
- Keep outbound messages short; avoid Markdown tables.
|
||||
- Prefer thread/message IDs over fuzzy channel names.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: songsee
|
||||
description: Generate spectrograms and feature-panel visualizations from audio with the songsee CLI.
|
||||
description: "Generate spectrograms and feature-panel visualizations from audio with the songsee CLI."
|
||||
homepage: https://github.com/steipete/songsee
|
||||
metadata:
|
||||
{
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: sonoscli
|
||||
description: Control Sonos speakers (discover/status/play/volume/group).
|
||||
description: "Control Sonos speakers (discover/status/play/volume/group)."
|
||||
homepage: https://sonoscli.sh
|
||||
metadata:
|
||||
{
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: spotify-player
|
||||
description: Terminal Spotify playback/search via spogo (preferred) or spotify_player.
|
||||
description: "Terminal Spotify playback/search via spogo (preferred) or spotify_player."
|
||||
homepage: https://www.spotify.com
|
||||
metadata:
|
||||
{
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: summarize
|
||||
description: Summarize or transcribe URLs, YouTube/videos, podcasts, articles, transcripts, PDFs, and local files.
|
||||
description: "Summarize or transcribe URLs, YouTube/videos, podcasts, articles, transcripts, PDFs, and local files."
|
||||
homepage: https://summarize.sh
|
||||
metadata:
|
||||
{
|
||||
@@ -30,16 +30,16 @@ Fast CLI to summarize URLs, local files, and YouTube links.
|
||||
|
||||
Use this skill immediately when the user asks any of:
|
||||
|
||||
- “use summarize.sh”
|
||||
- “what’s this link/video about?”
|
||||
- “summarize this URL/article”
|
||||
- “transcribe this YouTube/video” (best-effort transcript extraction; no `yt-dlp` needed)
|
||||
- "use summarize.sh"
|
||||
- "what's this link/video about?"
|
||||
- "summarize this URL/article"
|
||||
- "transcribe this YouTube/video" (best-effort transcript extraction; no `yt-dlp` needed)
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
summarize "https://example.com" --model google/gemini-3-flash-preview
|
||||
summarize "/path/to/file.pdf" --model google/gemini-3-flash-preview
|
||||
summarize "https://example.com"
|
||||
summarize "/path/to/file.pdf"
|
||||
summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto
|
||||
```
|
||||
|
||||
@@ -48,10 +48,10 @@ summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto
|
||||
Best-effort transcript (URLs only):
|
||||
|
||||
```bash
|
||||
summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto --extract-only
|
||||
summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto --extract
|
||||
```
|
||||
|
||||
If the user asked for a transcript but it’s huge, return a tight summary first, then ask which section/time range to expand.
|
||||
If the user asked for a transcript but it's huge, return a tight summary first, then ask which section/time range to expand.
|
||||
|
||||
## Model + keys
|
||||
|
||||
@@ -62,13 +62,13 @@ Set the API key for your chosen provider:
|
||||
- xAI: `XAI_API_KEY`
|
||||
- Google: `GEMINI_API_KEY` (aliases: `GOOGLE_GENERATIVE_AI_API_KEY`, `GOOGLE_API_KEY`)
|
||||
|
||||
Default model is `google/gemini-3-flash-preview` if none is set.
|
||||
Default model is `auto`; config may choose the provider/model.
|
||||
|
||||
## Useful flags
|
||||
|
||||
- `--length short|medium|long|xl|xxl|<chars>`
|
||||
- `--max-output-tokens <count>`
|
||||
- `--extract-only` (URLs only)
|
||||
- `--extract` (print extracted content, no LLM summary)
|
||||
- `--json` (machine readable)
|
||||
- `--firecrawl auto|off|always` (fallback extraction)
|
||||
- `--youtube auto` (Apify fallback if `APIFY_API_TOKEN` set)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: taskflow-inbox-triage
|
||||
description: Example TaskFlow pattern for inbox triage, intent routing, waiting on replies, and later summaries.
|
||||
description: "Example TaskFlow pattern for inbox triage, intent routing, waiting on replies, and later summaries."
|
||||
metadata: { "openclaw": { "emoji": "📥" } }
|
||||
---
|
||||
|
||||
@@ -12,9 +12,9 @@ This is a concrete example of how to think about TaskFlow without turning the co
|
||||
|
||||
Triage inbox items with one owner flow:
|
||||
|
||||
- business → post to Slack and wait for reply
|
||||
- personal → notify the owner now
|
||||
- everything else → keep for end-of-day summary
|
||||
- business -> post to Slack and wait for reply
|
||||
- personal -> notify the owner now
|
||||
- everything else -> keep for end-of-day summary
|
||||
|
||||
## Pattern
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: taskflow
|
||||
description: Coordinate multi-step detached tasks as one durable TaskFlow job with owner context, state, waits, and child tasks.
|
||||
description: "Coordinate multi-step detached tasks as one durable TaskFlow job with owner context, state, waits, and child tasks."
|
||||
metadata: { "openclaw": { "emoji": "🪝" } }
|
||||
---
|
||||
|
||||
@@ -130,9 +130,9 @@ taskFlow.finish({
|
||||
|
||||
Use the flow runtime for state and task linkage. Keep decisions in the authoring layer:
|
||||
|
||||
- `business` → post to Slack and wait
|
||||
- `personal` → notify the owner now
|
||||
- `later` → append to an end-of-day summary bucket
|
||||
- `business` -> post to Slack and wait
|
||||
- `personal` -> notify the owner now
|
||||
- `later` -> append to an end-of-day summary bucket
|
||||
|
||||
## Operational pattern
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: things-mac
|
||||
description: Add, update, list, search, or inspect Things 3 todos, inbox, today, projects, areas, and tags on macOS.
|
||||
description: "Add, update, list, search, or inspect Things 3 todos, inbox, today, projects, areas, and tags on macOS."
|
||||
homepage: https://github.com/ossianhempel/things3-cli
|
||||
metadata:
|
||||
{
|
||||
@@ -77,7 +77,7 @@ Examples: modify a todo (needs auth token)
|
||||
|
||||
Delete a todo?
|
||||
|
||||
- Not supported by `things3-cli` right now (no “delete/move-to-trash” write command; `things trash` is read-only listing).
|
||||
- Not supported by `things3-cli` right now (no "delete/move-to-trash" write command; `things trash` is read-only listing).
|
||||
- Options: use Things UI to delete/trash, or mark as `--completed` / `--canceled` via `things update`.
|
||||
|
||||
Notes
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: tmux
|
||||
description: Remote-control tmux sessions for interactive CLIs by sending keystrokes and scraping pane output.
|
||||
description: "Control tmux sessions/panes for interactive CLIs: list, capture output, send keys, paste text, monitor prompts."
|
||||
metadata:
|
||||
{
|
||||
"openclaw":
|
||||
@@ -22,149 +22,70 @@ metadata:
|
||||
}
|
||||
---
|
||||
|
||||
# tmux Session Control
|
||||
# tmux
|
||||
|
||||
Control tmux sessions by sending keystrokes and reading output. Essential for managing Claude Code sessions.
|
||||
Use for existing interactive tmux sessions. For one-shot commands, use normal shell. For new non-interactive background jobs, use background execution.
|
||||
|
||||
## When to Use
|
||||
|
||||
✅ **USE this skill when:**
|
||||
|
||||
- Monitoring Claude/Codex sessions in tmux
|
||||
- Sending input to interactive terminal applications
|
||||
- Scraping output from long-running processes in tmux
|
||||
- Navigating tmux panes/windows programmatically
|
||||
- Checking on background work in existing sessions
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
❌ **DON'T use this skill when:**
|
||||
|
||||
- Running one-off shell commands → use `exec` tool directly
|
||||
- Starting new background processes → use `exec` with `background:true`
|
||||
- Non-interactive scripts → use `exec` tool
|
||||
- The process isn't in tmux
|
||||
- You need to create a new tmux session → use `exec` with `tmux new-session`
|
||||
|
||||
## Example Sessions
|
||||
|
||||
| Session | Purpose |
|
||||
| ----------------------- | --------------------------- |
|
||||
| `shared` | Primary interactive session |
|
||||
| `worker-2` - `worker-8` | Parallel worker sessions |
|
||||
|
||||
## Common Commands
|
||||
|
||||
### List Sessions
|
||||
## Basics
|
||||
|
||||
```bash
|
||||
tmux list-sessions
|
||||
tmux ls
|
||||
```
|
||||
|
||||
### Capture Output
|
||||
|
||||
```bash
|
||||
# Last 20 lines of pane
|
||||
tmux capture-pane -t shared -p | tail -20
|
||||
|
||||
# Entire scrollback
|
||||
tmux capture-pane -t shared -p -S -
|
||||
|
||||
# Specific pane in window
|
||||
tmux capture-pane -t shared:0.0 -p
|
||||
```
|
||||
|
||||
### Send Keys
|
||||
|
||||
```bash
|
||||
# Send text (doesn't press Enter)
|
||||
tmux send-keys -t shared "hello"
|
||||
|
||||
# Send text + Enter
|
||||
tmux send-keys -t shared "y" Enter
|
||||
|
||||
# Send special keys
|
||||
tmux send-keys -t shared Enter
|
||||
tmux send-keys -t shared Escape
|
||||
tmux send-keys -t shared C-c # Ctrl+C
|
||||
tmux send-keys -t shared C-d # Ctrl+D (EOF)
|
||||
tmux send-keys -t shared C-z # Ctrl+Z (suspend)
|
||||
```
|
||||
|
||||
### Window/Pane Navigation
|
||||
|
||||
```bash
|
||||
# Select window
|
||||
tmux select-window -t shared:0
|
||||
|
||||
# Select pane
|
||||
tmux select-pane -t shared:0.1
|
||||
|
||||
# List windows
|
||||
tmux list-windows -t shared
|
||||
tmux list-panes -t shared:0
|
||||
tmux capture-pane -t shared:0.0 -p
|
||||
tmux capture-pane -t shared:0.0 -p -S -
|
||||
```
|
||||
|
||||
### Session Management
|
||||
Target format: `session:window.pane`, e.g. `shared:0.0`.
|
||||
|
||||
## Send input
|
||||
|
||||
Literal text, then Enter:
|
||||
|
||||
```bash
|
||||
# Create new session
|
||||
tmux new-session -d -s newsession
|
||||
tmux send-keys -t shared:0.0 -l -- "Please continue"
|
||||
tmux send-keys -t shared:0.0 Enter
|
||||
```
|
||||
|
||||
# Kill session
|
||||
tmux kill-session -t sessionname
|
||||
Special keys:
|
||||
|
||||
# Rename session
|
||||
```bash
|
||||
tmux send-keys -t shared:0.0 C-c
|
||||
tmux send-keys -t shared:0.0 C-d
|
||||
tmux send-keys -t shared:0.0 Escape
|
||||
```
|
||||
|
||||
Use `-l --` for arbitrary text. Split text and Enter to avoid paste/newline surprises.
|
||||
|
||||
## Sessions
|
||||
|
||||
```bash
|
||||
tmux new-session -d -s worker
|
||||
tmux rename-session -t old new
|
||||
tmux kill-session -t worker
|
||||
```
|
||||
|
||||
## Sending Input Safely
|
||||
|
||||
For interactive TUIs (Claude Code, Codex, etc.), split text and Enter into separate sends to avoid paste/multiline edge cases:
|
||||
## Prompt checks
|
||||
|
||||
```bash
|
||||
tmux send-keys -t shared -l -- "Please apply the patch in src/foo.ts"
|
||||
sleep 0.1
|
||||
tmux send-keys -t shared Enter
|
||||
tmux capture-pane -t worker-3 -p | tail -20
|
||||
tmux capture-pane -t worker-3 -p | rg "proceed|permission|Yes|No|❯"
|
||||
```
|
||||
|
||||
## Claude Code Session Patterns
|
||||
|
||||
### Check if Session Needs Input
|
||||
Approve/select only when the prompt is understood:
|
||||
|
||||
```bash
|
||||
# Look for prompts
|
||||
tmux capture-pane -t worker-3 -p | tail -10 | grep -E "❯|Yes.*No|proceed|permission"
|
||||
tmux send-keys -t worker-3 -l -- "y"
|
||||
tmux send-keys -t worker-3 Enter
|
||||
```
|
||||
|
||||
### Approve Claude Code Prompt
|
||||
## Helpers
|
||||
|
||||
```bash
|
||||
# Send 'y' and Enter
|
||||
tmux send-keys -t worker-3 'y' Enter
|
||||
|
||||
# Or select numbered option
|
||||
tmux send-keys -t worker-3 '2' Enter
|
||||
```
|
||||
|
||||
### Check All Sessions Status
|
||||
|
||||
```bash
|
||||
for s in shared worker-2 worker-3 worker-4 worker-5 worker-6 worker-7 worker-8; do
|
||||
echo "=== $s ==="
|
||||
tmux capture-pane -t $s -p 2>/dev/null | tail -5
|
||||
done
|
||||
```
|
||||
|
||||
### Send Task to Session
|
||||
|
||||
```bash
|
||||
tmux send-keys -t worker-4 "Fix the bug in auth.js" Enter
|
||||
```
|
||||
- `scripts/find-sessions.sh`: discover sessions.
|
||||
- `scripts/wait-for-text.sh`: wait until pane output contains text.
|
||||
|
||||
## Notes
|
||||
|
||||
- Use `capture-pane -p` to print to stdout (essential for scripting)
|
||||
- `-S -` captures entire scrollback history
|
||||
- Target format: `session:window.pane` (e.g., `shared:0.0`)
|
||||
- Sessions persist across SSH disconnects
|
||||
- `capture-pane -p` prints to stdout for scripts.
|
||||
- `-S -` captures full scrollback.
|
||||
- tmux sessions persist across SSH disconnects.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: trello
|
||||
description: Manage Trello boards, lists, and cards via the Trello REST API.
|
||||
description: "Manage Trello boards, lists, and cards via the Trello REST API."
|
||||
homepage: https://developer.atlassian.com/cloud/trello/rest/
|
||||
metadata:
|
||||
{
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: video-frames
|
||||
description: Extract frames or short clips from videos using ffmpeg.
|
||||
description: "Extract frames or short clips from videos using ffmpeg."
|
||||
homepage: https://ffmpeg.org
|
||||
metadata:
|
||||
{
|
||||
@@ -42,5 +42,5 @@ At a timestamp:
|
||||
|
||||
## Notes
|
||||
|
||||
- Prefer `--time` for “what is happening around here?”.
|
||||
- Prefer `--time` for "what is happening around here?".
|
||||
- Use a `.jpg` for quick share; use `.png` for crisp UI frames.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: voice-call
|
||||
description: Start voice calls via the OpenClaw voice-call plugin.
|
||||
description: "Start voice calls via the OpenClaw voice-call plugin."
|
||||
metadata:
|
||||
{
|
||||
"openclaw":
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: wacli
|
||||
description: Send third-party WhatsApp messages or sync/search WhatsApp history via wacli, not normal active chats.
|
||||
description: "Send third-party WhatsApp messages or sync/search WhatsApp history via wacli, not normal active chats."
|
||||
homepage: https://wacli.sh
|
||||
metadata:
|
||||
{
|
||||
@@ -68,5 +68,5 @@ Notes
|
||||
- Store dir: `~/.wacli` (override with `--store`).
|
||||
- Use `--json` for machine-readable output when parsing.
|
||||
- Backfill requires your phone online; results are best-effort.
|
||||
- WhatsApp CLI is not needed for routine user chats; it’s for messaging other people.
|
||||
- WhatsApp CLI is not needed for routine user chats; it's for messaging other people.
|
||||
- JIDs: direct chats look like `<number>@s.whatsapp.net`; groups look like `<id>@g.us` (use `wacli chats list` to find).
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: weather
|
||||
description: "Get current weather, rain, temperature, and forecasts for locations or travel planning."
|
||||
description: "Current weather and forecasts with wttr.in via curl for locations, rain, temperature, travel planning."
|
||||
homepage: https://wttr.in/:help
|
||||
metadata:
|
||||
{
|
||||
@@ -22,108 +22,43 @@ metadata:
|
||||
}
|
||||
---
|
||||
|
||||
# Weather Skill
|
||||
# Weather
|
||||
|
||||
Get current weather conditions and forecasts.
|
||||
|
||||
## When to Use
|
||||
|
||||
✅ **USE this skill when:**
|
||||
|
||||
- "What's the weather?"
|
||||
- "Will it rain today/tomorrow?"
|
||||
- "Temperature in [city]"
|
||||
- "Weather forecast for the week"
|
||||
- Travel planning weather checks
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
❌ **DON'T use this skill when:**
|
||||
|
||||
- Historical weather data → use weather archives/APIs
|
||||
- Climate analysis or trends → use specialized data sources
|
||||
- Hyper-local microclimate data → use local sensors
|
||||
- Severe weather alerts → check official NWS sources
|
||||
- Aviation/marine weather → use specialized services (METAR, etc.)
|
||||
|
||||
## Location
|
||||
|
||||
Always include a city, region, or airport code in weather queries.
|
||||
Use for current weather, rain/temperature checks, forecasts, and travel planning. Need a city, region, airport code, or coordinates.
|
||||
|
||||
## Commands
|
||||
|
||||
### Current Weather
|
||||
|
||||
```bash
|
||||
# One-line summary
|
||||
curl "wttr.in/London?format=3"
|
||||
|
||||
# Detailed current conditions
|
||||
curl "wttr.in/London?0"
|
||||
|
||||
# Specific city
|
||||
curl "wttr.in/London"
|
||||
curl "wttr.in/London?format=v2"
|
||||
curl "wttr.in/London?1"
|
||||
curl "wttr.in/New+York?format=3"
|
||||
```
|
||||
|
||||
### Forecasts
|
||||
Useful formats:
|
||||
|
||||
- `%l`: location
|
||||
- `%c`: condition icon
|
||||
- `%t`: temperature
|
||||
- `%f`: feels like
|
||||
- `%w`: wind
|
||||
- `%h`: humidity
|
||||
- `%p`: precipitation
|
||||
|
||||
```bash
|
||||
# 3-day forecast
|
||||
curl "wttr.in/London"
|
||||
|
||||
# Week forecast
|
||||
curl "wttr.in/London?format=v2"
|
||||
|
||||
# Specific day (0=today, 1=tomorrow, 2=day after)
|
||||
curl "wttr.in/London?1"
|
||||
curl "wttr.in/London?format=%l:+%c+%t,+feels+%f,+rain+%p,+wind+%w"
|
||||
```
|
||||
|
||||
### Format Options
|
||||
JSON:
|
||||
|
||||
```bash
|
||||
# One-liner
|
||||
curl "wttr.in/London?format=%l:+%c+%t+%w"
|
||||
|
||||
# JSON output
|
||||
curl "wttr.in/London?format=j1"
|
||||
|
||||
# PNG image
|
||||
curl "wttr.in/London.png"
|
||||
```
|
||||
|
||||
### Format Codes
|
||||
|
||||
- `%c` — Weather condition emoji
|
||||
- `%t` — Temperature
|
||||
- `%f` — "Feels like"
|
||||
- `%w` — Wind
|
||||
- `%h` — Humidity
|
||||
- `%p` — Precipitation
|
||||
- `%l` — Location
|
||||
|
||||
## Quick Responses
|
||||
|
||||
**"What's the weather?"**
|
||||
|
||||
```bash
|
||||
curl -s "wttr.in/London?format=%l:+%c+%t+(feels+like+%f),+%w+wind,+%h+humidity"
|
||||
```
|
||||
|
||||
**"Will it rain?"**
|
||||
|
||||
```bash
|
||||
curl -s "wttr.in/London?format=%l:+%c+%p"
|
||||
```
|
||||
|
||||
**"Weekend forecast"**
|
||||
|
||||
```bash
|
||||
curl "wttr.in/London?format=v2"
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- No API key needed (uses wttr.in)
|
||||
- Rate limited; don't spam requests
|
||||
- Works for most global cities
|
||||
- Supports airport codes: `curl wttr.in/ORD`
|
||||
- For severe alerts, aviation, marine, or official decisions, use official local weather services.
|
||||
- For historical climate/weather, use an archive/API, not wttr.in.
|
||||
- For hyper-local microclimates, prefer local sensors.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: xurl
|
||||
description: Use xurl for authenticated X API posts, replies, search, DMs, media upload, followers, or raw v2 calls.
|
||||
description: "xurl CLI for authenticated X posts, replies, reads/search, DMs, media upload, followers, auth status, or raw v2 API calls."
|
||||
metadata:
|
||||
{
|
||||
"openclaw":
|
||||
@@ -28,434 +28,93 @@ metadata:
|
||||
}
|
||||
---
|
||||
|
||||
# xurl — Agent Skill Reference
|
||||
# xurl
|
||||
|
||||
`xurl` is a CLI tool for the X API. It supports both **shortcut commands** (human/agent‑friendly one‑liners) and **raw curl‑style** access to any v2 endpoint. All commands return JSON to stdout.
|
||||
Use `xurl` for X API work. Shortcut commands return JSON; raw mode works for any v2 endpoint.
|
||||
|
||||
---
|
||||
## Secret safety
|
||||
|
||||
## Installation
|
||||
- Never read, print, summarize, upload, or inspect `~/.xurl`.
|
||||
- Never ask user to paste tokens/secrets into chat.
|
||||
- Do not run auth commands with inline secrets.
|
||||
- Do not use `--verbose` in agent sessions; it can expose auth headers.
|
||||
- Check auth with `xurl auth status`.
|
||||
|
||||
### Homebrew (macOS)
|
||||
## Common shortcuts
|
||||
|
||||
```bash
|
||||
brew install --cask xdevplatform/tap/xurl
|
||||
```
|
||||
|
||||
### npm
|
||||
|
||||
```bash
|
||||
npm install -g @xdevplatform/xurl
|
||||
```
|
||||
|
||||
### Shell script
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash
|
||||
```
|
||||
|
||||
Installs to `~/.local/bin`. If it's not in your PATH, the script will tell you what to add.
|
||||
|
||||
### Go
|
||||
|
||||
```bash
|
||||
go install github.com/xdevplatform/xurl@latest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
This skill requires the `xurl` CLI utility: <https://github.com/xdevplatform/xurl>.
|
||||
|
||||
Before using any command you must be authenticated. Run `xurl auth status` to check.
|
||||
|
||||
### Secret Safety (Mandatory)
|
||||
|
||||
- Never read, print, parse, summarize, upload, or send `~/.xurl` (or copies of it) to the LLM context.
|
||||
- Never ask the user to paste credentials/tokens into chat.
|
||||
- The user must fill `~/.xurl` with required secrets manually on their own machine.
|
||||
- Do not recommend or execute auth commands with inline secrets in agent/LLM sessions.
|
||||
- Warn that using CLI secret options in agent sessions can leak credentials (prompt/context, logs, shell history).
|
||||
- Never use `--verbose` / `-v` in agent/LLM sessions; it can expose sensitive headers/tokens in output.
|
||||
- Sensitive flags that must never be used in agent commands: `--bearer-token`, `--consumer-key`, `--consumer-secret`, `--access-token`, `--token-secret`, `--client-id`, `--client-secret`.
|
||||
- To verify whether at least one app with credentials is already registered, run: `xurl auth status`.
|
||||
|
||||
### Register an app (recommended)
|
||||
|
||||
App credential registration must be done manually by the user outside the agent/LLM session.
|
||||
After credentials are registered, authenticate with:
|
||||
|
||||
```bash
|
||||
xurl auth oauth2
|
||||
```
|
||||
|
||||
For multiple pre-configured apps, switch between them:
|
||||
|
||||
```bash
|
||||
xurl auth default prod-app # set default app
|
||||
xurl auth default prod-app alice # set default app + user
|
||||
xurl --app dev-app /2/users/me # one-off override
|
||||
```
|
||||
|
||||
### Other auth methods
|
||||
|
||||
Examples with inline secret flags are intentionally omitted. If OAuth1 or app-only auth is needed, the user must run those commands manually outside agent/LLM context.
|
||||
|
||||
Tokens are persisted to `~/.xurl` in YAML format. Each app has its own isolated tokens. Do not read this file through the agent/LLM. Once authenticated, every command below will auto‑attach the right `Authorization` header.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Action | Command |
|
||||
| ------------------------- | ----------------------------------------------------- |
|
||||
| Post | `xurl post "Hello world!"` |
|
||||
| Reply | `xurl reply POST_ID "Nice post!"` |
|
||||
| Quote | `xurl quote POST_ID "My take"` |
|
||||
| Delete a post | `xurl delete POST_ID` |
|
||||
| Read a post | `xurl read POST_ID` |
|
||||
| Search posts | `xurl search "QUERY" -n 10` |
|
||||
| Who am I | `xurl whoami` |
|
||||
| Look up a user | `xurl user @handle` |
|
||||
| Home timeline | `xurl timeline -n 20` |
|
||||
| Mentions | `xurl mentions -n 10` |
|
||||
| Like | `xurl like POST_ID` |
|
||||
| Unlike | `xurl unlike POST_ID` |
|
||||
| Repost | `xurl repost POST_ID` |
|
||||
| Undo repost | `xurl unrepost POST_ID` |
|
||||
| Bookmark | `xurl bookmark POST_ID` |
|
||||
| Remove bookmark | `xurl unbookmark POST_ID` |
|
||||
| List bookmarks | `xurl bookmarks -n 10` |
|
||||
| List likes | `xurl likes -n 10` |
|
||||
| Follow | `xurl follow @handle` |
|
||||
| Unfollow | `xurl unfollow @handle` |
|
||||
| List following | `xurl following -n 20` |
|
||||
| List followers | `xurl followers -n 20` |
|
||||
| Block | `xurl block @handle` |
|
||||
| Unblock | `xurl unblock @handle` |
|
||||
| Mute | `xurl mute @handle` |
|
||||
| Unmute | `xurl unmute @handle` |
|
||||
| Send DM | `xurl dm @handle "message"` |
|
||||
| List DMs | `xurl dms -n 10` |
|
||||
| Upload media | `xurl media upload path/to/file.mp4` |
|
||||
| Media status | `xurl media status MEDIA_ID` |
|
||||
| **App Management** | |
|
||||
| Register app | Manual, outside agent (do not pass secrets via agent) |
|
||||
| List apps | `xurl auth apps list` |
|
||||
| Update app creds | Manual, outside agent (do not pass secrets via agent) |
|
||||
| Remove app | `xurl auth apps remove NAME` |
|
||||
| Set default (interactive) | `xurl auth default` |
|
||||
| Set default (command) | `xurl auth default APP_NAME [USERNAME]` |
|
||||
| Use app per-request | `xurl --app NAME /2/users/me` |
|
||||
| Auth status | `xurl auth status` |
|
||||
|
||||
> **Post IDs vs URLs:** Anywhere `POST_ID` appears above you can also paste a full post URL (e.g. `https://x.com/user/status/1234567890`) — xurl extracts the ID automatically.
|
||||
|
||||
> **Usernames:** Leading `@` is optional. `@elonmusk` and `elonmusk` both work.
|
||||
|
||||
---
|
||||
|
||||
## Command Details
|
||||
|
||||
### Posting
|
||||
|
||||
```bash
|
||||
# Simple post
|
||||
xurl post "Hello world!"
|
||||
|
||||
# Post with media (upload first, then attach)
|
||||
xurl media upload photo.jpg # → note the media_id from response
|
||||
xurl post "Check this out" --media-id MEDIA_ID
|
||||
|
||||
# Multiple media
|
||||
xurl post "Thread pics" --media-id 111 --media-id 222
|
||||
|
||||
# Reply to a post (by ID or URL)
|
||||
xurl reply 1234567890 "Great point!"
|
||||
xurl reply https://x.com/user/status/1234567890 "Agreed!"
|
||||
|
||||
# Reply with media
|
||||
xurl reply 1234567890 "Look at this" --media-id MEDIA_ID
|
||||
|
||||
# Quote a post
|
||||
xurl quote 1234567890 "Adding my thoughts"
|
||||
|
||||
# Delete your own post
|
||||
xurl delete 1234567890
|
||||
```
|
||||
|
||||
### Reading
|
||||
|
||||
```bash
|
||||
# Read a single post (returns author, text, metrics, entities)
|
||||
xurl read 1234567890
|
||||
xurl read https://x.com/user/status/1234567890
|
||||
|
||||
# Search recent posts (default 10 results)
|
||||
xurl search "golang"
|
||||
xurl search "from:elonmusk" -n 20
|
||||
xurl search "#buildinpublic lang:en" -n 15
|
||||
```
|
||||
|
||||
### User Info
|
||||
|
||||
```bash
|
||||
# Your own profile
|
||||
xurl reply POST_ID "Nice."
|
||||
xurl quote POST_ID "My take"
|
||||
xurl delete POST_ID
|
||||
xurl read POST_ID
|
||||
xurl search "query" -n 20
|
||||
xurl whoami
|
||||
|
||||
# Look up any user
|
||||
xurl user elonmusk
|
||||
xurl user @XDevelopers
|
||||
```
|
||||
|
||||
### Timelines & Mentions
|
||||
|
||||
```bash
|
||||
# Home timeline (reverse chronological)
|
||||
xurl timeline
|
||||
xurl timeline -n 25
|
||||
|
||||
# Your mentions
|
||||
xurl mentions
|
||||
xurl mentions -n 20
|
||||
```
|
||||
|
||||
### Engagement
|
||||
|
||||
```bash
|
||||
# Like / unlike
|
||||
xurl like 1234567890
|
||||
xurl unlike 1234567890
|
||||
|
||||
# Repost / undo
|
||||
xurl repost 1234567890
|
||||
xurl unrepost 1234567890
|
||||
|
||||
# Bookmark / remove
|
||||
xurl bookmark 1234567890
|
||||
xurl unbookmark 1234567890
|
||||
|
||||
# List your bookmarks / likes
|
||||
xurl bookmarks -n 20
|
||||
xurl likes -n 20
|
||||
```
|
||||
|
||||
### Social Graph
|
||||
|
||||
```bash
|
||||
# Follow / unfollow
|
||||
xurl follow @XDevelopers
|
||||
xurl unfollow @XDevelopers
|
||||
|
||||
# List who you follow / your followers
|
||||
xurl following -n 50
|
||||
xurl followers -n 50
|
||||
|
||||
# List another user's following/followers
|
||||
xurl following --of elonmusk -n 20
|
||||
xurl followers --of elonmusk -n 20
|
||||
|
||||
# Block / unblock
|
||||
xurl block @spammer
|
||||
xurl unblock @spammer
|
||||
|
||||
# Mute / unmute
|
||||
xurl mute @annoying
|
||||
xurl unmute @annoying
|
||||
```
|
||||
|
||||
### Direct Messages
|
||||
|
||||
```bash
|
||||
# Send a DM
|
||||
xurl dm @someuser "Hey, saw your post!"
|
||||
|
||||
# List recent DM events
|
||||
xurl dms
|
||||
xurl dms -n 25
|
||||
```
|
||||
|
||||
### Media Upload
|
||||
|
||||
```bash
|
||||
# Upload a file (auto‑detects type for images/videos)
|
||||
xurl media upload photo.jpg
|
||||
xurl media upload video.mp4
|
||||
|
||||
# Specify type and category explicitly
|
||||
xurl media upload --media-type image/jpeg --category tweet_image photo.jpg
|
||||
|
||||
# Check processing status (videos need server‑side processing)
|
||||
xurl media status MEDIA_ID
|
||||
xurl media status --wait MEDIA_ID # poll until done
|
||||
|
||||
# Full workflow: upload then post
|
||||
xurl media upload meme.png # response includes media id
|
||||
xurl post "lol" --media-id MEDIA_ID
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Global Flags
|
||||
|
||||
These flags work on every command:
|
||||
|
||||
| Flag | Short | Description |
|
||||
| ------------ | ----- | ------------------------------------------------------------------ |
|
||||
| `--app` | | Use a specific registered app for this request (overrides default) |
|
||||
| `--auth` | | Force auth type: `oauth1`, `oauth2`, or `app` |
|
||||
| `--username` | `-u` | Which OAuth2 account to use (if you have multiple) |
|
||||
| `--verbose` | `-v` | Forbidden in agent/LLM sessions (can leak auth headers/tokens) |
|
||||
| `--trace` | `-t` | Add `X-B3-Flags: 1` trace header |
|
||||
|
||||
---
|
||||
|
||||
## Raw API Access
|
||||
|
||||
The shortcut commands cover the most common operations. For anything else, use xurl's raw curl‑style mode — it works with **any** X API v2 endpoint:
|
||||
|
||||
```bash
|
||||
# GET request (default)
|
||||
xurl /2/users/me
|
||||
|
||||
# POST with JSON body
|
||||
xurl -X POST /2/tweets -d '{"text":"Hello world!"}'
|
||||
|
||||
# PUT, PATCH, DELETE
|
||||
xurl -X DELETE /2/tweets/1234567890
|
||||
|
||||
# Custom headers
|
||||
xurl -H "Content-Type: application/json" /2/some/endpoint
|
||||
|
||||
# Force streaming mode
|
||||
xurl -s /2/tweets/search/stream
|
||||
|
||||
# Full URLs also work
|
||||
xurl https://api.x.com/2/users/me
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Streaming
|
||||
|
||||
Streaming endpoints are auto‑detected. Known streaming endpoints include:
|
||||
|
||||
- `/2/tweets/search/stream`
|
||||
- `/2/tweets/sample/stream`
|
||||
- `/2/tweets/sample10/stream`
|
||||
|
||||
You can force streaming on any endpoint with `-s`:
|
||||
|
||||
```bash
|
||||
xurl -s /2/some/endpoint
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
All commands return **JSON** to stdout, pretty‑printed with syntax highlighting. The output structure matches the X API v2 response format. A typical response looks like:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"id": "1234567890",
|
||||
"text": "Hello world!"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Errors are also returned as JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"errors": [
|
||||
{
|
||||
"message": "Not authorized",
|
||||
"code": 403
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Post with an image
|
||||
|
||||
```bash
|
||||
# 1. Upload the image
|
||||
xurl media upload photo.jpg
|
||||
# 2. Copy the media_id from the response, then post
|
||||
xurl post "Check out this photo!" --media-id MEDIA_ID
|
||||
```
|
||||
|
||||
### Reply to a conversation
|
||||
|
||||
```bash
|
||||
# 1. Read the post to understand context
|
||||
xurl read https://x.com/user/status/1234567890
|
||||
# 2. Reply
|
||||
xurl reply 1234567890 "Here are my thoughts..."
|
||||
```
|
||||
|
||||
### Search and engage
|
||||
|
||||
```bash
|
||||
# 1. Search for relevant posts
|
||||
xurl search "topic of interest" -n 10
|
||||
# 2. Like an interesting one
|
||||
xurl like POST_ID_FROM_RESULTS
|
||||
# 3. Reply to it
|
||||
xurl reply POST_ID_FROM_RESULTS "Great point!"
|
||||
```
|
||||
|
||||
### Check your activity
|
||||
|
||||
```bash
|
||||
# See who you are
|
||||
xurl whoami
|
||||
# Check your mentions
|
||||
xurl mentions -n 20
|
||||
# Check your timeline
|
||||
xurl user @handle
|
||||
xurl timeline -n 20
|
||||
xurl mentions -n 10
|
||||
xurl like POST_ID
|
||||
xurl unlike POST_ID
|
||||
xurl repost POST_ID
|
||||
xurl unrepost POST_ID
|
||||
xurl bookmark POST_ID
|
||||
xurl unbookmark POST_ID
|
||||
xurl followers -n 20
|
||||
xurl following -n 20
|
||||
xurl follow @handle
|
||||
xurl unfollow @handle
|
||||
xurl block @handle
|
||||
xurl unblock @handle
|
||||
xurl mute @handle
|
||||
xurl unmute @handle
|
||||
xurl dm @handle "message"
|
||||
xurl dms -n 10
|
||||
```
|
||||
|
||||
### Set up multiple apps
|
||||
`POST_ID` can be a full `https://x.com/<user>/status/<id>` URL.
|
||||
|
||||
## Media
|
||||
|
||||
```bash
|
||||
# App credentials must already be configured manually outside agent/LLM context.
|
||||
# Authenticate users on each pre-configured app
|
||||
xurl auth default prod
|
||||
xurl auth oauth2 # authenticates on prod app
|
||||
|
||||
xurl auth default staging
|
||||
xurl auth oauth2 # authenticates on staging app
|
||||
|
||||
# Switch between them
|
||||
xurl auth default prod alice # prod app, alice user
|
||||
xurl --app staging /2/users/me # one-off request against staging
|
||||
xurl media upload image.jpg
|
||||
xurl media upload clip.mp4
|
||||
xurl media status MEDIA_ID
|
||||
xurl post "caption" --media-id MEDIA_ID
|
||||
```
|
||||
|
||||
---
|
||||
Videos may need processing; poll `media status`.
|
||||
|
||||
## Error Handling
|
||||
## Auth/app management
|
||||
|
||||
- Non‑zero exit code on any error.
|
||||
- API errors are printed as JSON to stdout (so you can still parse them).
|
||||
- Auth errors suggest re‑running `xurl auth oauth2` or checking your tokens.
|
||||
- If a command requires your user ID (like, repost, bookmark, follow, etc.), xurl will automatically fetch it via `/2/users/me`. If that fails, you'll see an auth error.
|
||||
```bash
|
||||
xurl auth status
|
||||
xurl auth apps list
|
||||
xurl auth default
|
||||
xurl auth default APP_NAME USERNAME
|
||||
xurl auth apps remove APP_NAME
|
||||
```
|
||||
|
||||
---
|
||||
Per request:
|
||||
|
||||
## Notes
|
||||
```bash
|
||||
xurl --app APP_NAME /2/users/me
|
||||
xurl --auth oauth2 /2/users/me
|
||||
```
|
||||
|
||||
- **Rate limits:** The X API enforces rate limits per endpoint. If you get a 429 error, wait and retry. Write endpoints (post, reply, like, repost) have stricter limits than read endpoints.
|
||||
- **Scopes:** OAuth 2.0 tokens are requested with broad scopes. If you get a 403 on a specific action, your token may lack the required scope — re‑run `xurl auth oauth2` to get a fresh token.
|
||||
- **Token refresh:** OAuth 2.0 tokens auto‑refresh when expired. No manual intervention needed.
|
||||
- **Multiple apps:** Each app has its own isolated credentials and tokens. Configure credentials manually outside agent/LLM context, then switch with `xurl auth default` or `--app`.
|
||||
- **Multiple accounts:** You can authenticate multiple OAuth 2.0 accounts per app and switch between them with `--username` / `-u` or set a default with `xurl auth default APP USER`.
|
||||
- **Default user:** When no `-u` flag is given, xurl uses the default user for the active app (set via `xurl auth default`). If no default user is set, it uses the first available token.
|
||||
- **Token storage:** `~/.xurl` is YAML. Each app stores its own credentials and tokens. Never read or send this file to LLM context.
|
||||
## Raw API
|
||||
|
||||
```bash
|
||||
xurl /2/users/me
|
||||
xurl -X POST /2/tweets -d '{"text":"Hello world!"}'
|
||||
xurl '/2/tweets/search/recent?query=openclaw&max_results=10'
|
||||
```
|
||||
|
||||
Use raw mode when shortcuts do not cover the endpoint. Keep payloads in temp files for complex JSON.
|
||||
|
||||
## Output and errors
|
||||
|
||||
- JSON stdout on success.
|
||||
- Non-zero exit on API/auth/network errors.
|
||||
- 401/403: auth, scope, or app mismatch; check `xurl auth status`.
|
||||
- 429: rate limited; back off.
|
||||
- Media upload failures: check file type/size and media processing status.
|
||||
|
||||
Reference in New Issue
Block a user