From afb0e64262300caeb4cf37b00fa1390a637cedc5 Mon Sep 17 00:00:00 2001 From: Levi Neely Date: Tue, 14 Apr 2026 15:26:32 +0200 Subject: [PATCH] add reasoning skill Documents reasoning_think usage: when to use it, how to call it, and guidelines for effective scratchpad reasoning. Co-Authored-By: Claude Sonnet 4.6 --- anvillm-sessions/SKILL.md | 84 ----- beads/SKILL.md | 250 ------------- github-to-beads/SKILL.md | 51 --- reasoning/SKILL.md | 38 ++ .../SKILL.md | 0 shell-file-editing/SKILL.md | 336 ------------------ 6 files changed, 38 insertions(+), 721 deletions(-) delete mode 100644 anvillm-sessions/SKILL.md delete mode 100644 beads/SKILL.md delete mode 100644 github-to-beads/SKILL.md create mode 100644 reasoning/SKILL.md rename {ollie-session-management => session-management}/SKILL.md (100%) delete mode 100644 shell-file-editing/SKILL.md diff --git a/anvillm-sessions/SKILL.md b/anvillm-sessions/SKILL.md deleted file mode 100644 index 480cb1e..0000000 --- a/anvillm-sessions/SKILL.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -name: anvillm-sessions -intent: agents, sessions -description: Manage agent sessions (create, list, control). Use when spawning new agents, checking agent status, or controlling agent lifecycle. ---- - -# Anvillm Session Management - -Create and control agent sessions. - -## Commands - -List sessions: -``` -Tool: execute_tool -tool: list_sessions.sh -``` - -Create session: -``` -Tool: execute_tool -tool: create_session.sh -args: ["--backend", "", "--cwd", "", "--sandbox", "", "--model", ""] -``` - -Control session: -``` -Tool: execute_tool -tool: control_session.sh -args: ["--session-id", "", "--command", ""] -``` - -Spawn agent (requires default sandbox): -``` -Tool: execute_tool -tool: spawn_agent.sh -args: ["--agent-id", "", "--cwd", "", "--prompt", ""] -sandbox: default -``` -`--cwd` defaults to `$PWD`. `--prompt` is optional. - -Kill agent: -``` -Tool: execute_tool -tool: kill_agent.sh -args: ["--agent-id", ""] -``` - -## Backends - -- `kiro-cli` - Kiro CLI agent -- `claude` - Claude CLI agent -- `ollama` - Ollama agent - -## Session Lifecycle - -1. Create: `create_session.sh --backend kiro-cli --cwd /path/to/project --sandbox default` -2. Monitor: `list_sessions.sh` (check state field) -3. Control: `control_session.sh --session-id --command stop|restart|kill|refresh` - -## Session States - -- `starting` - Initializing -- `idle` - Ready for work -- `running` - Processing task -- `stopped` - Paused -- `error` - Failed -- `exited` - Terminated - -## When to Use - -- User asks to spawn/create a new agent -- Need to check agent status -- Need to stop/restart/kill an agent -- Coordinating multi-agent workflows - -## Session Handoff Pattern - -Agent A dies. Orphan cron detects dead assignee, calls `unclaim`. `BeadReady` fires on the event bus with full bead JSON including comments. Any waiting bot receives it via `wait_for_bead.sh`, claims the bead, and resumes — no bootstrap step, no agent-written snapshot. State lives in beads + git. - -## When NOT to Use - -- Sending messages to agents (use built-in communication tools: `send_message.sh`, `check_inbox.sh`) -- Managing tasks (use beads skill) diff --git a/beads/SKILL.md b/beads/SKILL.md deleted file mode 100644 index 09c4ebe..0000000 --- a/beads/SKILL.md +++ /dev/null @@ -1,250 +0,0 @@ ---- -name: beads -intent: tasks, workflow -description: Manage tasks using the beads 9P interface. Use when creating, updating, listing, or deleting tasks/beads, or managing task dependencies. ---- - -# Beads Skill - -## Project Mount Discovery - -Find your project's beads mount: -``` -Tool: execute_tool -tool: list_mounts.sh -``` -Then find the entry matching your cwd and extract the mount name. - -If no mount exists, create one (substitute actual path): -``` -Tool: execute_tool -tool: mount_beads.sh -args: ["--cwd", "/path/to/project"] -``` - -Initialize beads in a mount (creates .beads/): -``` -Tool: execute_tool -tool: init_beads.sh -args: ["--mount", "", "--prefix", ""] -``` - -## Tools - -All tools require `--mount `. Exceptions: `list_mounts.sh`, `mount_beads.sh`, `umount_beads.sh`. - -**CRITICAL:** Always use `sandbox: default` with beads tools. The tools derive scope from cwd, which must match the project directory. - -List mounts: -``` -Tool: execute_tool -tool: list_mounts.sh -sandbox: default -``` - -Wait for a bead on your mount (blocks until one is ready, returns full bead JSON including comments, then exits — bot decides whether to claim): -``` -Tool: execute_tool -tool: wait_for_bead.sh -args: ["--mount", ""] -sandbox: default -``` - -List ready beads (open, unblocked): -``` -Tool: execute_tool -tool: list_ready_beads.sh -args: ["--mount", ""] -sandbox: default -``` - -List all open beads (excludes closed): -``` -Tool: execute_tool -tool: list_beads.sh -args: ["--mount", ""] -sandbox: default -``` - -Search beads by id, title, or description (includes closed): -``` -Tool: execute_tool -tool: search_beads.sh -args: ["--mount", "", "--query", ""] -``` - -Lookup bead by ID: -``` -Tool: execute_tool -tool: search_beads.sh -args: ["--mount", "", "--id", ""] -``` - -**Note:** `list_beads.sh` and `list_ready_beads.sh` only return open beads. To find closed beads, use `search_beads.sh`. - -Read bead JSON: -``` -Tool: execute_tool -tool: read_bead.sh -args: ["--mount", "", "--id", "", "--property", "json"] -sandbox: default -``` - -Read bead comments: -``` -Tool: execute_tool -tool: read_bead_comments.sh -args: ["--mount", "", "--id", ""] -sandbox: default -``` - -**IMPORTANT:** When working on a bead, always check `comment_count` in the JSON output. If > 0, read comments for additional context, decisions, or blockers. - -Claim bead: -``` -Tool: execute_tool -tool: claim_bead.sh -args: ["--mount", "", "--id", ""] -sandbox: default -``` - -Complete bead: -``` -Tool: execute_tool -tool: complete_bead.sh -args: ["--mount", "", "--id", ""] -sandbox: default -``` - -Fail bead: -``` -Tool: execute_tool -tool: fail_bead.sh -args: ["--mount", "", "--id", "", "--reason", ""] -sandbox: default -``` - -Create bead (starts deferred — use open_bead.sh when ready): -``` -Tool: execute_tool -tool: create_bead.sh -args: ["--mount", "", "--title", "", "--desc", "<desc>", "--parent", "<id>"] -sandbox: default -``` -`--desc`, `--parent`, `--no-lint`, `--capability low|standard|high` are all optional. - -Update bead field: -``` -Tool: execute_tool -tool: update_bead.sh -args: ["--mount", "<mount>", "--id", "<id>", "--field", "<field>", "--value", "<value>"] -sandbox: default -``` -Valid fields: `title`, `description`, `design`, `acceptance_criteria`, `notes`, `issue_type`, `estimated_minutes`, `external_ref`, `spec_id`, `priority`, `due_at`, `work_type`. Status and assignee are managed by atomic operations only. - -Open (promote deferred to ready): -``` -Tool: execute_tool -tool: open_bead.sh -args: ["--mount", "<mount>", "--id", "<id>"] -sandbox: default -``` - -Defer bead: -``` -Tool: execute_tool -tool: defer_bead.sh -args: ["--mount", "<mount>", "--id", "<id>"] -sandbox: default -``` -Optional: append `"--until", "<RFC3339-time>"` to defer until a specific time. - -Reopen closed bead: -``` -Tool: execute_tool -tool: reopen_bead.sh -args: ["--mount", "<mount>", "--id", "<id>"] -sandbox: default -``` - -Relate two beads (soft link, no blocking): -``` -Tool: execute_tool -tool: relate_beads.sh -args: ["--mount", "<mount>", "--bead1", "<id-1>", "--bead2", "<id-2>"] -sandbox: default -``` - -Add dependency (child blocked by parent): -``` -Tool: execute_tool -tool: add_dependency.sh -args: ["--mount", "<mount>", "--child", "<child>", "--parent", "<parent>"] -sandbox: default -``` - -Comment on bead: -``` -Tool: execute_tool -tool: comment_bead.sh -args: ["--mount", "<mount>", "--id", "<id>", "--text", "<text>"] -sandbox: default -``` - -Label bead: -``` -Tool: execute_tool -tool: label_bead.sh -args: ["--mount", "<mount>", "--id", "<id>", "--label", "<label>"] -sandbox: default -``` - -Delete bead: -``` -Tool: execute_tool -tool: delete_bead.sh -args: ["--mount", "<mount>", "--id", "<id>"] -sandbox: default -``` - -**Note:** Delete does not cascade. To delete a parent and all children, delete children first, then parent. - -Unmount project: -``` -Tool: execute_tool -tool: umount_beads.sh -args: ["--mount", "<mount>"] -sandbox: default -``` -**Note:** Unmounting is an emergency stop. The orphan recovery cron will not spawn agents for unmounted projects. Remount to resume recovery. - -Sync project: -``` -Tool: execute_tool -tool: sync_beads.sh -args: ["--mount", "<mount>"] -sandbox: default -``` - -## Rules - -- Discover your mount first using mtab -- Claim before working -- Complete children before parent, if present -- Only parse JSON output -- Never access `.beads/` directly -- When creating, updating, or commenting on a bead, always escape JSON properly for bash -- Comment during work (decisions, dead ends, discoveries) -- Search past beads before starting -- Always favor atomic actions - - Good: `complete_bead.sh --mount myproj --id bd-123` - - Bad: `update_bead.sh --mount myproj --id bd-123 --field status --value closed` - -## Description Quality - -- The goal is to enable cold completion of the task, without additional research or code exploration -- Imperative verb + file path + `` `funcName()` `` or Acme file address (`/path/to/file:123,125` not `/path/to/file:123-125`) -- "How" signal (following X, same as Y) + acceptance criterion (must/should/returns) -- Backticked identifiers + cross-ref for >150 chars - -Bypass lint: title has `IDEA:` prefix. diff --git a/github-to-beads/SKILL.md b/github-to-beads/SKILL.md deleted file mode 100644 index 25e716d..0000000 --- a/github-to-beads/SKILL.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -name: github-to-beads -intent: tasks, github -description: Import GitHub issues and PRs into beads task tracking. Use when user asks to pull GitHub issue info, define work from an issue, or create tasks from GitHub. ---- - -# GitHub to Beads - -Import GitHub issues into beads. - -## Usage - -``` -Tool: execute_tool -tool: github_to_beads.sh -args: ["--mount", "<mount>", "--repo", "<owner/repo>", "--issue", "<issue_number>"] -``` - -**What it does:** -1. Fetches issue data via `gh` CLI -2. Creates bead: `#NUMBER: title` → title, body → description -3. Maps labels to issue_type (bug label → bug type) -4. Sets status (closed issues → closed status) -5. Parses task list (`- [ ]` items) as child beads -6. Skips if already imported - -## When to Use - -- User asks to "pull" or "import" a GitHub issue -- User wants to define work based on a GitHub issue -- User asks to create beads/tasks from GitHub - -## When NOT to Use - -- Just viewing issue info (use `gh issue view`) -- Modifying GitHub issues (this is pull-only) -- General bead management (use `beads` skill) - -## Manual GitHub Commands - -```bash -gh issue view 123 --repo owner/repo # human readable -gh issue view 123 --repo owner/repo --json number,title,body # JSON -``` - -## After Import - -Review and adjust: -- Remove beads bot doesn't need -- Refine descriptions -- Add context diff --git a/reasoning/SKILL.md b/reasoning/SKILL.md new file mode 100644 index 0000000..439a010 --- /dev/null +++ b/reasoning/SKILL.md @@ -0,0 +1,38 @@ +--- +name: reasoning +intent: think, reasoning, scratchpad, planning, problem-solving +description: Guidance on using reasoning_think for internal scratchpad reasoning before acting. +--- + +# Reasoning + +Use `reasoning_think` before acting on any non-trivial task. It is an internal scratchpad — the thought is recorded in conversation history but not shown to the user. + +## When to use + +- Breaking down a complex problem before writing code or running commands +- Analyzing constraints and requirements before committing to an approach +- Considering alternative approaches and their trade-offs +- Working through multi-step logic or edge cases +- Validating assumptions before acting on them + +## How to use + +Call `reasoning_think` with your full internal reasoning as the argument. Be thorough — this is your scratch space. + +``` +execute_tool: reasoning_think +args: [ + "The user wants to refactor the auth middleware. I need to check what + calls it before changing the interface, otherwise I'll break callers. + Plan: 1) grep for usages, 2) understand the interface, 3) make the + change, 4) verify callers still compile." +] +``` + +## Guidelines + +- Think before acting, not after +- Keep thoughts focused on the current decision +- One `reasoning_think` per decision point is enough — don't over-narrate +- Do not use it to communicate with the user; write responses directly diff --git a/ollie-session-management/SKILL.md b/session-management/SKILL.md similarity index 100% rename from ollie-session-management/SKILL.md rename to session-management/SKILL.md diff --git a/shell-file-editing/SKILL.md b/shell-file-editing/SKILL.md deleted file mode 100644 index f386e8b..0000000 --- a/shell-file-editing/SKILL.md +++ /dev/null @@ -1,336 +0,0 @@ ---- -name: shell-file-editing -intent: file editing, text editing, ed, sed, ssam -description: Recipes for reading and editing files using standard Unix tools (ed, sed) and plan9port ssam. Use when modifying files via execute_code. -user-invocable: false ---- - -# Shell File Editing - -Use `execute_code` with standard tools. Never guess line numbers — always grep first. - -## Locate Before Editing - -```sh -grep -n 'pattern' file # line numbers for matches -cat -n file # full file with line numbers -grep -n 'pattern' file | head # narrow to area of interest -``` - -## ed — Scripted Line Editing - -`ed` operates on whole lines. Drive it with a heredoc; use `-s` to suppress noise. - -### Address syntax - -``` -n line number (1-based) -$ last line -. current line (last affected) -, whole file (shorthand for 1,$) -/pattern/ next line matching pattern -?pattern? previous line matching pattern -n,m line range inclusive -/pat1/,/pat2/ range from first match to second -``` - -### Substitute on a matching line - -```sh -ed -s file <<'EOF' -/pattern/s/old/new/ -w -q -EOF -``` - -### Global substitute (all occurrences in file) - -```sh -ed -s file <<'EOF' -,s/old/new/g -w -q -EOF -``` - -### Delete lines matching a pattern - -```sh -ed -s file <<'EOF' -g/pattern/d -w -q -EOF -``` - -### Delete a line range - -```sh -ed -s file <<'EOF' -5,10d -w -q -EOF -``` - -### Insert text before a matching line - -```sh -ed -s file <<'EOF' -/pattern/i -new line of text -. -w -q -EOF -``` - -### Append text after a matching line - -```sh -ed -s file <<'EOF' -/pattern/a -new line of text -. -w -q -EOF -``` - -### Replace a range of lines - -```sh -ed -s file <<'EOF' -/start_pattern/,/end_pattern/c -replacement line 1 -replacement line 2 -. -w -q -EOF -``` - -### Replace exact line range - -```sh -ed -s file <<'EOF' -3,7c -new content -. -w -q -EOF -``` - -### Append at beginning of file (address 0) - -```sh -ed -s file <<'EOF' -0a -first line -. -w -q -EOF -``` - -### Move lines - -```sh -ed -s file <<'EOF' -5,8m12 -w -q -EOF -``` - -### Print without modifying (verify before write) - -```sh -ed -s file <<'EOF' -,p -q -EOF -``` - -### Multi-step script - -```sh -ed -s file <<'EOF' -/^func foo/,/^}/c -func foo(x int) int { - return x * 2 -} -. -,s/OldName/NewName/g -w -q -EOF -``` - -### Key points - -- Input mode (`a`, `i`, `c`) ends with a lone `.` on its own line -- `g/re/cmd` runs cmd on every matching line; useful with `d`, `s`, `p` -- `wq` writes and quits in one command -- Substitute delimiter can be any non-space non-newline character: `s|/path/a|/path/b|` -- `\n` in replacement introduces a newline (splits the line) - ---- - -## sed — Stream Substitution - -Best for simple in-place substitutions. Single-pass; cannot insert multi-line -blocks as easily as ed. - -### In-place substitution (GNU sed) - -```sh -sed -i 's/old/new/g' file -``` - -### In-place on multiple files - -```sh -sed -i 's/old/new/g' *.go -``` - -### Substitute only on lines matching a pattern - -```sh -sed -i '/pattern/s/old/new/' file -``` - -### Delete lines matching a pattern - -```sh -sed -i '/pattern/d' file -``` - -### Delete a line range - -```sh -sed -i '5,10d' file -``` - -### Print a line range (no modification) - -```sh -sed -n '10,20p' file -``` - -### Multiple expressions - -```sh -sed -i -e 's/foo/bar/g' -e 's/baz/qux/g' file -``` - -### Address forms - -``` -n line n -$ last line -/regexp/ lines matching regexp -n,m range -/a/,/b/ range between patterns -n,+k line n and k lines after it -``` - -### Key points - -- GNU sed: `-i` with no suffix. BSD sed: `-i ''`. Prefer `ed` for portability. -- sed makes one pass; edits to earlier lines do not affect later address matching -- Use `ed` when inserting or replacing blocks of multiple lines - ---- - -## ssam — Structural Editing (plan9port) - -`ssam` uses sam's command language. Selects structurally (by regex), not by -line number. Entire input is loaded before the script runs. - -Check availability: `command -v ssam` - -### Basic syntax - -``` -ssam 'address command' file -ssam -n 'address command' file # suppress default output -``` - -On invocation, the entire file is selected (dot = `,`). - -### Address syntax - -``` -, whole file -n line n -/regexp/ next match of regexp -?regexp? previous match -#n character offset n (#0 = start of file) -$ end of file -. current selection (dot) -a1,a2 from start of a1 to end of a2 -``` - -### Print first 10 lines - -```sh -ssam -n ',10p' file -``` - -### Global substitution - -```sh -ssam 's/old/new/g' file -``` - -### Substitute within lines matching a pattern - -```sh -ssam 'x/.*pattern.*\n/ s/old/new/' file -``` - -### Delete empty lines - -```sh -ssam 's/\n\n+/\n/g' file -``` - -### Print one word per line - -```sh -ssam -n 'y/[a-zA-Z]+/ c/\n/' file -``` - -### Structural loop: run command on each match - -```sh -# x selects each match of the pattern, then runs the sub-command on it -ssam 'x/pattern/ c/replacement/' file -``` - -### Conditional: run command only if range contains match - -```sh -ssam 'g/pattern/ s/old/new/' file # only lines containing pattern -ssam 'v/pattern/ s/old/new/' file # only lines NOT containing pattern -``` - -### Key points - -- ssam consumes all of stdin before running; safe for in-place style pipelines -- `x/re/ cmd` iterates over all non-overlapping matches; nested `x` is legal -- `y/re/ cmd` iterates over the text *between* matches -- `g/re/ cmd` and `v/re/ cmd` are guards (if-contains / if-not-contains) -- To write back in place: `ssam 'script' file > tmp && mv tmp file` - ---- - -## Workflow - -1. Locate with `grep -n` or `cat -n` -2. Preview the change with `ed -s file <<'EOF'\n,p\nq\nEOF` or `sed -n` -3. Apply the edit -4. Verify with `grep` or `cat -n` that the change landed correctly