
toolkit
General purpose Claude Code toolkit with research agents, skills, and introspection commands
- version
- 0.1.6-rc5
- GitHub stars
- 24
Install
/plugin install toolkit@claude-toolkitRun it inside Claude Code after adding the marketplace with /plugin marketplace add dwmkerr/claude-toolkit.
Contents
Discovered from sourceSkills 16
Agent Development
Create effective Claude Code agents.
Agent Colors
Agents support color assignments for visual distinction. Set in YAML frontmatter:
---
name: explore
description: Explores codebases
color: purple
---
Color Conventions
| Color | Agent Type | Purpose |
|---|---|---|
| Purple | Explore | Codebase exploration, documentation |
| Blue | Plan | Analysis, planning, architecture |
| Green | Create | Testing, creation, validation |
| Orange | Debug | Debugging, refactoring |
| Yellow | Clean | Optimization, cleanup |
| Red | Reflect | Security, critical review |
| Pink | - | Available |
| Cyan | - | Orchestration, coordination |
Agent Behavior
Permission Denial Resilience
Subagents continue after permission denial rather than stopping entirely. When a subagent hits a permissions wall, it tries alternative approaches automatically. This makes autonomous workflows more resilient and reduces the need for human intervention.
Important
After creating or modifying agents, inform the user:
No restart needed. Agent changes take effect immediately - agents are hot-reloaded.
Anthropic Evaluations
Build rigorous evaluations for AI agents using Anthropic's proven patterns.
Quick Reference
You MUST read the reference files for detailed guidance:
- Grader Types - Code-based, model-based, human graders
- Agent Type Patterns - Coding, conversational, research, computer use
- Roadmap - Steps 0-8 for building evals from scratch
- Frameworks - Harbor, Promptfoo, Braintrust, etc.
YAML Templates:
- coding-agent-eval.yaml - Coding agent template
- conversational-agent-eval.yaml - Support agent template
Annotated Examples:
- Example: Coding Agent - Auth bypass fix walkthrough
- Example: Conversational - Refund handling walkthrough
Core Definitions
| Term | Definition |
|---|---|
| Task | Single test with defined inputs and success criteria |
| Trial | One attempt at a task (run multiple for consistency) |
| Grader | Logic that scores agent performance; tasks can have multiple |
| Transcript | Complete record of a trial (outputs, tool calls, reasoning) |
| Outcome | Final state in environment (not just what agent said) |
| Evaluation harness | Infrastructure that runs evals end-to-end |
| Agent harness | System enabling model to act as agent (scaffold) |
| Evaluation suite | Collection of tasks measuring specific capabilities |
Grader Types (Quick Reference)
| Type | Methods | Best For |
|---|---|---|
| Code-based | String match, unit tests, static analysis, state checks | Fast, cheap, objective verification |
| Model-based | Rubric scoring, assertions, pairwise comparison | Nuanced, open-ended tasks |
| Human | SME review, A/B testing, spot-check sampling | Gold standard calibration |
See Grader Types for detailed comparison.
Capability vs Regression Evals
| Type | Question | Target Pass Rate |
|---|---|---|
| Capability | "What can this agent do well?" | Start low, hill-climb |
| Regression | "Does it still handle what it used to?" | Near 100% |
Capability evals with high pass rates "graduate" to regression suites.
Non-Determinism Metrics
| Metric | Measures | Use When |
|---|---|---|
| pass@k | At least 1 success in k attempts | One success matters (coding) |
| pass^k | All k attempts succeed | Consistency essential (customer-facing) |
Example: 75% per-trial success rate
- pass@3 ≈ 98% (likely to get at least one)
- pass^3 ≈ 42% (0.75³ all succeed)
Tracked Metrics
tracked_metrics:
- type: transcript
metrics: [n_turns, n_toolcalls, n_total_tokens]
- type: latency
metrics: [time_to_first_token, output_tokens_per_sec, time_to_last_token]
Attribution
Based on Demystifying evals for AI agents by Anthropic (January 2026).
Claude Code Agent Teams
Coordinate multiple Claude Code instances working together as a team with shared tasks, inter-agent messaging, and centralized management.
Quick Reference
See Agent Teams Guide for the complete reference including use case examples, architecture details, and troubleshooting.
Prerequisites
Agent teams are experimental and disabled by default. Enable them:
// settings.json
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
When to Use Agent Teams
Best for tasks where parallel exploration adds value:
| Use Case | Why Teams Help |
|---|---|
| Research and review | Multiple angles investigated simultaneously |
| New modules or features | Each teammate owns a separate piece |
| Debugging competing hypotheses | Test different theories in parallel |
| Cross-layer coordination | Frontend, backend, tests each owned by a teammate |
Don't use teams for: sequential tasks, same-file edits, or work with many dependencies. Use a single session or subagents instead.
Agent Teams vs Subagents
| Subagents | Agent Teams | |
|---|---|---|
| Context | Results return to caller | Fully independent |
| Communication | Report back only | Message each other directly |
| Coordination | Main agent manages all work | Shared task list, self-coordination |
| Best for | Focused tasks where only the result matters | Complex work requiring discussion |
| Token cost | Lower | Higher (each teammate is a separate instance) |
Use subagents for quick focused workers. Use agent teams when teammates need to share findings, challenge each other, and coordinate independently.
Starting a Team
Tell Claude to create a team in natural language:
I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.
Claude creates the team, spawns teammates, and coordinates work.
Display Modes
| Mode | Description | Requirements |
|---|---|---|
in-process | All teammates in main terminal, Shift+Down to cycle | Any terminal |
tmux / split panes | Each teammate in its own pane | tmux or iTerm2 |
auto (default) | Split panes if in tmux, otherwise in-process | — |
Override per-session:
claude --teammate-mode in-process
Or in settings:
{
"teammateMode": "in-process"
}
Controlling the Team
Specify teammates and models
Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.
Require plan approval
Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.
The lead reviews plans and approves or rejects with feedback.
Talk to teammates directly
- In-process: Shift+Down to cycle, Enter to view, Escape to interrupt
- Split panes: Click into a teammate's pane
Task management
Tasks have three states: pending, in progress, completed. Tasks can depend on other tasks. The lead assigns tasks or teammates self-claim. Press Ctrl+T to toggle the task list.
Shut down and clean up
Ask the researcher teammate to shut down
When done:
Clean up the team
Always use the lead to clean up. Shut down all teammates first.
Quality Gates with Hooks
TeammateIdle— runs when a teammate is about to go idle. Exit code 2 sends feedback and keeps them working.TaskCompleted— runs when a task is marked complete. Exit code 2 prevents completion and sends feedback.
Best Practices
- Give enough context — teammates don't inherit the lead's conversation history. Include details in spawn prompts.
- Start with 3-5 teammates — balances parallelism with coordination overhead.
- 5-6 tasks per teammate — keeps everyone productive.
- Avoid file conflicts — each teammate should own different files.
- Monitor and steer — check progress, redirect approaches that aren't working.
- Start with research/review — before trying parallel implementation.
Limitations
- No session resumption for in-process teammates (
/resume,/rewinddon't restore them) - Task status can lag — check and update manually if stuck
- One team per session
- No nested teams (teammates can't spawn their own teams)
- Lead is fixed for the team's lifetime
- All teammates start with the lead's permission mode
- Split panes require tmux or iTerm2 (not supported in VS Code terminal, Windows Terminal, or Ghostty)
Architecture
| Component | Role |
|---|---|
| Team lead | Main session that creates team, spawns teammates, coordinates |
| Teammates | Separate Claude Code instances working on assigned tasks |
| Task list | Shared work items that teammates claim and complete |
| Mailbox | Messaging system for inter-agent communication |
Storage locations:
- Team config:
~/.claude/teams/{team-name}/config.json - Task list:
~/.claude/tasks/{team-name}/
Attribution
Content adapted from Orchestrate teams of Claude Code sessions (Anthropic documentation).
Claude Code Hook Development
Create hooks that run shell commands on specific events to add guardrails, automations, and policy enforcement.
Quick Reference
You MUST read the reference files for detailed schemas and examples:
- Hook Events Reference - All events with input/output schemas
- Examples: Firewall - Block dangerous commands
- Examples: Quality Checks - Lint/format after edits
- Examples: Pre-Push Tests - Run tests before git push
Core Concepts
Hook Types
- Command hooks - Run bash scripts
- Prompt hooks - Query LLM for context-aware decisions
Exit Codes
| Code | Meaning | Behavior |
|---|---|---|
| 0 | Success | Action proceeds; stdout shown in verbose mode |
| 2 | Block | Action blocked; stderr fed to Claude |
| Other | Error | Non-blocking; stderr shown to user |
File Locations
- Settings:
.claude/settings.json - Scripts:
.claude/hooks/(mark executable)
Settings Structure
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": ".claude/hooks/my-script.sh",
"timeout": 60
}
]
}
]
}
}
Hook Events Summary
| Event | When | Can Block? |
|---|---|---|
| PreToolUse | Before tool executes | Yes (exit 2) |
| PostToolUse | After tool completes | Feedback only |
| PermissionRequest | User sees permission dialog | Yes |
| UserPromptSubmit | User submits prompt | Yes |
| Stop | Main agent finishes | Yes (continue) |
| SubagentStop | Subagent finishes | Yes (continue) |
| SessionStart | Session begins | Add context |
| SessionEnd | Session ends | Cleanup only |
| Notification | Notifications sent | No |
| PreCompact | Before compact | No |
Common Matchers
For PreToolUse/PostToolUse/PermissionRequest:
Bash- Shell commandsEdit,Write,Read- File operationsGlob,Grep- Search operationsTask- Subagent tasksmcp__<server>__<tool>- MCP tools- Regex patterns supported
Wildcard Permissions
Use wildcards for flexible matching patterns:
Bash(npm *)- Match any npm commandBash(*-h*)- Match commands containing-hBash(git:*)- Match any git subcommand
This reduces configuration overhead and avoids mismatched permissions blocking legitimate workflows.
Script Template
#!/usr/bin/env bash
set -euo pipefail
# Read JSON input
input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name // ""')
command=$(echo "$input" | jq -r '.tool_input.command // ""')
# Your validation logic here
if [[ "$command" =~ dangerous_pattern ]]; then
echo "Blocked: reason here" >&2
exit 2
fi
exit 0
Critical: Activating Hook Changes
Hooks are snapshotted at startup. After creating or modifying hooks:
⚠️ Changes won't take effect until you either:
- Restart Claude Code (exit and re-run
claude), OR- Run
/hooksto review and apply the updated configurationThis is a security feature - it prevents malicious hook modifications from affecting your current session.
Verifying Hooks Are Loaded
After restart, run /hooks to confirm your hook appears in the list. If it doesn't show up:
- Check JSON syntax in settings file
- Verify file is in correct location (
.claude/settings.json) - Look for
disableAllHooks: truein any settings file
Troubleshooting
Hook Not Triggering
- Did you restart? Hooks are snapshotted at startup - run
/hooksor restart Claude Code - Check
/hooksoutput - Your hook should be listed with correct matcher - Validate JSON - Run
cat .claude/settings.json | jq .to check syntax - Check matcher - Tool names are case-sensitive (
Bashnotbash)
Testing Hooks Safely
When creating hooks that block operations (like preventing push to main):
- Test on a safe branch first - Modify the hook to block a test branch
- Verify the block works - Attempt the blocked operation
- Update to production config - Change to block the actual target (e.g., main)
- Restart and verify - Run
/hooksto confirm the updated hook is loaded
Debugging
Use claude --debug to see hook execution details, or add logging to your hook:
echo "[DEBUG] Hook triggered: $cmd" >> /tmp/hook-debug.log
Attribution
Examples adapted from Steve Kinney's Claude Code Hook Examples.
Claude Code Memory and Rules
Configure Claude Code's memory system — CLAUDE.md files, modular rules, and auto memory — so instructions persist across sessions.
Quick Reference
You MUST read these references for detailed guidance:
- Memory Types - All memory locations, scopes, and precedence
- Rules Guide - Modular
.claude/rules/with path scoping - Auto Memory - Claude's self-managed memory system
- Examples - Real-world memory and rules configurations
Core Concepts
Claude Code has two kinds of persistent memory:
- CLAUDE.md files — Markdown you write with instructions, rules, and preferences
- Auto memory — Notes Claude writes for itself based on session learnings
Both load at session start. More specific instructions take precedence over broader ones.
Memory Hierarchy
| Scope | Location | Shared With | Priority |
|---|---|---|---|
| Organization | /Library/Application Support/ClaudeCode/CLAUDE.md | All org users | Lowest |
| User | ~/.claude/CLAUDE.md | All your projects | |
| User rules | ~/.claude/rules/*.md | All your projects | |
| Project (shared) | ./CLAUDE.md or ./.claude/CLAUDE.md | Team via git | |
| Project rules | ./.claude/rules/*.md | Team via git | |
| Project (local) | ./CLAUDE.local.md | Just you | Highest |
| Auto memory | ~/.claude/projects/<project>/memory/ | Just you | Per-project |
CLAUDE.md files in parent directories are loaded in full at launch. Files in child directories load on demand when Claude reads files there.
Choosing the Right Location
What do you need?
├── Instruction for ALL your projects?
│ ├── Shared with team? → Not possible at user level
│ └── Just you? → ~/.claude/CLAUDE.md or ~/.claude/rules/
├── Instruction for ONE project?
│ ├── Shared with team? → ./CLAUDE.md or .claude/rules/
│ └── Just you? → ./CLAUDE.local.md
├── Scoped to specific file types?
│ └── .claude/rules/<topic>.md with paths frontmatter
├── Session learnings that persist?
│ └── Auto memory (~/.claude/projects/<project>/memory/)
├── Automated enforcement (not guidance)?
│ └── Hook — use the claude-code-hook-development skill
└── Organization-wide policy?
└── Managed CLAUDE.md (deployed by IT)
Rules vs Hooks
Rules (CLAUDE.md / .claude/rules/) are instructions — natural language that Claude interprets with judgment.
Hooks (.claude/settings.json) are enforcement — shell commands that execute deterministically on events. Use the claude-code-hook-development skill for hooks.
| Need | Use |
|---|---|
| "Use 2-space tabs in this project" | Rule — .claude/rules/code-style.md or ./CLAUDE.md |
| "I prefer TypeScript over JavaScript" | Rule — ~/.claude/CLAUDE.md (user-level) |
| "API routes must validate input" | Rule — .claude/rules/api.md with paths: src/api/** |
| "Remember the DB uses port 5433" | Auto memory or ./CLAUDE.local.md |
| "All engineers must follow X policy" | Rule — Managed CLAUDE.md (org-level) |
| "Always run prettier after editing" | Hook — use claude-code-hook-development skill |
| "Never push to main" | Hook — use claude-code-hook-development skill |
| "Block rm -rf /" | Hook — use claude-code-hook-development skill |
Use rules for the 90% (guidance). Use hooks for the 10% (guardrails and automation).
CLAUDE.md Structure
Keep instructions specific and actionable:
# Project Instructions
## Build & Test
- Run tests: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`
## Code Style
- Use 2-space indentation
- Prefer named exports over default exports
- All API endpoints must validate input
## Architecture
- API routes in src/api/, business logic in src/services/
- Database queries only in src/db/ — never in route handlers
Tips:
- "Use 2-space indentation" beats "Format code properly"
- Format each instruction as a bullet point
- Group related instructions under descriptive headings
- Review periodically as the project evolves
Modular Rules (.claude/rules/)
For larger projects, split instructions into focused files instead of one large CLAUDE.md:
.claude/rules/
├── code-style.md # Formatting and naming
├── testing.md # Test conventions
├── security.md # Security requirements
└── frontend/
├── react.md # React patterns
└── styles.md # CSS conventions
All .md files are discovered recursively and loaded as project memory.
Path-Scoped Rules
Scope rules to specific files using paths frontmatter:
---
paths:
- "src/api/**/*.ts"
---
# API Rules
- All endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments
Rules without paths apply to all files.
Glob Patterns
| Pattern | Matches |
|---|---|
**/*.ts | All TypeScript files |
src/**/* | All files under src/ |
*.md | Markdown in project root |
src/**/*.{ts,tsx} | TypeScript and TSX files |
{src,lib}/**/*.ts | TypeScript in src/ or lib/ |
CLAUDE.md Imports
Import files with @path/to/file syntax:
See @README for project overview and @package.json for available npm commands.
# Git Workflow
- @docs/git-instructions.md
Relative paths resolve relative to the importing file. Max depth: 5 hops.
For personal instructions shared across worktrees:
# My Preferences
- @~/.claude/my-project-instructions.md
Bootstrapping
Run /init to generate an initial CLAUDE.md for your project. Then refine it.
Run /memory to open any memory file in your editor, toggle auto memory, or see what's loaded.
Attribution
Based on Claude Code Memory Documentation.
Claude Code Plugin Development
Create distributable plugins that bundle commands, agents, skills, hooks, MCP servers, and LSP servers.
Official docs: https://code.claude.com/docs/en/plugins-reference
Quick Reference
You MUST read these references for detailed schemas and examples:
- Plugin Manifest - Complete plugin.json schema
- Plugin Components - Commands, agents, skills, hooks, MCP, LSP
- CLI Commands - Install, uninstall, enable, disable, update
- Debugging - Common issues and troubleshooting
Plugin Structure
my-plugin/
├── .claude-plugin/
│ └── plugin.json # Required manifest
├── commands/ # Slash commands (.md files)
├── agents/ # Subagents (.md files)
├── skills/ # Skills (subdirs with SKILL.md)
├── hooks/
│ └── hooks.json # Hook configuration
├── .mcp.json # MCP server definitions
├── .lsp.json # LSP server configurations
└── scripts/ # Hook and utility scripts
Important: Components go at plugin root, NOT inside .claude-plugin/. Only plugin.json belongs in .claude-plugin/.
Marketplace Structure
A marketplace can contain multiple plugins. The marketplace root has its own .claude-plugin/marketplace.json:
my-marketplace/
├── .claude-plugin/
│ └── marketplace.json # Lists all plugins in this marketplace
├── plugins/
│ ├── plugin-a/
│ │ ├── .claude-plugin/
│ │ │ └── plugin.json
│ │ └── skills/
│ └── plugin-b/
│ ├── .claude-plugin/
│ │ └── plugin.json
│ └── commands/
marketplace.json
{
"name": "my-marketplace",
"owner": {
"name": "author-name"
},
"plugins": [
{
"name": "plugin-a",
"source": "./plugins/plugin-a",
"description": "First plugin description",
"version": "1.0.0"
},
{
"name": "plugin-b",
"source": "./plugins/plugin-b",
"description": "Second plugin description",
"version": "0.2.0"
}
]
}
Critical: When adding a new plugin to a marketplace:
- Add it to
marketplace.jsonor it won't be installable - If using release-please, add a jsonpath entry to the config for the new plugin's version
Minimal plugin.json
{
"name": "my-plugin",
"version": "1.0.0",
"description": "Brief plugin description"
}
Installation Scopes
| Scope | Location | Use case |
|---|---|---|
| user | ~/.claude/settings.json | Personal plugins (default) |
| project | .claude/settings.json | Team plugins via version control |
| local | .claude/settings.local.json | Project-specific, gitignored |
| managed | managed-settings.json | Read-only managed plugins |
Environment Variables
Use ${CLAUDE_PLUGIN_ROOT} for paths in hooks and MCP configs:
{
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
}
Plugin Components Summary
| Component | Location | Format |
|---|---|---|
| Commands | commands/ | Markdown with frontmatter |
| Agents | agents/ | Markdown with frontmatter |
| Skills | skills/*/SKILL.md | Directories with SKILL.md |
| Hooks | hooks/hooks.json | JSON configuration |
| MCP servers | .mcp.json | MCP server config |
| LSP servers | .lsp.json | Language server config |
CLI Quick Reference
# Install
claude plugin install <plugin>@<marketplace> --scope user
# Manage
claude plugin enable <plugin>
claude plugin disable <plugin>
claude plugin update <plugin>
claude plugin uninstall <plugin>
# Debug
claude --debug
Permissions
Problem: Using ! backticks to run plugin scripts fails with permission error:
Error: Bash command permission check failed for pattern
"!`${CLAUDE_PLUGIN_ROOT}/scripts/my-script.sh 2>&1 || true`":
This Bash command contains multiple operations.
Cause: ! backticks have their own permission model separate from allowed-tools. Complex commands or scripts fail.
Solution: Use the Bash tool instead of ! backticks for scripts:
---
allowed-tools: Bash(${CLAUDE_PLUGIN_ROOT}/scripts/my-script.sh:*)
---
Run the script:
```bash
${CLAUDE_PLUGIN_ROOT}/scripts/my-script.sh
```
Simple git commands still work with ! backticks: !git branch --show-current``
Common Issues
Plugin installed but commands don't appear?
The plugin may be disabled. Check ~/.claude/settings.json:
"enabledPlugins": {
"my-plugin@my-marketplace": false // ← Disabled!
}
Fix with: claude plugin enable my-plugin@my-marketplace then restart Claude Code.
Local changes not picked up?
Use claude plugin update <plugin> or do a full reinstall:
claude plugin marketplace remove my-marketplace
claude plugin marketplace add ./
claude plugin install my-plugin@my-marketplace
Important
After creating or modifying plugins, inform the user:
Plugin changes take effect immediately after installation. Use
claude --debugto verify plugin loading.
Checklist
Before finalizing a plugin:
-
plugin.jsonhas name, version, description - Components at plugin root (not in
.claude-plugin/) - All paths use
${CLAUDE_PLUGIN_ROOT}variable - Scripts are executable (
chmod +x) - If part of a marketplace, plugin is listed in
marketplace.json - If using release-please, add jsonpath for new plugin version in config
- Test with
claude --debugto verify loading
Slash Command Development
Create custom slash commands for Claude Code.
Quick Reference
You MUST read these references for detailed guidance:
- Official Documentation - Anthropic's slash command guide
Command Structure
Commands are Markdown files in specific locations:
| Scope | Location | Description suffix |
|---|---|---|
| Project | .claude/commands/ | (project) |
| Personal | ~/.claude/commands/ | (user) |
| Plugin | commands/ in plugin root | (plugin) |
Basic Command
---
description: Brief description of what this command does
---
Your prompt instructions here.
Frontmatter Options
---
allowed-tools: Bash(git:*), Read
argument-hint: [filename] [options]
description: What this command does
model: claude-3-5-haiku-20241022
disable-model-invocation: false
context: fork
---
| Field | Purpose |
|---|---|
allowed-tools | Tools the command can use |
argument-hint | Shows in autocomplete (e.g., [message]) |
description | Brief description (required for SlashCommand tool) |
model | Specific model to use |
disable-model-invocation | Prevent programmatic invocation |
context: fork | Run in isolated sub-agent context, preventing side effects on main agent state |
Arguments
All arguments:
Fix issue #$ARGUMENTS following our coding standards
Positional arguments:
Review PR #$1 with priority $2 and assign to $3
Dynamic Content
Bash execution (prefix with exclamation mark):
Current branch: EXCLAMATION`git branch --show-current`
Recent commits: EXCLAMATION`git log --oneline -5`
Replace EXCLAMATION with the exclamation mark character - workaround for bug #12762.
File references (prefix with at-sign):
Review the implementation in @src/utils/helpers.js
Namespacing
Subdirectories group related commands:
.claude/commands/frontend/test.md→/testshows(project:frontend).claude/commands/backend/test.md→/testshows(project:backend)
Checklist
- Description filled in frontmatter
-
argument-hintif command takes arguments -
allowed-toolsif using Bash or specific tools - Test with
/command-name --helpstyle invocation
Claude Code Statusline Development
Create custom status lines that display contextual information at the bottom of Claude Code.
Quick Reference
You MUST read the reference files for detailed schemas and examples:
- JSON Schema - Complete input structure documentation
- Example: Simple - Basic bash statusline
- Example: Git-Aware - Git branch and status
- Example: Context Usage - Context window percentage
- Example: Cost Tracking - Session costs and tokens
Configuration
Add to .claude/settings.json:
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh",
"padding": 0
}
}
How It Works
- Status line updates when conversation messages change
- Updates run at most every 300ms
- First line of stdout becomes the status line text
- ANSI color codes supported
- JSON context passed via stdin
JSON Input (Quick Reference)
| Field | Description |
|---|---|
model.display_name | Model name (e.g., "Opus") |
workspace.current_dir | Current working directory |
workspace.project_dir | Original project directory |
cost.total_cost_usd | Session cost in USD |
cost.total_lines_added | Lines added this session |
cost.total_lines_removed | Lines removed this session |
context_window.context_window_size | Max context tokens |
context_window.current_usage | Current token usage object |
See JSON Schema for complete structure.
Script Template
#!/bin/bash
input=$(cat)
# Extract values using jq
model=$(echo "$input" | jq -r '.model.display_name')
dir=$(echo "$input" | jq -r '.workspace.current_dir')
# Colors via tput
blue=$(tput setaf 4)
reset=$(tput sgr0)
echo "${blue}[$model]${reset} ${dir##*/}"
Make executable:
chmod +x ~/.claude/statusline.sh
Tips
- Keep output concise - single line only
- Use
tputfor portable ANSI colors - Test with mock JSON:
echo '{"model":{"display_name":"Test"}}' | ./statusline.sh - Cache expensive operations (git status) if needed
Important
After creating or modifying statuslines, inform the user:
No restart needed. Statusline changes take effect immediately - Claude Code reads settings fresh on each update.
Attribution
Based on Claude Code Status Line Configuration.
Editable HTML
The user edits text directly on the rendered page. Each edit is queued to a file. The agent watches the queue and applies the change to the real source, so build steps, templates and generated files stay in sync.
browser (press e, click, type)
│ POST /api/dev/live-edit {oldText, newText, binding, tag, parentText}
▼
scratch/live-edit/edits.jsonl ──watched by──▶ agent edits source files
│
scratch/live-edit/applied.jsonl ◀─────────────────┘ (badge shows "N waiting")
Why a queue and not a direct save: the rendered page is rarely the source. Text may come from a template, a script data array, a generator, or a component. The agent knows where it lives; the browser does not.
Pick a mode
| Situation | Mode |
|---|---|
| Static HTML file, visual, one-off page | Static: references/live_edit_server.py serves the page with the script injected |
| App with a dev server (Next.js, Vite, etc.) | App: add a dev-only API route and mount the overlay in dev builds |
| Standalone file the user keeps, no agent loop | Download: E to edit, Cmd+S downloads the edited HTML (see dwmkerr:slides conference mode) |
Default to Static unless the project already has a dev server.
Static mode
- Copy
references/live-edit.jsandreferences/live_edit_server.pyinto./scratch/live-edit/(gitignored). Never into the shipped page. - Start the server in the background:
python3 scratch/live-edit/live_edit_server.py path/to/page.html 8772 scratch/live-edit - Watch the queue with Monitor (or a background
tail), one notification per edit:f=scratch/live-edit/edits.jsonl; touch "$f"; tail -n 0 -F "$f" - Tell the user:
- Open
http://127.0.0.1:8772/page.html - Press
eto toggle edit mode, click any text, type - Click away,
EscorCmd+Ssends the edit - Badge shows how many edits are still waiting
- Reload to see the applied file
- Open
App mode
Copy the shape of the static server into the app:
GET /api/dev/live-editreturns{queued}(lines inedits.jsonlminus lines inapplied.jsonl)POST /api/dev/live-editappends{ts, ...body}toedits.jsonl- Both return 404 unless
NODE_ENV === "development": the route writes to the working tree - Mount
live-edit.js(or a component port of it) only in dev builds - Put the queue outside the app (
LIVE_EDIT_FILEenv var) so a containerised dev server and the host agent share it via a mount
Next.js example: ui/app/api/dev/live-edit/route.ts plus a <LiveEdit /> client component rendered when process.env.NODE_ENV === "development".
Applying edits
For each queued line:
- Read the full line from
edits.jsonl. Monitor notifications truncate long text. - Find
oldTextin the source. Check every place it lives: the shipped file, templates, generator scripts, data files. Fix all of them, or a rebuild reverts the edit. - If
bindingis set, the text comes from script data (e.g.data-text="cap.title"), not the markup. Search the data, not the HTML. - Escape for the target context. A straight
'inside a single-quoted JS string ends the string and breaks the page. Use curly quotes or escape it. - Append
{ts, result: "applied" | "not found" | "skipped", old, new}toapplied.jsonlso the badge count drops. - Report briefly. Flag typos or factual problems in the new copy and suggest a fix, but apply what the user wrote.
A small apply_edit.py <ts> <old> <new> helper that does steps 2, 4 and 5 across a fixed file list is worth writing when edits are frequent.
Make pages edit-friendly
- Text rendered from JS data: add
data-text="<key>"on the element so edits carry a binding. contenteditable="plaintext-only"stops pasted markup leaking into the queue.- The script listens in the capture phase and swallows clicks while editing, so the page's own handlers (steps, carousels, links) do not fire.
Gotchas
- User still sees old text after a structural change. Their open page holds what they typed. Ask them to reload.
- Edit not found. Rendered text differs from source: whitespace, entities (
&),’escapes, text split across elements. Try those forms before giving up. - Server stops with the session. It is a background task. Restart it in a new session.
- Security. Bind to
127.0.0.1only and never ship the script or route. Anything that can POST to it can edit your working tree via the agent.
References
references/live-edit.js: browser overlay (toggle, hover outline, plaintext editing, queue badge)references/live_edit_server.py: static server that injects the overlay and owns the queue
Learn and Improve
Analyze friction in the current session and propose targeted improvements to Claude Code configuration.
Workflow
Step 1: Understand the Problem
Ask the user what went wrong. If they've already described the issue, confirm your understanding.
Use AskUserQuestion to clarify:
- What happened? (e.g., "skill X asked for permission to run Y")
- What should have happened? (e.g., "it should just run without asking")
- How often does this occur? (one-off vs recurring)
Step 2: Gather Diagnostic Context
Investigate the current configuration by reading these files (read only what exists):
Settings (permissions, hooks, env):
~/.claude/settings.json(user-level).claude/settings.json(project-level, shared).claude/settings.local.json(project-level, local)
Memory (CLAUDE.md hierarchy):
~/.claude/CLAUDE.md(user-level)./CLAUDE.mdor./.claude/CLAUDE.md(project-level)./CLAUDE.local.md(local overrides)./.claude/rules/*.md(modular rules)
Auto memory:
~/.claude/projects/*/memory/MEMORY.mdfor the current project
Plugins & skills:
.claude-plugin/marketplace.json(if in a plugin repo)- Installed plugins:
~/.claude/plugins/cache/(list directories) - Installed marketplaces:
~/.claude/plugins/marketplaces/(list directories)
MCP servers:
.mcp.json(project)~/.claude.jsonor~/.claude/mcp.json(user)
Also review the conversation history for:
- Tool calls that were blocked or required permission prompts
- Skills that were invoked (or should have been but weren't)
- Agents that were spawned and their outcomes
- Error messages or unexpected behavior
Step 3: Identify the Root Cause
Common root causes and their fixes — see Improvement Types for full details.
| Symptom | Likely Cause | Fix Location |
|---|---|---|
| Permission prompt for a bash command | Missing allow rule | settings.json permissions.allow |
| Permission prompt for file read/write | Missing path pattern | settings.json permissions.allow |
| Skill not triggering | Bad description triggers | Skill SKILL.md frontmatter |
| Skill triggering on wrong tasks | Description too broad | Skill SKILL.md frontmatter |
| Repeated instructions ignored | Not in CLAUDE.md | CLAUDE.md (appropriate level) |
| Convention not followed per-filetype | No path-scoped rule | .claude/rules/ with paths frontmatter |
| Agent hitting permission walls | Agent lacks permissionMode | Agent frontmatter |
| MCP tool requiring permission | Missing MCP allow rule | settings.json permissions.allow |
| Hook not firing | Wrong matcher or event | settings.json hooks |
Step 4: Propose Improvements
In addition to fixing the reported issue, review the session for commands that were prompted for permission but are read-only and side-effect free (e.g., ls, gh pr view, git log). Suggest permanently allowing these — at user level for read-only commands, project level for write commands. See Improvement Types for examples.
For each proposed improvement, present:
- What to change — the specific file and content
- Why — how this fixes the reported issue
- Who benefits — see the table below to explain the reach of the improvement
- Risk — any trade-offs (e.g., "this auto-allows all npm commands")
Explain the reach of each improvement type to help the user decide:
| Improvement Type | Best For | Who Benefits |
|---|---|---|
| Skill fix (external plugin) | Fixing behavior everyone hits — opens a PR upstream | All users of the skill |
| Skill fix (personal skill) | Your custom workflows across all projects | You, all projects |
| Agent fix (external plugin) | Agents that hit permission walls or use wrong model | All users of the agent |
| User-level settings | Permission rules and preferences that apply everywhere | You, all projects |
| User-level CLAUDE.md | Coding conventions and instructions you always want | You, all projects |
| Project-shared settings | Team permissions and conventions | Your team, one project |
| Project-shared CLAUDE.md | Architecture notes, project-specific patterns | Your team, one project |
| Project-local settings | Personal overrides for one project | Just you, one project |
| Hook | Automating repetitive steps (formatting, tests, safety) — delegate to toolkit:claude-code-hook-development skill for non-trivial hooks | Depends on scope |
Project rules (.claude/rules/) | File-type-scoped conventions (API rules, test rules, frontend rules) — delegate to toolkit:claude-code-memory-and-rules skill for setup | Your team, one project |
User rules (~/.claude/rules/) | Personal conventions across all projects | Just you, all projects |
| Auto memory | Session learnings that don't belong in CLAUDE.md — delegate to toolkit:claude-code-memory-and-rules skill for setup | You, one project |
When an improvement could live at multiple scopes, present the options and explain the trade-off — broader scope means more reuse but also more risk if the change is wrong.
Step 5: Apply the Change
Apply the approved change to the correct file. After applying:
- Verify the file is valid JSON (for settings files) or valid markdown (for CLAUDE.md)
- Tell the user if a restart is needed (hooks require restart; skills/CLAUDE.md do not)
- If the fix is to an external skill or plugin, propose opening a PR instead
Step 6: Record the Verified Improvement (ESSENTIAL)
Every user-approved improvement is a verified data point. This skill is self-improving — each fix makes it better for the next person.
After the user confirms the improvement works, append a summary to Verified Improvements using this format:
### [Short title]
- **Friction**: [What went wrong]
- **Fix**: [What was changed and where]
- **Scope**: [Who benefits — e.g., "all users of toolkit:research"]
Keep entries concise (3 lines max). This log serves two purposes:
- Examples for future invocations — Claude reads these to pattern-match similar problems faster
- Evidence for skill evolution — patterns in the log reveal common friction that should be addressed in the skill itself or its references
If the log grows beyond ~30 entries, consolidate repeated patterns into the root cause table in Step 3 and remove the individual entries.
Important Constraints
- Never modify managed/enterprise settings — those are IT-controlled
- Always confirm before writing — show the exact change first
- Consider the reach — explain who benefits from each improvement type so the user can choose the right scope
- Preserve existing content — merge into existing settings, don't overwrite
- Settings format: permission rules use
Tool(pattern)syntax (e.g.,Bash(npm run *))
Quick Reference
For the full catalog of improvement types and examples, see:
- Improvement Types — all configuration levers with examples
- Diagnostic Checklist — systematic investigation steps
References
- agents.md outperforms skills in agent evals — Vercel research showing that CLAUDE.md-style agent instructions outperform skill-based routing in evaluations
Makefile Development
Create Makefiles following consistent conventions.
Template
default: help
.PHONY: help
help: # Show help for each of the Makefile recipes.
@grep -E '^[a-zA-Z0-9 -]+:.*#' Makefile | sort | while read -r l; do printf "\033[1;32m$$(echo $$l | cut -f 1 -d':')\033[00m:$$(echo $$l | cut -f 2- -d'#')\n"; done
.PHONY: init
init: # Initialise the development environment.
./scripts/init.sh
Conventions
| Element | Convention |
|---|---|
| Filename | Makefile (capitalised, no extension) |
| Default target | default: help as the first line |
.PHONY | Declare directly above each target |
| Help comments | Single # on the target line: target: # Description. |
| Target names | Lowercase, hyphen-separated (test-e2e, type-check) |
| Complex logic | Delegate to scripts (./scripts/build.sh) rather than inline |
Help Target
The self-documenting help target parses # comments and prints sorted, colour-coded output:
.PHONY: help
help: # Show help for each of the Makefile recipes.
@grep -E '^[a-zA-Z0-9 -]+:.*#' Makefile | sort | while read -r l; do printf "\033[1;32m$$(echo $$l | cut -f 1 -d':')\033[00m:$$(echo $$l | cut -f 2- -d'#')\n"; done
Every target must have a # Description. comment or it won't appear in help output.
Common Targets
| Target | Purpose |
|---|---|
help | Show available targets (always present) |
init or setup | Install dependencies, configure environment |
build | Compile or bundle artifacts |
dev | Start local development server |
test | Run test suite |
lint | Run linters and formatters |
Important
After creating or modifying Makefiles, remind the user:
Use tabs. Makefile recipes require literal tab characters for indentation, not spaces.
Release Please Development
Configure automated versioning, changelog generation, and releases using Google's release-please.
Quick Reference
- Single Package Pattern - Simple repos with one version
- Multi-Package Pattern - Monorepos with independent versions
- Configuration Options - All available settings
Overview
Release-please automates:
- Version bumping based on conventional commits
- CHANGELOG.md generation
- GitHub release creation
- Version updates in files (package.json, Chart.yaml, etc.)
Core Files
.github/
├── release-please-config.json # Package configuration
├── release-please-manifest.json # Current version tracking
└── workflows/
└── release.yaml # GitHub Actions workflow
When to Use Each Pattern
| Pattern | Use Case |
|---|---|
| Single Package | Libraries, CLIs, simple apps with one version |
| Multi-Package | Monorepos, services with independent release cycles |
Basic Setup
1. Create Config File
.github/release-please-config.json:
{
"release-type": "simple",
"packages": {
".": {
"changelog-path": "CHANGELOG.md"
}
}
}
2. Create Manifest
.github/release-please-manifest.json:
{
".": "0.0.1"
}
3. Add GitHub Workflow
.github/workflows/release.yaml:
name: Release
on:
push:
branches: [main]
permissions:
contents: write
pull-requests: write
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: googleapis/release-please-action@v4
with:
config-file: .github/release-please-config.json
manifest-file: .github/release-please-manifest.json
Release Types
| Type | Use Case | Versions |
|---|---|---|
simple | Generic projects | CHANGELOG only |
node | npm packages | package.json |
python | Python packages | setup.py, pyproject.toml |
go | Go modules | go.mod |
helm | Helm charts | Chart.yaml |
Updating Extra Files
Use extra-files to update versions in arbitrary files:
{
"packages": {
".": {
"extra-files": [
{
"type": "json",
"path": "manifest.json",
"jsonpath": "$.version"
}
]
}
}
}
Claude Code Plugin Marketplaces
For marketplaces with multiple plugins sharing a single version:
{
"release-type": "simple",
"packages": {
".": {
"changelog-path": "CHANGELOG.md",
"extra-files": [
{
"type": "json",
"path": ".claude-plugin/marketplace.json",
"jsonpath": "$.plugins[0].version"
},
{
"type": "json",
"path": ".claude-plugin/marketplace.json",
"jsonpath": "$.plugins[1].version"
}
]
}
}
}
Add a jsonpath entry for each plugin in the marketplace. When adding new plugins, update both:
.claude-plugin/marketplace.json- add the plugin entry.github/release-please-config.json- add jsonpath for the new plugin's version
Conventional Commits
Release-please uses commit prefixes to determine version bumps:
| Prefix | Version Bump | Example |
|---|---|---|
feat: | Minor (0.x.0) | New feature |
fix: | Patch (0.0.x) | Bug fix |
feat!: or BREAKING CHANGE | Major (x.0.0) | Breaking change |
docs:, chore:, etc. | None | No release |
How It Works
- Push commits to main with conventional commit messages
- Release-please creates/updates a release PR
- Merge the release PR to create a GitHub release
- Tags and changelog are automatically generated
See Also
- Single Package Example - Detailed single-package setup
- Multi-Package Example - Monorepo configuration
- Configuration Reference - All options explained
Research
Research technical solutions and gather evidence before implementation.
Research Process
1. Web Search First
Always start with web search to find:
- Official documentation
- GitHub repositories
- Blog posts and tutorials
- Protocol specifications (PDFs, RFCs)
2. Examine GitHub Repositories
GitHub raw content is often blocked. Clone repos to examine them:
cd /tmp
git clone https://github.com/owner/repo.git
cat /tmp/repo/README.md
Look for:
- README documentation
- Code examples
- Architecture patterns
- Dependencies and requirements
3. Handle Blocked Content
If a website cannot be loaded:
- Ask the user to paste the relevant content
- Request PDFs or specification documents
- Ask for screenshots if visual content is needed
Example prompt:
"I found a relevant resource at [URL] but cannot access it. Could you paste the key content or provide the PDF?"
4. Local Research Workspace
Store findings in ./scratch/research/ for review:
mkdir -p ./scratch/research
Save:
- Cloned repo summaries
- Code snippets
- Architecture diagrams
- Comparison notes
5. Evidence Requirements
Minimum 2-3 datapoints required before recommending a solution:
- GitHub repo with active maintenance
- Documentation or specification
- Real-world usage examples
- Community feedback (issues, discussions)
If insufficient evidence, ask for guidance:
"I found only one reference to this approach. Can you point me to additional resources or clarify the requirements?"
Output Format
Always back up findings with sources:
## Research: [Topic]
### Option 1: [Solution Name]
- **Source**: [URL or repo link]
- **Pros**: ...
- **Cons**: ...
- **Evidence**: [What confirms this works]
### Option 2: [Solution Name]
...
### Recommendation
Based on [N] sources, I recommend [Option] because...
### Sources
- [Title](URL)
- [Repo](GitHub URL) - cloned and examined
- [Spec](URL) - user provided
Example Usage
User: "Research options for terminal recording in an MCP server"
- Web search: "terminal recording library node typescript"
- Find GitHub repos -> clone to /tmp and examine
- Find asciinema, VHS, xterm.js
- Compare approaches in ./scratch/research/terminal-recording.md
- Present options with 2-3 sources each
Shell Script Development
Create shell scripts following consistent conventions.
Template
#!/usr/bin/env bash
set -e -o pipefail
# Colors
green='\033[0;32m'
red='\033[0;31m'
yellow='\033[1;33m'
blue='\033[0;34m'
nc='\033[0m'
# Script logic here
echo -e "${green}✔${nc} completed successfully"
Conventions
| Element | Convention |
|---|---|
| Shebang | #!/usr/bin/env bash |
| Safety | set -e -o pipefail |
| Local variables | Lowercase (model, dir, count) |
| Environment variables | Uppercase (PATH, HOME, USER) |
| Color variables | Lowercase (green, red, nc) |
| Status words | Lowercase (error, warning, note) |
Status Output Patterns
echo -e "${green}✔${nc} task completed" # success
echo -e "${red}error${nc}: something failed" # error
echo -e "${yellow}warning${nc}: something to note" # warning
echo -e "${blue}info${nc}: informational message" # info
Important
After creating or modifying shell scripts, inform the user:
Make executable. Run
chmod +x script.shbefore use.
Skill Development
Create effective Claude Code skills that are concise, discoverable, and well-structured.
Quick Reference
You MUST read these references for detailed guidance:
- Best Practices - Official Anthropic guidance
- Skill Examples - Patterns from real skills
- Skill Categories & Patterns - Three categories and five reusable patterns
- Testing Guide - Triggering, functional, and performance testing
- Troubleshooting - Common problems and fixes
- The Complete Guide to Building Skills for Claude - Comprehensive Anthropic guide (source PDF)
Before You Start
Define 2-3 concrete use cases before writing anything:
Use Case: [Name]
Trigger: User says "[phrase]" or "[phrase]"
Steps:
1. [First action]
2. [Second action]
Result: [What gets produced]
Then identify which category your skill falls into — this determines which techniques to use. See Skill Categories & Patterns.
Core Principles
- Concise is key - Only add context Claude doesn't already have
- Progressive disclosure - SKILL.md is the overview; details go in
references/ - Write in third person - "This skill processes..." not "I can help you..."
Skill Structure
skill-name/
├── SKILL.md # Main instructions (< 500 lines)
├── scripts/ # Optional: executable code (Python, Bash, etc.)
├── assets/ # Optional: templates, fonts, icons
└── references/ # Detailed docs (loaded on demand)
├── guide.md
└── examples/
YAML Frontmatter
---
name: my-skill-name
description: This skill should be used when the user asks to "do X", "create Y", or mentions Z. Be specific about triggers.
context: fork # Optional: run in isolated context (prevents side effects)
user-invocable: true # Optional: show in slash command menu (default: true)
---
Name rules:
- Lowercase letters, numbers, hyphens only
- Max 64 characters
- No reserved words (anthropic, claude)
Description rules:
- Max 1024 characters
- Third person ("This skill..." not "I can...")
- Include WHAT it does AND WHEN to use it
Optional fields:
context: fork- Run skill in isolated sub-agent context, preventing unintended side effects on main agent stateuser-invocable: false- Hide from slash command menu (skills are visible by default)allowed-tools- Restrict which tools the skill can use (e.g.,"Bash(python:*) Bash(npm:*) WebFetch"). Skills withreferences/directories should includeallowed-tools: Read, Grepto avoid permission prompts when accessing bundled files (claude-code#15757)license- e.g., MIT, Apache-2.0compatibility- Environment requirements (1-500 chars)metadata- Custom key-value pairs (author, version, mcp-server)
Writing Effective Descriptions
Structure: [What it does] + [When to use it] + [Key capabilities]
# Good - specific triggers
description: This skill should be used when the user asks to "create a hook", "add a hook", or mentions Claude Code hooks.
# Bad - vague
description: Helps with automation tasks.
Progressive Disclosure Pattern
Keep SKILL.md under 500 lines. Link to details:
# My Skill
## Quick start
[Essential info here]
## Advanced features
See [detailed-guide.md](./references/detailed-guide.md)
## API reference
See [api-reference.md](./references/api-reference.md)
Claude loads reference files only when needed.
Testing Your Skill
Validate across three dimensions before sharing:
- Triggering - Does it load when it should? Not load when it shouldn't?
- Functional - Does it produce correct outputs and handle errors?
- Performance - Is it actually better than no skill? (fewer messages, fewer errors, less tokens)
See Testing Guide for test examples and success criteria.
Troubleshooting
Common issues and fixes:
| Symptom | Fix |
|---|---|
| Doesn't trigger | Add specific trigger phrases to description |
| Triggers too often | Add negative triggers, narrow scope |
| Instructions ignored | Make instructions concise, use explicit headers |
| Slow responses | Move content to references/, reduce SKILL.md size |
See Troubleshooting for detailed solutions.
Important
After creating or modifying skills, inform the user:
No restart needed. Skill changes take effect immediately - skills are hot-reloaded.
Checklist
Before finalizing a skill:
- 2-3 use cases defined with triggers, steps, and results
- Category identified (document creation, workflow automation, MCP enhancement)
- Description includes triggers ("when user asks to...")
- SKILL.md under 500 lines
- Complex content moved to
references/ - Third person throughout
- No time-sensitive information
- Consistent terminology
- Triggering tests pass (obvious + paraphrased requests)
- Doesn't trigger on unrelated topics
Solve Problem
A methodical approach to solving a problem. The goal is to resist the instinct to jump at the first plausible-sounding fix. That instinct feels fast but causes wrong fixes and wasted iteration. Slow down, gather evidence, then propose.
Work through the moves in order. Do not skip ahead. The moves are domain-neutral — they apply to a code bug, a broken appliance, a drop in sales, or a failing process. Examples below span more than code on purpose.
1. Understand intent
Restate the problem in your own words so the user can correct you. Establish what they expect, what is actually happening, and what "solved" looks like.
Clarify with the user only if the problem is genuinely ambiguous. Do not interrogate a clear problem — echo your understanding and move on.
2. See the problem — first-hand, repeatably
Confirm the problem is real before hunting for causes. Observe it directly, under conditions you can return to — don't diagnose from a second-hand report, ticket, summary, or a single stale log line. You want a way to make the problem happen (or to check whether it's happening) again on demand, because the same handle confirms the cause now and verifies the fix later (move 6).
Prefer first-hand evidence over artifacts: reproduce the bug by running it; watch the real checkout instead of reading the sales dashboard; measure the actual part instead of trusting the spec.
If you cannot see it, or it turns out not to be a real problem (wrong expectation, already fixed, environment issue), say so and stop. Do not invent a fix for a problem you have not observed.
3. Hypothesize
Once the problem is confirmed, investigate how the thing is supposed to work and where reality diverges. From that investigation, list at least two candidate causes.
A single hypothesis is banned — it leads to tunnel vision. Force yourself to name alternatives, even ones you think are unlikely.
4. Gather evidence
For each hypothesis, run the cheapest check that discriminates between causes — ideally one that could prove the hypothesis wrong, not merely one consistent with it. Evidence that merely fits a hypothesis (correlation) is weak: it often fits competing hypotheses too. ("It works in a clean browser" is consistent with both "stale state" and "a race" — it rules out neither.) Seek the check that separates them.
Confirm or eliminate each with first-hand evidence. Assumptions and memory are not evidence. If the cheap checks (logs, reports) don't isolate it, escalate to direct observation with more instrumentation rather than guessing harder. Keep eliminating until one cause is supported by evidence that survived an attempt to falsify it.
5. Propose
Propose a solution grounded in the evidence. State your confidence level and what is still uncertain. If you cannot reach certainty, say so, and say what would resolve it.
By default, stop here. Propose — do not implement — unless the user asks you to apply the fix.
6. Verify the resolution
Once a fix is applied, re-observe the original symptom under the same conditions that showed it (move 2's handle). The problem is not solved until the thing that was wrong is now demonstrably right — observed, not assumed.
This is not the same as move 4. Move 4 verifies the diagnosis ("is this the cause?"); move 6 verifies the resolution ("did my action make the symptom actually go away?"). They are different questions: a doctor's test can confirm the cause, yet the prescribed treatment may still not cure the patient — you check the patient got better. You can also mis-apply a correct diagnosis (incomplete fix, wrong change, a side effect), and only re-observing the symptom catches that.
If the symptom persists, the fix — or the diagnosis behind it — was wrong. Do not patch again from the same reasoning; return to move 2 with more instrumentation.
Re-observe the exact symptom the user reported — not a proxy. A related error clearing or a secondary signal going green is not the symptom going away. One cause cleared is not the symptom cleared; if it persists, another cause remains — return to observing.
Anti-rush rules
- Read the definition before the surroundings. When something misbehaves, the artifact that defines it — its config, frontmatter, schema, or source — is usually the cheapest, most decisive evidence. Read it before theorizing from menus, labels, dashboards, or error text, which are downstream surfaces.
- No proposal before the problem is seen first-hand and a cause is evidenced.
- At least two hypotheses before testing any.
- Evidence — not memory or assumption — confirms a cause. Prefer a check that could falsify the hypothesis over one that merely fits it.
- Recurrence means you were wrong. If the problem comes back after a fix, the cause (or the fix) was wrong — go back to observing it directly with more instrumentation; do not propose another fix from the same reasoning.
- The words in the report are hypotheses, not evidence. "It's a timeout," "it's a race," "it only happens without X" — these are the reporter's model of the bug, often wrong even when plausible. Test them like any other hypothesis; never adopt them as the starting fact.
- Surface signals are hypotheses too. A menu label, status badge, error string, or dashboard number is the system's rendering of its state, not the state itself. Confirm against the underlying definition/source, not the surface.
- A constant is a clue. An exact, repeating number (the same 15s three times) is a deadline or an interval, not how long the work took — work varies, limits don't. When cheap checks can't separate causes, change the conditions to make a hidden variable visible rather than staring harder at the same setup.
- Not solved until re-observed gone (move 6), not just "a change was made".
- State confidence. Flag uncertainty. Never fake certainty.
Show your working
When presenting the proposal, always show the full trace so the user can debug your reasoning. Use this structure:
## Problem
<the problem, restated>
## How I confirmed it
<what you reproduced or observed — the evidence it is real>
## Hypotheses considered
1. <hypothesis> — <eliminated / confirmed>
2. <hypothesis> — <eliminated / confirmed>
...
## Evidence
<per hypothesis: what you checked and what it showed>
## Root cause
<the cause supported by evidence>
## Proposed solution
<the fix, grounded in the evidence>
## Confidence
<high / medium / low> — <what is still uncertain, if anything>
## Verification (after applying)
<the original symptom re-checked under the same conditions — gone, observed>
Worked examples
For full end-to-end traces of the method applied to hard, real problems, see
references/. Read one when you are stuck and want a model
to follow. Currently:
- SSE keepalive misdiagnosed as a timeout — a bug reported as a "query timeout" that was nothing of the kind. Shows falsifying several plausible causes, escalating instrumentation (throttling a consumer to expose a hidden keepalive), reading dependency source as evidence, and verifying the fix end-to-end.
Commands 5
Agent History
Show which agents were spawned during the current Claude Code session.
CRITICAL: Do NOT read the session file directly - it's too large. Use the Bash tool to run grepsession.sh which filters efficiently.
Instructions
-
Use Bash to run grepsession.sh
${CLAUDE_PLUGIN_ROOT}/scripts/grepsession.sh '"name":"Task"'This outputs matching lines with line numbers from the current session.
-
Parse the output
Each line is JSONL with this structure:
{ "type": "assistant", "timestamp": "2025-01-05T09:23:15.123Z", "message": { "content": [ { "type": "tool_use", "name": "Task", "input": { "description": "Research Claude plugins", "subagent_type": "dwmkerr:researcher", "prompt": "..." } } ] } }Extract:
- Line number: from grep prefix (e.g.,
1247:{...}) - Time: from
.timestamp - Agent: from
.message.content[].input.subagent_type - Description: from
.message.content[].input.description
- Line number: from grep prefix (e.g.,
-
If you need more context
${CLAUDE_PLUGIN_ROOT}/scripts/grepsession.sh '"name":"Task"' -C 5Or use Read tool with offset/limit on the session file.
-
To find what triggered each agent
Look for the most recent user message before each agent. User messages have this structure:
{ "type": "user", "timestamp": "2025-01-05T09:23:00.000Z", "message": { "content": "are there github repos showing how to check skills?" } } -
Display results
Format timestamps as relative time (e.g., "3m ago", "1h ago", "2d ago").
## Agents Spawned This Session | Line | When | Agent | Task | Triggered By | |------|----------|----------------|------------------------------|----------------------------| | 1247 | 2h ago | researcher | Research Claude plugins | "are there github repos..." | 1389 | 1h ago | researcher | Clone and examine repo | "are there github repos..." **Total**: 2 agents spawned
Notes
- Uses the same
grepsession.shscript from the skills plugin - Users can run
grepsession.shdirectly and pipe tojq - Line numbers let you inspect specific parts of the session log
GitHub Pull Request
Open or create a pull request for the current branch.
Context
- Current branch: !
git branch --show-current - Recent commits on this branch: !
git log main..HEAD --oneline 2>/dev/null || git log origin/main..HEAD --oneline 2>/dev/null || echo "Unable to determine commits"
Instructions
Step 1: Check if PR exists (fast path)
Run the ghpr script:
${CLAUDE_PLUGIN_ROOT}/scripts/ghpr.sh
- If it shows "✔ opened: ": The PR was opened in the browser. Confirm this to the user and stop.
- If it shows "NO_PR": Continue to Step 2.
Step 2: Check for relevant skills
Before creating a PR, check available skills for any that might provide PR guidance:
- Look for
<project>-developmentskills (e.g.,ark-development,typescript-development) if this is engineering work - Look for
pull-requestorpr-guidanceskills - Review the conversation history for context about what was implemented
If relevant skills exist, invoke them to get project-specific PR conventions.
Step 3: Create PR (if none exists)
a. Analyze the branch name and commits to determine the type:
feat/branch or feature commits →feat:fix/branch or bugfix commits →fix:chore/branch or maintenance commits →chore:docs/branch →docs:refactor/branch →refactor:
b. Draft a PR title following conventional commit format (e.g., feat: add ghpr command)
c. Draft a PR body using this format:
## Summary
- Brief description of changes
d. Present the suggested title and body to the user using AskUserQuestion:
- Show the proposed title
- Show the proposed body
- Ask for confirmation or edits
e. If confirmed, create the PR:
gh pr create --title "..." --body "..."
f. Report the PR URL to the user.
Skill History
Show which skills were invoked during the current Claude Code session.
CRITICAL: Do NOT read the session file directly - it's too large. Use the Bash tool to run grepsession.sh which filters efficiently.
Instructions
-
Use Bash to run grepsession.sh
${CLAUDE_PLUGIN_ROOT}/scripts/grepsession.sh '"name":"Skill"'This outputs matching lines with line numbers from the current session.
-
Parse the output
Each line is JSONL with this structure:
{ "type": "assistant", "timestamp": "2025-01-05T09:23:15.123Z", "message": { "content": [ { "type": "tool_use", "name": "Skill", "input": { "skill": "typescript-development", "args": "" } } ] } }Extract:
- Line number: from grep prefix (e.g.,
1247:{...}) - Time: from
.timestamp - Skill: from
.message.content[].input.skill
- Line number: from grep prefix (e.g.,
-
If you need more context
${CLAUDE_PLUGIN_ROOT}/scripts/grepsession.sh '"name":"Skill"' -C 5Or use Read tool with offset/limit on the session file.
-
To find what triggered each skill
Look for the most recent user message before each skill. User messages have this structure:
{ "type": "user", "timestamp": "2025-01-05T09:23:00.000Z", "message": { "content": "fix the type errors in the project" } } -
Display results
Format timestamps as relative time (e.g., "3m ago", "1h ago", "2d ago").
## Skills Invoked This Session | Line | When | Skill | Triggered By | |------|----------|--------------------|--------------------------------| | 1247 | 2h ago | typescript-dev | "fix the type errors in..." | | 1389 | 45m ago | technical-writing | "improve the readme..." | **Total**: 2 skills invoked
Notes
- Users can run
grepsession.shdirectly and pipe tojq - Line numbers let you inspect specific parts of the session log
- Use
-C Nfor context,-A Nfor after,-B Nfor before
Very Fast
Handle this request quickly:
$ARGUMENTS
Instructions
- If the request is empty, ask what to run and stop.
- Do the work directly with the fewest tool calls needed. Do not spawn subagents unless the request asks for them.
- Keep the answer short. Lead with the result.
- If the request needs deep reasoning or design work, say so in one line and suggest re-running it without
/toolkit:vfast.
Very Very Fast
Handle this request quickly and cheaply:
$ARGUMENTS
Instructions
- If the request is empty, ask what to run and stop.
- Do the work directly with the fewest tool calls needed. Do not spawn subagents unless the request asks for them.
- Keep the answer short. Lead with the result.
- If the request needs deep reasoning, large refactors, or design work, say so in one line and suggest
/toolkit:vfastor no command.
Agents 1
You are a technical researcher specializing in finding and evaluating solutions for software engineering problems.
Your Approach
-
Start with web search - Always search first to find documentation, GitHub repos, blog posts, and specifications.
-
Clone GitHub repos - GitHub raw content is often blocked. Clone repos to
/tmpto examine them:git clone https://github.com/owner/repo.git /tmp/repo cat /tmp/repo/README.md -
Ask for blocked content - If you cannot load a website, ask the user:
"I found a relevant resource at [URL] but cannot access it. Could you paste the key content?"
-
Request specifications - If you find PDFs, RFCs, or protocol specs you cannot access, ask the user to provide them.
-
Store findings locally - Save research to
./scratch/research/for review:mkdir -p ./scratch/research
Evidence Requirements
You must find 2-3 datapoints before recommending a solution:
- Active GitHub repo with recent commits
- Official documentation or specification
- Real-world usage examples
- Community feedback (issues, discussions, blog posts)
If you cannot find sufficient evidence, ask for guidance:
"I found only one reference to this approach. Can you point me to additional resources or clarify requirements?"
Output Format
Always structure findings with sources:
## Research: [Topic]
### Option 1: [Solution Name]
- **Source**: [URL]
- **Pros**: ...
- **Cons**: ...
- **Evidence**: ...
### Option 2: [Solution Name]
...
### Recommendation
Based on [N] sources, I recommend [Option] because...
### Sources
- [Title](URL)
- [Repo](GitHub URL) - cloned and examined
What You Do NOT Do
- Do not guess or make up solutions without evidence
- Do not recommend based on a single source
- Do not proceed without asking if you hit blockers
- Do not skip the web search step
Sponsors
Details
- Marketplace
- dwmkerr/claude-toolkit
- Source
- plugins/toolkit
- Category
- Community