@poolzin/pool-bot 2026.2.21 → 2026.2.23

package/skills/apple-reminders/SKILL.md

@@ -1,67 +1,118 @@
 ---
 name: apple-reminders
-description: Manage Apple Reminders via the `remindctl` CLI on macOS (list, add, edit, complete, delete). Supports lists, date filters, and JSON/plain output.
+description: Manage Apple Reminders via remindctl CLI (list, add, edit, complete, delete). Supports lists, date filters, and JSON/plain output.
 homepage: https://github.com/steipete/remindctl
-metadata: {"poolbot":{"emoji":"⏰","os":["darwin"],"requires":{"bins":["remindctl"]},"install":[{"id":"brew","kind":"brew","formula":"steipete/tap/remindctl","bins":["remindctl"],"label":"Install remindctl via Homebrew"}]}}
+metadata:
+  {
+    "poolbot":
+      {
+        "emoji": "⏰",
+        "os": ["darwin"],
+        "requires": { "bins": ["remindctl"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/remindctl",
+              "bins": ["remindctl"],
+              "label": "Install remindctl via Homebrew",
+            },
+          ],
+      },
+  }
 ---
 
 # Apple Reminders CLI (remindctl)
 
-Use `remindctl` to manage Apple Reminders directly from the terminal. It supports list filtering, date-based views, and scripting output.
+Use `remindctl` to manage Apple Reminders directly from the terminal.
 
-Setup
-- Install (Homebrew): `brew install steipete/tap/remindctl`
-- From source: `pnpm install && pnpm build` (binary at `./bin/remindctl`)
-- macOS-only; grant Reminders permission when prompted.
+## When to Use
 
-Permissions
+✅ **USE this skill when:**
+
+- User explicitly mentions "reminder" or "Reminders app"
+- Creating personal to-dos with due dates that sync to iOS
+- Managing Apple Reminders lists
+- User wants tasks to appear in their iPhone/iPad Reminders app
+
+## When NOT to Use
+
+❌ **DON'T use this skill when:**
+
+- Scheduling Clawdbot 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 a Clawdbot alert → clarify first
+
+## Setup
+
+- Install: `brew install steipete/tap/remindctl`
+- macOS-only; grant Reminders permission when prompted
 - Check status: `remindctl status`
 - Request access: `remindctl authorize`
 
-View Reminders
-- Default (today): `remindctl`
-- Today: `remindctl today`
-- Tomorrow: `remindctl tomorrow`
-- Week: `remindctl week`
-- Overdue: `remindctl overdue`
-- Upcoming: `remindctl upcoming`
-- Completed: `remindctl completed`
-- All: `remindctl all`
-- Specific date: `remindctl 2026-01-04`
-
-Manage Lists
-- List all lists: `remindctl list`
-- Show list: `remindctl list Work`
-- Create list: `remindctl list Projects --create`
-- Rename list: `remindctl list Work --rename Office`
-- Delete list: `remindctl list Work --delete`
-
-Create Reminders
-- Quick add: `remindctl add "Buy milk"`
-- With list + due: `remindctl add --title "Call mom" --list Personal --due tomorrow`
-
-Edit Reminders
-- Edit title/due: `remindctl edit 1 --title "New title" --due 2026-01-04`
-
-Complete Reminders
-- Complete by id: `remindctl complete 1 2 3`
-
-Delete Reminders
-- Delete by id: `remindctl delete 4A83 --force`
-
-Output Formats
-- JSON (scripting): `remindctl today --json`
-- Plain TSV: `remindctl today --plain`
-- Counts only: `remindctl today --quiet`
-
-Date Formats
+## Common Commands
+
+### View Reminders
+
+```bash
+remindctl                    # Today's reminders
+remindctl today              # Today
+remindctl tomorrow           # Tomorrow
+remindctl week               # This week
+remindctl overdue            # Past due
+remindctl all                # Everything
+remindctl 2026-01-04         # Specific date
+```
+
+### Manage Lists
+
+```bash
+remindctl list               # List all lists
+remindctl list Work          # Show specific list
+remindctl list Projects --create    # Create list
+remindctl list Work --delete        # Delete list
+```
+
+### Create Reminders
+
+```bash
+remindctl add "Buy milk"
+remindctl add --title "Call mom" --list Personal --due tomorrow
+remindctl add --title "Meeting prep" --due "2026-02-15 09:00"
+```
+
+### Complete/Delete
+
+```bash
+remindctl complete 1 2 3     # Complete by ID
+remindctl delete 4A83 --force  # Delete by ID
+```
+
+### Output Formats
+
+```bash
+remindctl today --json       # JSON for scripting
+remindctl today --plain      # TSV format
+remindctl today --quiet      # Counts only
+```
+
+## Date Formats
+
 Accepted by `--due` and date filters:
+
 - `today`, `tomorrow`, `yesterday`
 - `YYYY-MM-DD`
 - `YYYY-MM-DD HH:mm`
 - ISO 8601 (`2026-01-04T12:34:56Z`)
 
-Notes
-- macOS-only.
-- If access is denied, enable Terminal/remindctl in System Settings → Privacy & Security → Reminders.
-- If running over SSH, grant access on the Mac that runs the command.
+## Example: Clarifying User Intent
+
+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 a Clawdbot alert (I'll message you here)?"
+
+- Apple Reminders → use this skill
+- Clawdbot alert → use `cron` tool with systemEvent

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"
+```