geekbot-cli 0.1.0

package/skills/geekbot/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: geekbot
+description: >
+  Use when the user mentions Geekbot, standups, daily check-ins, async
+  reports, polls, team engagement, response rates, or participation
+  tracking. Triggers on: "standup", "check-in", "report", "poll",
+  "Geekbot", "who hasn't posted", "draft my standup", "team analytics".
+---
+
+# Geekbot — AI-Powered Standup & Poll Management
+
+## Overview
+
+This skill wraps the `geekbot` CLI to let users manage async team rituals
+conversationally. It handles two broad workflows:
+
+- **Manager workflows** — create standups/polls from templates, edit configs,
+  manage members and schedules, analyse team engagement from report data
+- **Reporter workflows** — draft standup reports with AI assistance, carry
+  over unresolved blockers, calibrate tone from history, post reports
+
+The CLI produces structured JSON output with machine-readable error codes,
+making it reliable for agent-driven automation.
+
+## Prerequisites
+
+Before any operation, verify the CLI is available and authenticated.
+
+Run `check-cli.sh` on first invocation. If it fails:
+
+- **CLI not found**: Install via `npm install -g geekbot-cli` (requires
+  Bun >= 1.3.5 runtime). Note: `npx geekbot-cli` also requires Bun on
+  PATH — it is not a Node.js fallback.
+- **Auth not configured**: Guide the user to run `geekbot auth setup`
+  which stores the API key in the OS keychain. Alternatively they can
+  set `GEEKBOT_API_KEY` as an environment variable.
+
+Do not attempt any Geekbot operation until both checks pass.
+
+## How the CLI Works
+
+The CLI follows a noun-verb pattern: `geekbot <resource> <action> [options]`.
+
+Every command returns a JSON envelope on stdout:
+
+```
+Success: { "ok": true,  "data": <T>,  "error": null,  "metadata": {...} }
+Error:   { "ok": false, "data": null,  "error": { "code", "message", "retryable", "suggestion" }, "metadata": {...} }
+```
+
+Always check the `ok` field first. On errors, the `error.suggestion` field
+often contains the exact fix — including listing valid IDs when a resource
+isn't found. Use this to self-correct without bothering the user.
+
+For the full command reference with flags, defaults, and examples, read
+`cli-commands.md`.
+
+## Quick Reference
+
+Most common operations at a glance:
+
+| Task | Command |
+|------|---------|
+| List my standups | `geekbot standup list` (add `--brief` for compact output, `--name`/`--channel` to filter, `--mine` for member-only, `--member <id>` for a specific user, `--limit <n>` to cap results) |
+| Get standup details + question IDs | `geekbot standup get <id>` |
+| Create a standup | `geekbot standup create --name "..." --channel "..." --questions '[...]'` |
+| Update a standup (PATCH) | `geekbot standup update <id> --time "09:30"` |
+| Delete a standup | `geekbot standup delete <id> --yes` |
+| List reports | `geekbot report list --standup-id <id> --limit 10` |
+| Submit a report | `geekbot report create --standup-id <id> --answers '{"<qid>":"..."}'` |
+| My profile + user ID | `geekbot me show` |
+| Create a poll (Slack only) | `geekbot poll create --name "..." --channel "..." --question "..." --choices '[...]'` |
+| Search team members | `geekbot team search <query>` (matches username, realname, email) |
+| Check auth | `geekbot auth status` |
+
+For full flag details, see `cli-commands.md`.
+
+## External Context Enrichment
+
+The skill becomes dramatically more useful when it can pull data from where
+work actually happens. This is **opportunistic** — check what MCP servers
+are connected in the current session and use whatever is available. Never
+fail or complain if nothing is connected; just fall back to asking the user.
+
+**For report drafting:** Pull the user's recent activity from connected MCP
+servers (GitHub, Jira, Calendar, Slack) and use it to pre-populate a draft.
+The user reviews and approves instead of writing from scratch.
+
+**For analytics:** Cross-reference standup report data with delivery data
+to give richer insights — not just "who posted" but "what was actually shipped."
+
+For entity mapping tables and deduplication strategy, see `reporter-workflows.md`.
+
+**Important boundaries:**
+- Always show the user what data you pulled and from where
+- Never post a report containing enrichment data without user review
+- If an MCP server query fails, skip it silently and move on
+- Enrichment provides specifics (PR numbers, ticket IDs); the user's
+  voice still drives the narrative
+
+## Intent Routing
+
+Pattern-match on the user's request to pick the right workflow. Don't ask
+"are you a manager or a reporter?" — the request itself makes intent clear.
+The same person can manage standups and submit reports in one conversation.
+
+**Route to Manager Workflows (§ below) when you see:**
+- Creation/config language: "create", "set up", "configure", "schedule",
+  "add members", "change the questions", "duplicate", "delete"
+- Analytics language: "how is my team doing", "engagement", "response rate",
+  "who hasn't posted", "participation", "trends"
+- Member summary language: "what has X been up to", "X's reports",
+  "1-1 prep for X", "summarize X's work", "what did X report",
+  "catch me up on X", "X's recent standups"
+- Poll language: "create a poll", "voting results", "survey"
+
+**Route to Reporter Workflows (§ below) when you see:**
+- Drafting language: "help me write", "draft my report", "what should I say",
+  "fill in my standup"
+- Posting language: "post my answers", "submit my report"
+- Context language: "what did I say last time", "carry over blockers",
+  "my recent reports"
+- Identity queries: "what standups am I in", "show my profile"
+
+**When ambiguous**, ask one clarifying question — never more than one.
+
+## Manager Workflows
+
+For detailed multi-step guides, read `manager-workflows.md`.
+
+### Creating a Standup
+
+This is the most common and most complex manager operation.
+
+**If the request is vague** ("set up a standup for my team"), offer templates.
+Load `standup-templates.json` and present the 3–4 most relevant options
+based on context. Templates provide pre-built questions and sensible schedule
+defaults — the user just needs to supply a name and Slack/Teams channel.
+
+**Gathering required fields:**
+- `--name` — the standup name (required)
+- `--channel` — Slack/Teams channel to post in (required)
+- `--questions` — JSON array of question objects (required; from template or custom)
+- `--time` — defaults to 10:00 if not specified
+- `--timezone` — infer from `geekbot me show` → `data.timezone` if not given
+- `--days` — defaults to Mon–Fri
+- `--users` — comma-separated user IDs (can add later via `update`)
+
+**Always confirm the full configuration with the user before executing.**
+Show: name, channel, questions, schedule, timezone.
+
+**Note:** The CLI sets which days of the week to run but cannot set frequency
+(bi-weekly, monthly). For non-weekly schedules, create the standup via CLI
+and tell the user to adjust the frequency in the Geekbot web dashboard.
+
+### Editing / Deleting / Other Operations
+
+- **Edit**: Fetch current state with `standup get`, show the user, confirm
+  changes, use `standup update` (PATCH). Use `standup replace` only for
+  full config replacement.
+- **Delete**: Always fetch and show what will be deleted first. Get explicit
+  confirmation. Execute with `--yes`.
+- **Duplicate**: `geekbot standup duplicate <id> --name "New Name"`
+- **Trigger now**: `geekbot standup start <id>` — confirm before executing.
+- **Polls** (Slack only): See `cli-commands.md` for poll commands.
+
+### Analytics
+
+Analytics come from report data fetched via the CLI. The skill computes
+metrics; the CLI provides raw data. For the full analytics playbook with
+6 named analysis patterns (response rate, participation gaps, blocker
+frequency, trends, answer quality, cross-referencing), read
+`manager-workflows.md`.
+
+**Quick start:** Identify the standup with `standup list`, get member count
+with `standup get <id>`, fetch reports with
+`report list --standup-id <id> --after <date> --limit 100`, then compute.
+
+### Team Member Summary
+
+Summarize what a specific person has been working on — ideal for 1-1 prep.
+For the full step-by-step workflow, read `manager-workflows.md` §Team Member
+Summary.
+
+**Quick start:** `geekbot team search <name>` → get user ID →
+`geekbot standup list --member <id> --brief` to find their standups →
+`geekbot report list --standup-id <sid> --user-id <id> --after <3 weeks ago> --limit 20` →
+synthesize by work stream, not chronologically.
+
+## Reporter Workflows
+
+For the full drafting pipeline, tone calibration, blocker carry-over logic,
+and edge cases, read `reporter-workflows.md`.
+
+### Report Drafting Pipeline (Summary)
+
+1. **Identify the standup** — `standup list`, auto-select if only one
+2. **Fetch questions** — `standup get <id>` → extract question IDs and text
+3. **Gather context** — from MCP servers (if connected), previous reports
+   (for style calibration), and the user's direct input
+4. **Draft answers** — match their historical tone/length, weave in specifics
+   from MCP data, run blocker carry-over check on last 3–5 reports
+5. **Review and post** — present draft, get explicit approval, then
+   `report create --standup-id <id> --answers '{...}'`
+
+**Never post a report without explicit user approval.**
+
+### Quick Actions
+
+One-shot commands that don't need the full pipeline:
+
+- **"What standups am I in?"** → `geekbot standup list`
+- **"Show my recent reports"** → `geekbot report list --user-id <uid> --limit 5`
+- **"Show my profile"** → `geekbot me show`
+- **"What teams am I in?"** → `geekbot me teams`
+- **"Trigger my standup now"** → confirm first, then `geekbot standup start <id>`
+
+## Confirmation Policy
+
+| Operation | Confirmation required? | What to show |
+|-----------|----------------------|--------------|
+| CREATE standup/poll | Yes | Full config: name, channel, questions, schedule |
+| UPDATE standup | Yes | Current vs proposed (diff) |
+| DELETE standup | Yes, always | What will be deleted (name, channel, members) |
+| POST report | Yes, always | Complete draft with all answers |
+| TRIGGER standup | Yes | Which standup, who it targets |
+| List / Get / Analytics | No | Just execute and present results |
+| Error recovery retries | No | Transparent to user |
+
+## Error Handling
+
+For the complete recovery guide, read `error-recovery.md`.
+
+**Core pattern**: always parse the JSON envelope, check `ok`, branch on
+exit code.
+
+| Exit code | Meaning | Agent action |
+|-----------|---------|--------------|
+| 0 | Success | Proceed normally |
+| 3 | Not found | Parse `error.suggestion` — it lists valid IDs. Offer them to the user. |
+| 4 | Auth failed | Guide user through `geekbot auth setup`. Do not retry. |
+| 5 | Forbidden | Explain permission issue. The user may need admin access. |
+| 6 | Validation | Show `error.message`, help the user fix the input. |
+| 7 | Network | If `error.retryable` is true, retry once after 2s silently. If it fails again, report. |
+| 8 | Conflict | Explain the conflict (e.g., duplicate name). Suggest resolution. |
+| 9 | Schema validation (`schema_validation_error`) | API response didn't match expected format. Don't ask user to fix input — suggest updating CLI or reporting a bug. |
+| 1, 2, 9 | General / usage / API | Report `error.message` to the user clearly. |
+
+**Never retry** errors where `retryable` is false.
+
+## Common Mistakes
+
+- **Inventing report answers** — if the user didn't provide enough context
+  for a question, ask. Never guess or fabricate.
+- **Retrying auth errors** — exit code 4 is never transient. Guide the user
+  to `geekbot auth setup` instead.
+- **Skipping confirmation for deletes** — always show what will be deleted
+  and get explicit approval, even if it feels obvious.
+- **Dumping raw JSON** — format output as tables, summaries, or narratives.
+  The user should never see a raw JSON envelope.
+- **Ignoring `error.suggestion`** — when a resource isn't found (exit 3),
+  the CLI already lists valid alternatives. Use them.
+- **Asking "are you a manager or reporter?"** — the request itself reveals
+  intent. Pattern-match, don't interrogate.
+
+## Output Patterns
+
+**CRUD confirmations** — brief, factual, include key identifiers:
+> Created "Sprint Retro" standup (ID 789) in #engineering — Fridays at
+> 15:00 Chicago time with 3 questions.
+
+**Lists** — concise table: ID, name, channel, schedule. Don't dump raw JSON.
+
+**Analytics** — narrative summary first, data table for details. Use
+visualisation (chart/graph) when showing trends over time.
+
+**Report drafts** — one question per block, clearly labelled with question
+text and proposed answer. Easy to scan and approve.
+
+**Errors** — plain language: what happened, why, what to do next. Always
+use `error.suggestion` when available.

package/skills/geekbot/check-cli.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Verify geekbot CLI is installed and authenticated.
+# Run at the start of any skill invocation.
+# Exit 0 = ready, Exit 1 = not installed, Exit 2 = not authed
+
+set -euo pipefail
+
+# Check CLI exists on PATH
+if ! command -v geekbot &>/dev/null; then
+  cat <<'EOF'
+{"ok":false,"error":"cli_not_found","message":"geekbot CLI not found on PATH.","suggestion":"Install: npm install -g geekbot-cli (requires Bun >= 1.3.5). Then run: npx skills add geekbot-com/geekbot-cli to register the skill with your AI agents."}
+EOF
+  exit 1
+fi
+
+# Check version (confirms the binary actually runs)
+VERSION_OUTPUT=$(geekbot --version 2>&1 || true)
+if [ -z "$VERSION_OUTPUT" ]; then
+  cat <<'EOF'
+{"ok":false,"error":"cli_broken","message":"geekbot CLI found but failed to run.","suggestion":"Try: bun install in the geekbot-cli directory, then bun link again"}
+EOF
+  exit 1
+fi
+
+# Check auth — use exit code instead of jq to avoid extra dependency
+if ! geekbot auth status &>/dev/null; then
+  cat <<'EOF'
+{"ok":false,"error":"auth_not_configured","message":"geekbot CLI is not authenticated.","suggestion":"Run: geekbot auth setup"}
+EOF
+  exit 2
+fi
+
+# All good — sanitize version to alphanumeric + dots before embedding in JSON
+SAFE_VERSION=$(echo "$VERSION_OUTPUT" | tr -cd '[:alnum:].')
+echo "{\"ok\":true,\"version\":\"${SAFE_VERSION}\",\"message\":\"geekbot CLI is installed and authenticated\"}"
+exit 0

package/skills/geekbot/cli-commands.md

@@ -0,0 +1,382 @@
+# Geekbot CLI — Command Reference
+
+Agent-optimised reference for the `geekbot` CLI. Every command returns a
+JSON envelope: `{ ok, data, error, metadata }`. Always check `ok` first.
+
+## Table of Contents
+
+1. [Standup commands](#standup)
+2. [Report commands](#report)
+3. [Poll commands](#poll)
+4. [Identity commands](#identity)
+5. [Auth commands](#auth)
+6. [Global options](#global-options)
+
+---
+
+## Standup
+
+### standup list
+
+List standups the authenticated user participates in, with optional
+client-side filtering and a brief output mode.
+
+```bash
+geekbot standup list                            # all your standups
+geekbot standup list --admin                    # all team standups (admin only)
+geekbot standup list --brief                    # compact: id, name, channel only
+geekbot standup list --brief --limit 10         # first 10, compact
+geekbot standup list --name "daily"             # filter by name (case-insensitive substring)
+geekbot standup list --channel "#status"        # filter by channel (case-insensitive substring)
+geekbot standup list --mine                     # only standups you are a member of
+geekbot standup list --member "UHNM44125"       # only standups a specific user is in
+geekbot standup list --mine --brief             # combine filters
+```
+
+| Flag | Default | Notes |
+|------|---------|-------|
+| `--admin` | `false` | Include all team standups (admin only) |
+| `--brief` | `false` | Return only `id`, `name`, `channel` |
+| `--limit <n>` | — | Cap results to first N standups (applied after filters) |
+| `--name <name>` | — | Case-insensitive substring filter on standup name |
+| `--channel <channel>` | — | Case-insensitive substring filter on channel name |
+| `--mine` | `false` | Filter to standups where you appear in the members list |
+| `--member <id>` | — | Filter to standups where the given user ID is a member |
+
+**Note:** `--name`, `--channel`, `--mine`, `--member`, and `--limit` are
+client-side filters applied after fetching. `--mine` makes one extra API call
+(`GET /v1/me`) to resolve your user ID.
+
+Returns: `data` is an array of standup objects. With `--brief`, each object
+contains only `id`, `name`, `channel`. Without `--brief`, full standup
+objects with `questions`, `users`, and all fields.
+
+### standup get
+
+Get full details of a standup including questions with their IDs.
+
+```bash
+geekbot standup get 123
+```
+
+Returns: `data` includes `id`, `name`, `channel`, `time`, `timezone`, `days`,
+`questions` (array of `{ id, text }`), member info.
+
+This is the primary way to discover question IDs for report submission.
+
+### standup create
+
+Create a new standup. Name and channel are required.
+
+```bash
+geekbot standup create \
+  --name "Sprint Retro" \
+  --channel "#engineering" \
+  --time "15:00" \
+  --timezone "America/Chicago" \
+  --days "Fri" \
+  --questions '[{"text": "What went well?"}, {"text": "What could improve?"}]' \
+  --users "U123,U456" \
+  --wait-time 0
+```
+
+| Flag | Required | Default | Notes |
+|------|----------|---------|-------|
+| `--name <name>` | Yes | — | Standup name |
+| `--channel <channel>` | Yes | — | Slack/Teams channel name |
+| `--time <HH:MM>` | No | `10:00` | 24-hour format |
+| `--timezone <tz>` | No | `UTC` | IANA timezone (e.g. `Europe/Athens`) |
+| `--days <days>` | No | `Mon,Tue,Wed,Thu,Fri` | Comma-separated |
+| `--questions <json>` | Yes | — | JSON array: `[{"text": "..."},...]` |
+| `--users <ids>` | No | — | Comma-separated user IDs |
+| `--wait-time <min>` | No | `0` | Minutes between users |
+
+Returns: `data` is the created standup object. `metadata` includes an
+`undo` field with the delete command.
+
+**Tip**: If you know the user's timezone from `geekbot me show`, use it
+as the default instead of UTC.
+
+**Limitation**: The `--days` flag controls which days of the week the standup
+runs, but there is no flag for frequency (bi-weekly, monthly, etc.). For
+non-weekly schedules, create the standup via CLI and direct the user to
+adjust the frequency in the Geekbot web dashboard.
+
+### standup update (PATCH)
+
+Partially update a standup. Only pass the flags you want to change.
+
+```bash
+geekbot standup update 123 --time "09:30" --days "Mon,Wed,Fri"
+geekbot standup update 123 --users "U123,U456,U789"
+geekbot standup update 123 --questions '["What did you do?","Any blockers?"]'
+```
+
+| Flag | Notes |
+|------|-------|
+| `--name <name>` | New standup name |
+| `--channel <channel>` | New channel |
+| `--time <HH:MM>` | New time |
+| `--timezone <tz>` | New timezone |
+| `--days <days>` | New days (replaces all) |
+| `--questions <json>` | New questions (replaces all) |
+| `--wait-time <min>` | New wait time |
+| `--users <ids>` | New member list (replaces all) |
+
+**Important**: `--users` replaces the entire member list. To add a member,
+fetch the current list first, append the new ID, and send the full list.
+
+### standup replace (PUT)
+
+Full replacement of a standup. Name and channel are required; everything
+else uses create defaults if omitted.
+
+```bash
+geekbot standup replace 123 \
+  --name "New Name" \
+  --channel "#new-channel" \
+  --time "11:00" \
+  --timezone "UTC"
+```
+
+Use `replace` only when you want to reset the entire config. Prefer
+`update` for partial changes.
+
+### standup delete
+
+Delete a standup permanently. Always pass `--yes` in agent context.
+
+```bash
+geekbot standup delete 123 --yes
+```
+
+The skill should confirm with the user conversationally before executing.
+
+### standup duplicate
+
+Clone an existing standup with a new name.
+
+```bash
+geekbot standup duplicate 123 --name "Backend Daily v2"
+```
+
+Returns: the new standup object with a new ID.
+
+### standup start
+
+Trigger a standup immediately (outside its normal schedule).
+
+```bash
+geekbot standup start 123
+geekbot standup start 123 --users "U123,U456"    # target specific users
+```
+
+---
+
+## Report
+
+### report list
+
+List reports with optional filters. All filters are optional.
+
+```bash
+# Recent reports for a standup
+geekbot report list --standup-id 123 --limit 10
+
+# A specific user's reports
+geekbot report list --standup-id 123 --user-id U08LXSA31BJ --limit 5
+
+# Date range
+geekbot report list --standup-id 123 --after "2026-03-01" --before "2026-03-15"
+```
+
+| Flag | Notes |
+|------|-------|
+| `--standup-id <id>` | Filter by standup |
+| `--user-id <id>` | Filter by user (Slack-style ID like `U08LXSA31BJ`) |
+| `--before <date>` | ISO 8601 date or unix timestamp |
+| `--after <date>` | ISO 8601 date or unix timestamp |
+| `--limit <n>` | Max reports to return |
+
+Returns: `data` is an array of report objects, each containing `id`,
+`standup_id`, `questions` (array of `{ id, text, answer }`).
+
+### report create
+
+Submit a report. Answers are keyed by question ID.
+
+```bash
+geekbot report create \
+  --standup-id 123 \
+  --answers '{"101": "Finished auth module", "102": "Starting API tests", "103": "None right now"}'
+```
+
+| Flag | Required | Notes |
+|------|----------|-------|
+| `--standup-id <id>` | Yes | Which standup to report on |
+| `--answers <json>` | Yes | JSON object: `{"<question_id>": "<answer>", ...}` |
+
+Get question IDs from `geekbot standup get <standup_id>`.
+
+**Critical**: Never submit a report without explicit user approval.
+
+---
+
+## Poll
+
+Polls are Slack-only. Non-Slack teams will get a platform error.
+
+### poll list
+
+```bash
+geekbot poll list
+```
+
+Returns: array of poll objects.
+
+### poll get
+
+```bash
+geekbot poll get 456
+```
+
+Returns: poll details including question and choices.
+
+### poll create
+
+```bash
+geekbot poll create \
+  --name "Team Lunch" \
+  --channel "#general" \
+  --question "Where should we eat?" \
+  --choices '["Pizza", "Sushi", "Tacos"]'
+```
+
+| Flag | Required |
+|------|----------|
+| `--name <name>` | Yes |
+| `--channel <channel>` | Yes |
+| `--question <text>` | Yes |
+| `--choices <json>` | Yes — JSON array of strings |
+
+### poll votes
+
+View voting results for a poll.
+
+```bash
+geekbot poll votes 456
+geekbot poll votes 456 --after "2026-03-01" --before "2026-03-15"
+```
+
+---
+
+## Identity
+
+### me show
+
+Get the authenticated user's profile. Use this to discover the user's ID,
+timezone, and admin status.
+
+```bash
+geekbot me show
+```
+
+Returns:
+```json
+{
+  "id": "U08LXSA31BJ",
+  "username": "mitch",
+  "realname": "mitch",
+  "email": "mitch@geekbot.com",
+  "timezone": "Europe/Athens",
+  "is_admin": true,
+  "role": "admin"
+}
+```
+
+The `id` field is a Slack-style user ID — use it for `--user-id` filters
+and `--users` member lists.
+
+The `timezone` field is an IANA timezone — use it as a default for standup
+creation when the user doesn't specify one.
+
+### me teams
+
+List teams the user belongs to.
+
+```bash
+geekbot me teams
+```
+
+### team list
+
+List all teams with their members.
+
+```bash
+geekbot team list
+```
+
+### team search
+
+Search team members by name, username, or email. Case-insensitive
+substring match across all three fields.
+
+```bash
+geekbot team search jenny                 # match by username or realname
+geekbot team search "Smith"               # match by realname
+geekbot team search @example.com          # match by email domain
+```
+
+Returns: `data` is an array of matching user objects with `id`, `role`,
+`email`, `username`, `realname`, `profile_img`. Use the `id` field as
+the `--user-id` value for `report list`.
+
+---
+
+## Auth
+
+### auth setup
+
+Configure and store the API key. Validates against the Geekbot API.
+
+```bash
+geekbot auth setup                        # interactive prompt
+geekbot --api-key YOUR_KEY auth setup     # non-interactive
+```
+
+### auth status
+
+Verify stored credentials work.
+
+```bash
+geekbot auth status
+```
+
+Returns `ok: true` if auth is valid.
+
+### auth remove
+
+Remove stored API key from OS keychain.
+
+```bash
+geekbot auth remove
+```
+
+---
+
+## Global Options
+
+Apply to all commands:
+
+| Flag | Default | Notes |
+|------|---------|-------|
+| `--api-key <key>` | — | Override env var and keychain |
+| `--output <format>` | `json` | Only `json` currently supported |
+| `--debug` | `false` | Debug output on stderr |
+| `-v, --version` | — | Print version |
+| `--help` | — | Show help text |
+
+## Exit Codes
+
+See the error handling table in `SKILL.md` for exit codes and agent actions.
+For detailed recovery flows, see `error-recovery.md`.