clawdbot 2026.1.4

package/skills/clawdhub/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: clawdhub
+description: Use the ClawdHub CLI to search, install, update, and publish agent skills from clawdhub.com. Use when you need to fetch new skills on the fly, sync installed skills to latest or a specific version, or publish new/updated skill folders with the npm-installed clawdhub CLI.
+metadata: {"clawdbot":{"requires":{"bins":["clawdhub"]},"install":[{"id":"node","kind":"node","package":"clawdhub","bins":["clawdhub"],"label":"Install ClawdHub CLI (npm)"}]}}
+---
+
+# ClawdHub CLI
+
+Install
+```bash
+npm i -g clawdhub
+```
+
+Auth (publish)
+```bash
+clawdhub login
+clawdhub whoami
+```
+
+Search
+```bash
+clawdhub search "postgres backups"
+```
+
+Install
+```bash
+clawdhub install my-skill
+clawdhub install my-skill --version 1.2.3
+```
+
+Update (hash-based match + upgrade)
+```bash
+clawdhub update my-skill
+clawdhub update my-skill --version 1.2.3
+clawdhub update --all
+clawdhub update my-skill --force
+clawdhub update --all --no-input --force
+```
+
+List
+```bash
+clawdhub list
+```
+
+Publish
+```bash
+clawdhub publish ./my-skill --slug my-skill --name "My Skill" --version 1.2.0 --changelog "Fixes + docs"
+```
+
+Notes
+- Default registry: https://clawdhub.com (override with CLAWDHUB_REGISTRY or --registry)
+- Default workdir: cwd; install dir: ./skills (override with --workdir / --dir)
+- Update command hashes local files, resolves matching version, and upgrades to latest unless --version is set

package/skills/coding-agent/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: coding-agent
+description: Run Codex CLI, Claude Code, OpenCode, or Pi Coding Agent via background process for programmatic control.
+metadata: {"clawdbot":{"emoji":"🧩","requires":{"anyBins":["claude","codex","opencode","pi"]}}}
+---
+
+# Coding Agent (background-first)
+
+Use **bash background mode** for non-interactive coding work. For interactive coding sessions, use the **tmux** skill (always, except very simple one-shot prompts).
+
+## The Pattern: workdir + background
+
+```bash
+# Create temp space for chats/scratch work
+SCRATCH=$(mktemp -d)
+
+# Start agent in target directory ("little box" - only sees relevant files)
+bash workdir:$SCRATCH background:true command:"<agent command>"
+# Or for project work:
+bash workdir:~/project/folder background:true command:"<agent command>"
+# Returns sessionId for tracking
+
+# Monitor progress
+process action:log sessionId:XXX
+
+# Check if done  
+process action:poll sessionId:XXX
+
+# Send input (if agent asks a question)
+process action:write sessionId:XXX data:"y"
+
+# Kill if needed
+process action:kill sessionId:XXX
+```
+
+**Why workdir matters:** Agent wakes up in a focused directory, doesn't wander off reading unrelated files (like your soul.md 😅).
+
+---
+
+## Codex CLI
+
+**Model:** `gpt-5.2-codex` is the default (set in ~/.codex/config.toml)
+
+### Building/Creating (use --full-auto or --yolo)
+```bash
+# --full-auto: sandboxed but auto-approves in workspace
+bash workdir:~/project background:true command:"codex exec --full-auto \"Build a snake game with dark theme\""
+
+# --yolo: NO sandbox, NO approvals (fastest, most dangerous)
+bash workdir:~/project background:true command:"codex --yolo \"Build a snake game with dark theme\""
+
+# Note: --yolo is a shortcut for --dangerously-bypass-approvals-and-sandbox
+```
+
+### Reviewing PRs (vanilla, no flags)
+
+**⚠️ CRITICAL: Never review PRs in Clawdbot's own project folder!**
+- Either use the project where the PR is submitted (if it's NOT ~/Projects/clawdbot)
+- Or clone to a temp folder first
+
+```bash
+# Option 1: Review in the actual project (if NOT clawdbot)
+bash workdir:~/Projects/some-other-repo background:true command:"codex review --base main"
+
+# Option 2: Clone to temp folder for safe review (REQUIRED for clawdbot PRs!)
+REVIEW_DIR=$(mktemp -d)
+git clone https://github.com/clawdbot/clawdbot.git $REVIEW_DIR
+cd $REVIEW_DIR && gh pr checkout 130
+bash workdir:$REVIEW_DIR background:true command:"codex review --base origin/main"
+# Clean up after: rm -rf $REVIEW_DIR
+
+# Option 3: Use git worktree (keeps main intact)
+git worktree add /tmp/pr-130-review pr-130-branch
+bash workdir:/tmp/pr-130-review background:true command:"codex review --base main"
+```
+
+**Why?** Checking out branches in the running Clawdbot repo can break the live instance!
+
+### Batch PR Reviews (parallel army!)
+```bash
+# Fetch all PR refs first
+git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'
+
+# Deploy the army - one Codex per PR!
+bash workdir:~/project background:true command:"codex exec \"Review PR #86. git diff origin/main...origin/pr/86\""
+bash workdir:~/project background:true command:"codex exec \"Review PR #87. git diff origin/main...origin/pr/87\""
+bash workdir:~/project background:true command:"codex exec \"Review PR #95. git diff origin/main...origin/pr/95\""
+# ... repeat for all PRs
+
+# Monitor all
+process action:list
+
+# Get results and post to GitHub
+process action:log sessionId:XXX
+gh pr comment <PR#> --body "<review content>"
+```
+
+### Tips for PR Reviews
+- **Fetch refs first:** `git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'`
+- **Use git diff:** Tell Codex to use `git diff origin/main...origin/pr/XX`
+- **Don't checkout:** Multiple parallel reviews = don't let them change branches
+- **Post results:** Use `gh pr comment` to post reviews to GitHub
+
+---
+
+## Claude Code
+
+```bash
+bash workdir:~/project background:true command:"claude \"Your task\""
+```
+
+---
+
+## OpenCode
+
+```bash
+bash workdir:~/project background:true command:"opencode run \"Your task\""
+```
+
+---
+
+## Pi Coding Agent
+
+```bash
+# Install: npm install -g @mariozechner/pi-coding-agent
+bash workdir:~/project background:true command:"pi \"Your task\""
+```
+
+---
+
+## Pi flags (common)
+
+- `--print` / `-p`: non-interactive; runs prompt and exits.
+- `--provider <name>`: pick provider (default: google).
+- `--model <id>`: pick model (default: gemini-2.5-flash).
+- `--api-key <key>`: override API key (defaults to env vars).
+
+Examples:
+
+```bash
+# Set provider + model, non-interactive
+bash workdir:~/project background:true command:"pi --provider openai --model gpt-4o-mini -p \"Summarize src/\""
+```
+
+---
+
+## tmux (interactive sessions)
+
+Use the tmux skill for interactive coding sessions (always, except very simple one-shot prompts). Prefer bash background mode for non-interactive runs.
+
+---
+
+## Parallel Issue Fixing with git worktrees + tmux
+
+For fixing multiple issues in parallel, use git worktrees (isolated branches) + tmux sessions:
+
+```bash
+# 1. Clone repo to temp location
+cd /tmp && git clone git@github.com:user/repo.git repo-worktrees
+cd repo-worktrees
+
+# 2. Create worktrees for each issue (isolated branches!)
+git worktree add -b fix/issue-78 /tmp/issue-78 main
+git worktree add -b fix/issue-99 /tmp/issue-99 main
+
+# 3. Set up tmux sessions
+SOCKET="${TMPDIR:-/tmp}/codex-fixes.sock"
+tmux -S "$SOCKET" new-session -d -s fix-78
+tmux -S "$SOCKET" new-session -d -s fix-99
+
+# 4. Launch Codex in each (after pnpm install!)
+tmux -S "$SOCKET" send-keys -t fix-78 "cd /tmp/issue-78 && pnpm install && codex --yolo 'Fix issue #78: <description>. Commit and push.'" Enter
+tmux -S "$SOCKET" send-keys -t fix-99 "cd /tmp/issue-99 && pnpm install && codex --yolo 'Fix issue #99: <description>. Commit and push.'" Enter
+
+# 5. Monitor progress
+tmux -S "$SOCKET" capture-pane -p -t fix-78 -S -30
+tmux -S "$SOCKET" capture-pane -p -t fix-99 -S -30
+
+# 6. Check if done (prompt returned)
+tmux -S "$SOCKET" capture-pane -p -t fix-78 -S -3 | grep -q "❯" && echo "Done!"
+
+# 7. Create PRs after fixes
+cd /tmp/issue-78 && git push -u origin fix/issue-78
+gh pr create --repo user/repo --head fix/issue-78 --title "fix: ..." --body "..."
+
+# 8. Cleanup
+tmux -S "$SOCKET" kill-server
+git worktree remove /tmp/issue-78
+git worktree remove /tmp/issue-99
+```
+
+**Why worktrees?** Each Codex works in isolated branch, no conflicts. Can run 5+ parallel fixes!
+
+**Why tmux over bash background?** Codex is interactive — needs TTY for proper output. tmux provides persistent sessions with full history capture.
+
+---
+
+## ⚠️ Rules
+
+1. **Respect tool choice** — if user asks for Codex, use Codex. NEVER offer to build it yourself!
+2. **Be patient** — don't kill sessions because they're "slow"
+3. **Monitor with process:log** — check progress without interfering
+4. **--full-auto for building** — auto-approves changes
+5. **vanilla for reviewing** — no special flags needed
+6. **Parallel is OK** — run many Codex processes at once for batch work
+7. **NEVER start Codex in ~/clawd/** — it'll read your soul docs and get weird ideas about the org chart! Use the target project dir or /tmp for blank slate chats
+8. **NEVER checkout branches in ~/Projects/clawdbot/** — that's the LIVE Clawdbot instance! Clone to /tmp or use git worktree for PR reviews
+
+---
+
+## PR Template (The Razor Standard)
+
+When submitting PRs to external repos, use this format for quality & maintainer-friendliness:
+
+````markdown
+## Original Prompt
+[Exact request/problem statement]
+
+## What this does
+[High-level description]
+
+**Features:**
+- [Key feature 1]
+- [Key feature 2]
+
+**Example usage:**
+```bash
+# Example
+command example
+```
+````
+
+## Feature intent (maintainer-friendly)
+[Why useful, how it fits, workflows it enables]
+
+## Prompt history (timestamped)
+- YYYY-MM-DD HH:MM UTC: [Step 1]
+- YYYY-MM-DD HH:MM UTC: [Step 2]
+
+## How I tested
+**Manual verification:**
+1. [Test step] - Output: `[result]`
+2. [Test step] - Result: [result]
+
+**Files tested:**
+- [Detail]
+- [Edge cases]
+
+## Session logs (implementation)
+- [What was researched]
+- [What was discovered]
+- [Time spent]
+
+## Implementation details
+**New files:**
+- `path/file.ts` - [description]
+
+**Modified files:**
+- `path/file.ts` - [change]
+
+**Technical notes:**
+- [Detail 1]
+- [Detail 2]
+
+---
+*Submitted by Razor 🥷 - Mariano's AI agent*
+```
+
+**Key principles:**
+1. Human-written description (no AI slop)
+2. Feature intent for maintainers
+3. Timestamped prompt history
+4. Session logs if using Codex/agent
+
+**Example:** https://github.com/steipete/bird/pull/22

package/skills/discord/SKILL.md

@@ -0,0 +1,369 @@
+---
+name: discord
+description: Use when you need to control Discord from Clawdbot via the discord tool: send messages, react, post or upload stickers, upload emojis, run polls, manage threads/pins/search, fetch permissions or member/role/channel info, or handle moderation actions in Discord DMs or channels.
+---
+
+# Discord Actions
+
+## Overview
+
+Use `discord` to manage messages, reactions, threads, polls, and moderation. You can disable groups via `discord.actions.*` (defaults to enabled, except roles/moderation). The tool uses the bot token configured for Clawdbot.
+
+## Inputs to collect
+
+- For reactions: `channelId`, `messageId`, and an `emoji`.
+- For stickers/polls/sendMessage: a `to` target (`channel:<id>` or `user:<id>`). Optional `content` text.
+- Polls also need a `question` plus 2–10 `answers`.
+- For media: `mediaUrl` with `file:///path` for local files or `https://...` for remote.
+- For emoji uploads: `guildId`, `name`, `mediaUrl`, optional `roleIds` (limit 256KB, PNG/JPG/GIF).
+- For sticker uploads: `guildId`, `name`, `description`, `tags`, `mediaUrl` (limit 512KB, PNG/APNG/Lottie JSON).
+
+Message context lines include `discord message id` and `channel` fields you can reuse directly.
+
+**Note:** `sendMessage` uses `to: "channel:<id>"` format, not `channelId`. Other actions like `react`, `readMessages`, `editMessage` use `channelId` directly.
+
+## Actions
+
+### React to a message
+
+```json
+{
+  "action": "react",
+  "channelId": "123",
+  "messageId": "456",
+  "emoji": "✅"
+}
+```
+
+### List reactions + users
+
+```json
+{
+  "action": "reactions",
+  "channelId": "123",
+  "messageId": "456",
+  "limit": 100
+}
+```
+
+### Send a sticker
+
+```json
+{
+  "action": "sticker",
+  "to": "channel:123",
+  "stickerIds": ["9876543210"],
+  "content": "Nice work!"
+}
+```
+
+- Up to 3 sticker IDs per message.
+- `to` can be `user:<id>` for DMs.
+
+### Upload a custom emoji
+
+```json
+{
+  "action": "emojiUpload",
+  "guildId": "999",
+  "name": "party_blob",
+  "mediaUrl": "file:///tmp/party.png",
+  "roleIds": ["222"]
+}
+```
+
+- Emoji images must be PNG/JPG/GIF and <= 256KB.
+- `roleIds` is optional; omit to make the emoji available to everyone.
+
+### Upload a sticker
+
+```json
+{
+  "action": "stickerUpload",
+  "guildId": "999",
+  "name": "clawdbot_wave",
+  "description": "Clawdbot waving hello",
+  "tags": "👋",
+  "mediaUrl": "file:///tmp/wave.png"
+}
+```
+
+- Stickers require `name`, `description`, and `tags`.
+- Uploads must be PNG/APNG/Lottie JSON and <= 512KB.
+
+### Create a poll
+
+```json
+{
+  "action": "poll",
+  "to": "channel:123",
+  "question": "Lunch?",
+  "answers": ["Pizza", "Sushi", "Salad"],
+  "allowMultiselect": false,
+  "durationHours": 24,
+  "content": "Vote now"
+}
+```
+
+- `durationHours` defaults to 24; max 32 days (768 hours).
+
+### Check bot permissions for a channel
+
+```json
+{
+  "action": "permissions",
+  "channelId": "123"
+}
+```
+
+## Ideas to try
+
+- React with ✅/⚠️ to mark status updates.
+- Post a quick poll for release decisions or meeting times.
+- Send celebratory stickers after successful deploys.
+- Upload new emojis/stickers for release moments.
+- Run weekly “priority check” polls in team channels.
+- DM stickers as acknowledgements when a user’s request is completed.
+
+## Action gating
+
+Use `discord.actions.*` to disable action groups:
+- `reactions` (react + reactions list + emojiList)
+- `stickers`, `polls`, `permissions`, `messages`, `threads`, `pins`, `search`
+- `emojiUploads`, `stickerUploads`
+- `memberInfo`, `roleInfo`, `channelInfo`, `voiceStatus`, `events`
+- `roles` (role add/remove, default `false`)
+- `moderation` (timeout/kick/ban, default `false`)
+### Read recent messages
+
+```json
+{
+  "action": "readMessages",
+  "channelId": "123",
+  "limit": 20
+}
+```
+
+### Send/edit/delete a message
+
+```json
+{
+  "action": "sendMessage",
+  "to": "channel:123",
+  "content": "Hello from Clawdbot"
+}
+```
+
+**With media attachment:**
+
+```json
+{
+  "action": "sendMessage",
+  "to": "channel:123",
+  "content": "Check out this audio!",
+  "mediaUrl": "file:///tmp/audio.mp3"
+}
+```
+
+- `to` uses format `channel:<id>` or `user:<id>` for DMs (not `channelId`!)
+- `mediaUrl` supports local files (`file:///path/to/file`) and remote URLs (`https://...`)
+- Optional `replyTo` with a message ID to reply to a specific message
+
+```json
+{
+  "action": "editMessage",
+  "channelId": "123",
+  "messageId": "456",
+  "content": "Fixed typo"
+}
+```
+
+```json
+{
+  "action": "deleteMessage",
+  "channelId": "123",
+  "messageId": "456"
+}
+```
+
+### Threads
+
+```json
+{
+  "action": "threadCreate",
+  "channelId": "123",
+  "name": "Bug triage",
+  "messageId": "456"
+}
+```
+
+```json
+{
+  "action": "threadList",
+  "guildId": "999"
+}
+```
+
+```json
+{
+  "action": "threadReply",
+  "channelId": "777",
+  "content": "Replying in thread"
+}
+```
+
+### Pins
+
+```json
+{
+  "action": "pinMessage",
+  "channelId": "123",
+  "messageId": "456"
+}
+```
+
+```json
+{
+  "action": "listPins",
+  "channelId": "123"
+}
+```
+
+### Search messages
+
+```json
+{
+  "action": "searchMessages",
+  "guildId": "999",
+  "content": "release notes",
+  "channelIds": ["123", "456"],
+  "limit": 10
+}
+```
+
+### Member + role info
+
+```json
+{
+  "action": "memberInfo",
+  "guildId": "999",
+  "userId": "111"
+}
+```
+
+```json
+{
+  "action": "roleInfo",
+  "guildId": "999"
+}
+```
+
+### List available custom emojis
+
+```json
+{
+  "action": "emojiList",
+  "guildId": "999"
+}
+```
+
+### Role changes (disabled by default)
+
+```json
+{
+  "action": "roleAdd",
+  "guildId": "999",
+  "userId": "111",
+  "roleId": "222"
+}
+```
+
+### Channel info
+
+```json
+{
+  "action": "channelInfo",
+  "channelId": "123"
+}
+```
+
+```json
+{
+  "action": "channelList",
+  "guildId": "999"
+}
+```
+
+### Voice status
+
+```json
+{
+  "action": "voiceStatus",
+  "guildId": "999",
+  "userId": "111"
+}
+```
+
+### Scheduled events
+
+```json
+{
+  "action": "eventList",
+  "guildId": "999"
+}
+```
+
+### Moderation (disabled by default)
+
+```json
+{
+  "action": "timeout",
+  "guildId": "999",
+  "userId": "111",
+  "durationMinutes": 10
+}
+```
+
+## Discord Writing Style Guide
+
+**Keep it conversational!** Discord is a chat platform, not documentation.
+
+### Do
+- Short, punchy messages (1-3 sentences ideal)
+- Multiple quick replies > one wall of text
+- Use emoji for tone/emphasis 🦞
+- Lowercase casual style is fine
+- Break up info into digestible chunks
+- Match the energy of the conversation
+
+### Don't
+- No markdown tables (Discord renders them as ugly raw `| text |`)
+- No `## Headers` for casual chat (use **bold** or CAPS for emphasis)
+- Avoid multi-paragraph essays
+- Don't over-explain simple things
+- Skip the "I'd be happy to help!" fluff
+
+### Formatting that works
+- **bold** for emphasis
+- `code` for technical terms
+- Lists for multiple items
+- > quotes for referencing
+- Wrap multiple links in `<>` to suppress embeds
+
+### Example transformations
+
+❌ Bad:
+```
+I'd be happy to help with that! Here's a comprehensive overview of the versioning strategies available:
+
+## Semantic Versioning
+Semver uses MAJOR.MINOR.PATCH format where...
+
+## Calendar Versioning
+CalVer uses date-based versions like...
+```
+
+✅ Good:
+```
+versioning options: semver (1.2.3), calver (2026.01.04), or yolo (`latest` forever). what fits your release cadence?
+```