@poolzin/pool-bot 2026.2.21 → 2026.2.22

package/skills/coding-agent/SKILL.md

@@ -1,7 +1,10 @@
 ---
 name: coding-agent
-description: Run Codex CLI, Claude Code, OpenCode, or Pi Coding Agent via background process for programmatic control.
-metadata: {"poolbot":{"emoji":"🧩","requires":{"anyBins":["claude","codex","opencode","pi"]}}}
+description: "Delegate coding tasks to Codex, Claude Code, or Pi agents via background process. Use when: (1) building/creating new features or apps, (2) reviewing PRs (spawn in temp dir), (3) refactoring large codebases, (4) iterative coding that needs file exploration. NOT for: simple one-liner fixes (just edit), reading code (use read tool), or any work in ~/clawd workspace (never spawn agents here). Requires a bash tool that supports pty:true."
+metadata:
+  {
+    "poolbot": { "emoji": "🧩", "requires": { "anyBins": ["claude", "codex", "opencode", "pi"] } },
+  }
 ---
 
 # Coding Agent (bash-first)
@@ -24,27 +27,27 @@ bash command:"codex exec 'Your prompt'"
 
 ### Bash Tool Parameters
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `command` | string | The shell command to run |
-| `pty` | boolean | **Use for coding agents!** Allocates a pseudo-terminal for interactive CLIs |
-| `workdir` | string | Working directory (agent sees only this folder's context) |
-| `background` | boolean | Run in background, returns sessionId for monitoring |
-| `timeout` | number | Timeout in seconds (kills process on expiry) |
-| `elevated` | boolean | Run on host instead of sandbox (if allowed) |
+| Parameter    | Type    | Description                                                                 |
+| ------------ | ------- | --------------------------------------------------------------------------- |
+| `command`    | string  | The shell command to run                                                    |
+| `pty`        | boolean | **Use for coding agents!** Allocates a pseudo-terminal for interactive CLIs |
+| `workdir`    | string  | Working directory (agent sees only this folder's context)                   |
+| `background` | boolean | Run in background, returns sessionId for monitoring                         |
+| `timeout`    | number  | Timeout in seconds (kills process on expiry)                                |
+| `elevated`   | boolean | Run on host instead of sandbox (if allowed)                                 |
 
 ### Process Tool Actions (for background sessions)
 
-| 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 |
+| 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                                |
 
 ---
 
@@ -99,13 +102,14 @@ process action:kill sessionId:XXX
 
 ### Flags
 
-| Flag | Effect |
-|------|--------|
-| `exec "prompt"` | One-shot execution, exits when done |
-| `--full-auto` | Sandboxed but auto-approves in workspace |
-| `--yolo` | NO sandbox, NO approvals (fastest, most dangerous) |
+| Flag            | Effect                                             |
+| --------------- | -------------------------------------------------- |
+| `exec "prompt"` | One-shot execution, exits when done                |
+| `--full-auto`   | Sandboxed but auto-approves in workspace           |
+| `--yolo`        | NO sandbox, NO approvals (fastest, most dangerous) |
 
 ### Building/Creating
+
 ```bash
 # Quick one-shot (auto-approves) - remember PTY!
 bash pty:true workdir:~/project command:"codex exec --full-auto 'Build a dark mode toggle'"
@@ -133,6 +137,7 @@ bash pty:true workdir:/tmp/pr-130-review command:"codex review --base main"
 ```
 
 ### Batch PR Reviews (parallel army!)
+
 ```bash
 # Fetch all PR refs first
 git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'
@@ -255,14 +260,15 @@ For long-running background tasks, append a wake trigger to your prompt so Pool
 ... your task here.
 
 When completely finished, run this command to notify me:
-poolbot gateway wake --text "Done: [brief summary of what was built]" --mode now
+poolbot system event --text "Done: [brief summary of what was built]" --mode now
 ```
 
 **Example:**
+
 ```bash
 bash pty:true workdir:~/project background:true command:"codex --yolo exec 'Build a REST API for todos.
 
-When completely finished, run: poolbot gateway wake --text \"Done: Built todos REST API with CRUD endpoints\" --mode now'"
+When completely finished, run: poolbot system event --text \"Done: Built todos REST API with CRUD endpoints\" --mode now'"
 ```
 
 This triggers an immediate wake event — Skippy gets pinged in seconds, not 10 minutes.
@@ -275,4 +281,4 @@ This triggers an immediate wake event — Skippy gets pinged in seconds, not 10
 - **Git repo required:** Codex won't run outside a git directory. Use `mktemp -d && git init` for scratch work.
 - **exec is your friend:** `codex exec "prompt"` runs and exits cleanly - perfect for one-shots.
 - **submit vs write:** Use `submit` to send input + Enter, `write` for raw data without newline.
-- **Sass works:** Codex responds well to playful prompts. Asked it to write a haiku about being second fiddle to a space lobster, got: *"Second chair, I code / Space lobster sets the tempo / Keys glow, I follow"* 🦞
+- **Sass works:** Codex responds well to playful prompts. Asked it to write a haiku about being second fiddle to a space lobster, got: _"Second chair, I code / Space lobster sets the tempo / Keys glow, I follow"_ 🦞

package/skills/github/SKILL.md

@@ -1,48 +1,163 @@
 ---
 name: github
-description: "Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries."
-metadata: {"poolbot":{"emoji":"🐙","requires":{"bins":["gh"]},"install":[{"id":"brew","kind":"brew","formula":"gh","bins":["gh"],"label":"Install GitHub CLI (brew)"},{"id":"apt","kind":"apt","package":"gh","bins":["gh"],"label":"Install GitHub CLI (apt)"}]}}
+description: "GitHub operations via `gh` CLI: issues, PRs, CI runs, code review, API queries. Use when: (1) checking PR status or CI, (2) creating/commenting on issues, (3) listing/filtering PRs or issues, (4) viewing run logs. NOT for: complex web UI interactions requiring manual browser flows (use browser tooling when available), bulk operations across many repos (script with gh api), or when gh auth is not configured."
+metadata:
+  {
+    "poolbot":
+      {
+        "emoji": "🐙",
+        "requires": { "bins": ["gh"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "gh",
+              "bins": ["gh"],
+              "label": "Install GitHub CLI (brew)",
+            },
+            {
+              "id": "apt",
+              "kind": "apt",
+              "package": "gh",
+              "bins": ["gh"],
+              "label": "Install GitHub CLI (apt)",
+            },
+          ],
+      },
+  }
 ---
 
 # GitHub Skill
 
-Use the `gh` CLI to interact with GitHub. Always specify `--repo owner/repo` when not in a git directory, or use URLs directly.
+Use the `gh` CLI to interact with GitHub repositories, issues, PRs, and CI.
 
-## Pull Requests
+## 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
 
-Check CI status on a PR:
 ```bash
-gh pr checks 55 --repo owner/repo
+# Authenticate (one-time)
+gh auth login
+
+# Verify
+gh auth status
 ```
 
-List recent workflow runs:
+## Common Commands
+
+### Pull Requests
+
 ```bash
-gh run list --repo owner/repo --limit 10
+# List PRs
+gh pr list --repo owner/repo
+
+# Check CI status
+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
 ```
 
-View a run and see which steps failed:
+### Issues
+
 ```bash
-gh run view <run-id> --repo owner/repo
+# 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
 ```
 
-View logs for failed steps only:
+### CI/Workflow 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 --log-failed
-```
 
-## API for Advanced Queries
+# Re-run failed jobs
+gh run rerun <run-id> --failed --repo owner/repo
+```
 
-The `gh api` command is useful for accessing data not available through other subcommands.
+### API Queries
 
-Get PR with specific fields:
 ```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}'
 ```
 
 ## JSON Output
 
-Most commands support `--json` for structured output.  You can use `--jq` to filter:
+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

package/skills/imsg/SKILL.md

@@ -1,25 +1,122 @@
 ---
 name: imsg
-description: iMessage/SMS CLI for listing chats, history, watch, and sending.
+description: iMessage/SMS CLI for listing chats, history, and sending messages via Messages.app.
 homepage: https://imsg.to
-metadata: {"poolbot":{"emoji":"📨","os":["darwin"],"requires":{"bins":["imsg"]},"install":[{"id":"brew","kind":"brew","formula":"steipete/tap/imsg","bins":["imsg"],"label":"Install imsg (brew)"}]}}
+metadata:
+  {
+    "poolbot":
+      {
+        "emoji": "📨",
+        "os": ["darwin"],
+        "requires": { "bins": ["imsg"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/imsg",
+              "bins": ["imsg"],
+              "label": "Install imsg (brew)",
+            },
+          ],
+      },
+  }
 ---
 
 # imsg
 
-Use `imsg` to read and send Messages.app iMessage/SMS on macOS.
+Use `imsg` to read and send iMessage/SMS via macOS Messages.app.
 
-Requirements
-- Messages.app signed in
-- Full Disk Access for your terminal
-- Automation permission to control Messages.app (for sending)
+## When to Use
 
-Common commands
-- List chats: `imsg chats --limit 10 --json`
-- History: `imsg history --chat-id 1 --limit 20 --attachments --json`
-- Watch: `imsg watch --chat-id 1 --attachments`
-- Send: `imsg send --to "+14155551212" --text "hi" --file /path/pic.jpg`
+✅ **USE this skill when:**
 
-Notes
-- `--service imessage|sms|auto` controls delivery.
-- Confirm recipient + message before sending.
+- User explicitly asks to send iMessage or SMS
+- Reading iMessage conversation history
+- Checking recent Messages.app chats
+- Sending to phone numbers or Apple IDs
+
+## When NOT to Use
+
+❌ **DON'T use this skill 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 (Clawdbot routes automatically)
+
+## Requirements
+
+- macOS with Messages.app signed in
+- Full Disk Access for terminal
+- Automation permission for Messages.app (for sending)
+
+## Common Commands
+
+### List Chats
+
+```bash
+imsg chats --limit 10 --json
+```
+
+### View History
+
+```bash
+# By chat ID
+imsg history --chat-id 1 --limit 20 --json
+
+# With attachments info
+imsg history --chat-id 1 --limit 20 --attachments --json
+```
+
+### Watch for New Messages
+
+```bash
+imsg watch --chat-id 1 --attachments
+```
+
+### Send Messages
+
+```bash
+# Text only
+imsg send --to "+14155551212" --text "Hello!"
+
+# With attachment
+imsg send --to "+14155551212" --text "Check this out" --file /path/to/image.jpg
+
+# Specify service
+imsg send --to "+14155551212" --text "Hi" --service imessage
+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)
+
+## 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
+
+## Example Workflow
+
+User: "Text mom that I'll be late"
+
+```bash
+# 1. Find mom's chat
+imsg chats --limit 20 --json | jq '.[] | select(.displayName | contains("Mom"))'
+
+# 2. Confirm with user
+# "Found Mom at +1555123456. Send 'I'll be late' via iMessage?"
+
+# 3. Send after confirmation
+imsg send --to "+1555123456" --text "I'll be late"
+```

package/skills/openhue/SKILL.md

@@ -1,30 +1,112 @@
 ---
 name: openhue
-description: Control Philips Hue lights/scenes via the OpenHue CLI.
+description: Control Philips Hue lights and scenes via the OpenHue CLI.
 homepage: https://www.openhue.io/cli
-metadata: {"poolbot":{"emoji":"💡","requires":{"bins":["openhue"]},"install":[{"id":"brew","kind":"brew","formula":"openhue/cli/openhue-cli","bins":["openhue"],"label":"Install OpenHue CLI (brew)"}]}}
+metadata:
+  {
+    "poolbot":
+      {
+        "emoji": "💡",
+        "requires": { "bins": ["openhue"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "openhue/cli/openhue-cli",
+              "bins": ["openhue"],
+              "label": "Install OpenHue CLI (brew)",
+            },
+          ],
+      },
+  }
 ---
 
 # OpenHue CLI
 
-Use `openhue` to control Hue lights and scenes via a Hue Bridge.
+Use `openhue` to control Philips Hue lights and scenes via a Hue Bridge.
 
-Setup
-- Discover bridges: `openhue discover`
-- Guided setup: `openhue setup`
+## When to Use
 
-Read
-- `openhue get light --json`
-- `openhue get room --json`
-- `openhue get scene --json`
+✅ **USE this skill when:**
 
-Write
-- Turn on: `openhue set light <id-or-name> --on`
-- Turn off: `openhue set light <id-or-name> --off`
-- Brightness: `openhue set light <id> --on --brightness 50`
-- Color: `openhue set light <id> --on --rgb #3399FF`
-- Scene: `openhue set scene <scene-id>`
+- "Turn on/off the lights"
+- "Dim the living room lights"
+- "Set a scene" or "movie mode"
+- Controlling specific Hue rooms or zones
+- Adjusting brightness, color, or color temperature
 
-Notes
-- You may need to press the Hue Bridge button during setup.
-- Use `--room "Room Name"` when light names are ambiguous.
+## When NOT to Use
+
+❌ **DON'T use this skill when:**
+
+- 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)
+
+## Common Commands
+
+### List Resources
+
+```bash
+openhue get light       # List all lights
+openhue get room        # List all rooms
+openhue get scene       # List all scenes
+```
+
+### Control Lights
+
+```bash
+# Turn on/off
+openhue set light "Bedroom Lamp" --on
+openhue set light "Bedroom Lamp" --off
+
+# Brightness (0-100)
+openhue set light "Bedroom Lamp" --on --brightness 50
+
+# Color temperature (warm to cool: 153-500 mirek)
+openhue set light "Bedroom Lamp" --on --temperature 300
+
+# Color (by name or hex)
+openhue set light "Bedroom Lamp" --on --color red
+openhue set light "Bedroom Lamp" --on --rgb "#FF5500"
+```
+
+### Control Rooms
+
+```bash
+# Turn off entire room
+openhue set room "Bedroom" --off
+
+# Set room brightness
+openhue set room "Bedroom" --on --brightness 30
+```
+
+### Scenes
+
+```bash
+# Activate scene
+openhue set scene "Relax" --room "Bedroom"
+openhue set scene "Concentrate" --room "Office"
+```
+
+## Quick Presets
+
+```bash
+# Bedtime (dim warm)
+openhue set room "Bedroom" --on --brightness 20 --temperature 450
+
+# Work mode (bright cool)
+openhue set room "Office" --on --brightness 100 --temperature 250
+
+# Movie mode (dim)
+openhue set room "Living Room" --on --brightness 10
+```
+
+## Notes
+
+- Bridge must be on local network
+- First run requires button press on Hue bridge to pair
+- Colors only work on color-capable bulbs (not white-only)