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-toolkit

Run it inside Claude Code after adding the marketplace with /plugin marketplace add dwmkerr/claude-toolkit.

Contents

Discovered from source

Skills 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

ColorAgent TypePurpose
PurpleExploreCodebase exploration, documentation
BluePlanAnalysis, planning, architecture
GreenCreateTesting, creation, validation
OrangeDebugDebugging, refactoring
YellowCleanOptimization, cleanup
RedReflectSecurity, 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:

YAML Templates:

Annotated Examples:

Core Definitions

TermDefinition
TaskSingle test with defined inputs and success criteria
TrialOne attempt at a task (run multiple for consistency)
GraderLogic that scores agent performance; tasks can have multiple
TranscriptComplete record of a trial (outputs, tool calls, reasoning)
OutcomeFinal state in environment (not just what agent said)
Evaluation harnessInfrastructure that runs evals end-to-end
Agent harnessSystem enabling model to act as agent (scaffold)
Evaluation suiteCollection of tasks measuring specific capabilities

Grader Types (Quick Reference)

TypeMethodsBest For
Code-basedString match, unit tests, static analysis, state checksFast, cheap, objective verification
Model-basedRubric scoring, assertions, pairwise comparisonNuanced, open-ended tasks
HumanSME review, A/B testing, spot-check samplingGold standard calibration

See Grader Types for detailed comparison.

Capability vs Regression Evals

TypeQuestionTarget 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

MetricMeasuresUse When
pass@kAt least 1 success in k attemptsOne success matters (coding)
pass^kAll k attempts succeedConsistency 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 CaseWhy Teams Help
Research and reviewMultiple angles investigated simultaneously
New modules or featuresEach teammate owns a separate piece
Debugging competing hypothesesTest different theories in parallel
Cross-layer coordinationFrontend, 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

SubagentsAgent Teams
ContextResults return to callerFully independent
CommunicationReport back onlyMessage each other directly
CoordinationMain agent manages all workShared task list, self-coordination
Best forFocused tasks where only the result mattersComplex work requiring discussion
Token costLowerHigher (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

ModeDescriptionRequirements
in-processAll teammates in main terminal, Shift+Down to cycleAny terminal
tmux / split panesEach teammate in its own panetmux 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

  1. Give enough context — teammates don't inherit the lead's conversation history. Include details in spawn prompts.
  2. Start with 3-5 teammates — balances parallelism with coordination overhead.
  3. 5-6 tasks per teammate — keeps everyone productive.
  4. Avoid file conflicts — each teammate should own different files.
  5. Monitor and steer — check progress, redirect approaches that aren't working.
  6. Start with research/review — before trying parallel implementation.

Limitations

  • No session resumption for in-process teammates (/resume, /rewind don'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

ComponentRole
Team leadMain session that creates team, spawns teammates, coordinates
TeammatesSeparate Claude Code instances working on assigned tasks
Task listShared work items that teammates claim and complete
MailboxMessaging 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:

Core Concepts

Hook Types

  1. Command hooks - Run bash scripts
  2. Prompt hooks - Query LLM for context-aware decisions

Exit Codes

CodeMeaningBehavior
0SuccessAction proceeds; stdout shown in verbose mode
2BlockAction blocked; stderr fed to Claude
OtherErrorNon-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

EventWhenCan Block?
PreToolUseBefore tool executesYes (exit 2)
PostToolUseAfter tool completesFeedback only
PermissionRequestUser sees permission dialogYes
UserPromptSubmitUser submits promptYes
StopMain agent finishesYes (continue)
SubagentStopSubagent finishesYes (continue)
SessionStartSession beginsAdd context
SessionEndSession endsCleanup only
NotificationNotifications sentNo
PreCompactBefore compactNo

Common Matchers

For PreToolUse/PostToolUse/PermissionRequest:

  • Bash - Shell commands
  • Edit, Write, Read - File operations
  • Glob, Grep - Search operations
  • Task - Subagent tasks
  • mcp__<server>__<tool> - MCP tools
  • Regex patterns supported

Wildcard Permissions

Use wildcards for flexible matching patterns:

  • Bash(npm *) - Match any npm command
  • Bash(*-h*) - Match commands containing -h
  • Bash(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:

  1. Restart Claude Code (exit and re-run claude), OR
  2. Run /hooks to review and apply the updated configuration

This 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: true in any settings file

Troubleshooting

Hook Not Triggering

  1. Did you restart? Hooks are snapshotted at startup - run /hooks or restart Claude Code
  2. Check /hooks output - Your hook should be listed with correct matcher
  3. Validate JSON - Run cat .claude/settings.json | jq . to check syntax
  4. Check matcher - Tool names are case-sensitive (Bash not bash)

Testing Hooks Safely

When creating hooks that block operations (like preventing push to main):

  1. Test on a safe branch first - Modify the hook to block a test branch
  2. Verify the block works - Attempt the blocked operation
  3. Update to production config - Change to block the actual target (e.g., main)
  4. Restart and verify - Run /hooks to 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:

  1. CLAUDE.md files — Markdown you write with instructions, rules, and preferences
  2. 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

ScopeLocationShared WithPriority
Organization/Library/Application Support/ClaudeCode/CLAUDE.mdAll org usersLowest
User~/.claude/CLAUDE.mdAll your projects
User rules~/.claude/rules/*.mdAll your projects
Project (shared)./CLAUDE.md or ./.claude/CLAUDE.mdTeam via git
Project rules./.claude/rules/*.mdTeam via git
Project (local)./CLAUDE.local.mdJust youHighest
Auto memory~/.claude/projects/<project>/memory/Just youPer-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.

NeedUse
"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

PatternMatches
**/*.tsAll TypeScript files
src/**/*All files under src/
*.mdMarkdown in project root
src/**/*.{ts,tsx}TypeScript and TSX files
{src,lib}/**/*.tsTypeScript 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 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:

  1. Add it to marketplace.json or it won't be installable
  2. 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

ScopeLocationUse case
user~/.claude/settings.jsonPersonal plugins (default)
project.claude/settings.jsonTeam plugins via version control
local.claude/settings.local.jsonProject-specific, gitignored
managedmanaged-settings.jsonRead-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

ComponentLocationFormat
Commandscommands/Markdown with frontmatter
Agentsagents/Markdown with frontmatter
Skillsskills/*/SKILL.mdDirectories with SKILL.md
Hookshooks/hooks.jsonJSON configuration
MCP servers.mcp.jsonMCP server config
LSP servers.lsp.jsonLanguage 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 --debug to verify plugin loading.

Checklist

Before finalizing a plugin:

  • plugin.json has 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 --debug to verify loading

Slash Command Development

Create custom slash commands for Claude Code.

Quick Reference

You MUST read these references for detailed guidance:

Command Structure

Commands are Markdown files in specific locations:

ScopeLocationDescription suffix
Project.claude/commands/(project)
Personal~/.claude/commands/(user)
Plugincommands/ 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
---
FieldPurpose
allowed-toolsTools the command can use
argument-hintShows in autocomplete (e.g., [message])
descriptionBrief description (required for SlashCommand tool)
modelSpecific model to use
disable-model-invocationPrevent programmatic invocation
context: forkRun 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 → /test shows (project:frontend)
  • .claude/commands/backend/test.md → /test shows (project:backend)

Checklist

  • Description filled in frontmatter
  • argument-hint if command takes arguments
  • allowed-tools if using Bash or specific tools
  • Test with /command-name --help style 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:

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)

FieldDescription
model.display_nameModel name (e.g., "Opus")
workspace.current_dirCurrent working directory
workspace.project_dirOriginal project directory
cost.total_cost_usdSession cost in USD
cost.total_lines_addedLines added this session
cost.total_lines_removedLines removed this session
context_window.context_window_sizeMax context tokens
context_window.current_usageCurrent 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 tput for 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

SituationMode
Static HTML file, visual, one-off pageStatic: 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 loopDownload: 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

  1. Copy references/live-edit.js and references/live_edit_server.py into ./scratch/live-edit/ (gitignored). Never into the shipped page.
  2. Start the server in the background:
    python3 scratch/live-edit/live_edit_server.py path/to/page.html 8772 scratch/live-edit
    
  3. 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"
    
  4. Tell the user:
    • Open http://127.0.0.1:8772/page.html
    • Press e to toggle edit mode, click any text, type
    • Click away, Esc or Cmd+S sends the edit
    • Badge shows how many edits are still waiting
    • Reload to see the applied file

App mode

Copy the shape of the static server into the app:

  • GET /api/dev/live-edit returns {queued} (lines in edits.jsonl minus lines in applied.jsonl)
  • POST /api/dev/live-edit appends {ts, ...body} to edits.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_FILE env 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:

  1. Read the full line from edits.jsonl. Monitor notifications truncate long text.
  2. Find oldText in 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.
  3. If binding is set, the text comes from script data (e.g. data-text="cap.title"), not the markup. Search the data, not the HTML.
  4. 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.
  5. Append {ts, result: "applied" | "not found" | "skipped", old, new} to applied.jsonl so the badge count drops.
  6. 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 (&amp;), ’ 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.1 only 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.md or ./.claude/CLAUDE.md (project-level)
  • ./CLAUDE.local.md (local overrides)
  • ./.claude/rules/*.md (modular rules)

Auto memory:

  • ~/.claude/projects/*/memory/MEMORY.md for 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.json or ~/.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.

SymptomLikely CauseFix Location
Permission prompt for a bash commandMissing allow rulesettings.json permissions.allow
Permission prompt for file read/writeMissing path patternsettings.json permissions.allow
Skill not triggeringBad description triggersSkill SKILL.md frontmatter
Skill triggering on wrong tasksDescription too broadSkill SKILL.md frontmatter
Repeated instructions ignoredNot in CLAUDE.mdCLAUDE.md (appropriate level)
Convention not followed per-filetypeNo path-scoped rule.claude/rules/ with paths frontmatter
Agent hitting permission wallsAgent lacks permissionModeAgent frontmatter
MCP tool requiring permissionMissing MCP allow rulesettings.json permissions.allow
Hook not firingWrong matcher or eventsettings.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:

  1. What to change — the specific file and content
  2. Why — how this fixes the reported issue
  3. Who benefits — see the table below to explain the reach of the improvement
  4. 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 TypeBest ForWho Benefits
Skill fix (external plugin)Fixing behavior everyone hits — opens a PR upstreamAll users of the skill
Skill fix (personal skill)Your custom workflows across all projectsYou, all projects
Agent fix (external plugin)Agents that hit permission walls or use wrong modelAll users of the agent
User-level settingsPermission rules and preferences that apply everywhereYou, all projects
User-level CLAUDE.mdCoding conventions and instructions you always wantYou, all projects
Project-shared settingsTeam permissions and conventionsYour team, one project
Project-shared CLAUDE.mdArchitecture notes, project-specific patternsYour team, one project
Project-local settingsPersonal overrides for one projectJust you, one project
HookAutomating repetitive steps (formatting, tests, safety) — delegate to toolkit:claude-code-hook-development skill for non-trivial hooksDepends 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 setupYour team, one project
User rules (~/.claude/rules/)Personal conventions across all projectsJust you, all projects
Auto memorySession learnings that don't belong in CLAUDE.md — delegate to toolkit:claude-code-memory-and-rules skill for setupYou, 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:

  1. Verify the file is valid JSON (for settings files) or valid markdown (for CLAUDE.md)
  2. Tell the user if a restart is needed (hooks require restart; skills/CLAUDE.md do not)
  3. 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:

  1. Examples for future invocations — Claude reads these to pattern-match similar problems faster
  2. 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:

References

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

ElementConvention
FilenameMakefile (capitalised, no extension)
Default targetdefault: help as the first line
.PHONYDeclare directly above each target
Help commentsSingle # on the target line: target: # Description.
Target namesLowercase, hyphen-separated (test-e2e, type-check)
Complex logicDelegate 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

TargetPurpose
helpShow available targets (always present)
init or setupInstall dependencies, configure environment
buildCompile or bundle artifacts
devStart local development server
testRun test suite
lintRun 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

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

PatternUse Case
Single PackageLibraries, CLIs, simple apps with one version
Multi-PackageMonorepos, 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

TypeUse CaseVersions
simpleGeneric projectsCHANGELOG only
nodenpm packagespackage.json
pythonPython packagessetup.py, pyproject.toml
goGo modulesgo.mod
helmHelm chartsChart.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:

  1. .claude-plugin/marketplace.json - add the plugin entry
  2. .github/release-please-config.json - add jsonpath for the new plugin's version

Conventional Commits

Release-please uses commit prefixes to determine version bumps:

PrefixVersion BumpExample
feat:Minor (0.x.0)New feature
fix:Patch (0.0.x)Bug fix
feat!: or BREAKING CHANGEMajor (x.0.0)Breaking change
docs:, chore:, etc.NoneNo release

How It Works

  1. Push commits to main with conventional commit messages
  2. Release-please creates/updates a release PR
  3. Merge the release PR to create a GitHub release
  4. Tags and changelog are automatically generated

See Also

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"

  1. Web search: "terminal recording library node typescript"
  2. Find GitHub repos -> clone to /tmp and examine
  3. Find asciinema, VHS, xterm.js
  4. Compare approaches in ./scratch/research/terminal-recording.md
  5. 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

ElementConvention
Shebang#!/usr/bin/env bash
Safetyset -e -o pipefail
Local variablesLowercase (model, dir, count)
Environment variablesUppercase (PATH, HOME, USER)
Color variablesLowercase (green, red, nc)
Status wordsLowercase (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.sh before 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:

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

  1. Concise is key - Only add context Claude doesn't already have
  2. Progressive disclosure - SKILL.md is the overview; details go in references/
  3. 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 state
  • user-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 with references/ directories should include allowed-tools: Read, Grep to avoid permission prompts when accessing bundled files (claude-code#15757)
  • license - e.g., MIT, Apache-2.0
  • compatibility - 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:

  1. Triggering - Does it load when it should? Not load when it shouldn't?
  2. Functional - Does it produce correct outputs and handle errors?
  3. 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:

SymptomFix
Doesn't triggerAdd specific trigger phrases to description
Triggers too oftenAdd negative triggers, narrow scope
Instructions ignoredMake instructions concise, use explicit headers
Slow responsesMove 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

  1. 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.

  2. 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
  3. If you need more context

    ${CLAUDE_PLUGIN_ROOT}/scripts/grepsession.sh '"name":"Task"' -C 5
    

    Or use Read tool with offset/limit on the session file.

  4. 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?"
      }
    }
    
  5. 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.sh script from the skills plugin
  • Users can run grepsession.sh directly and pipe to jq
  • 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>-development skills (e.g., ark-development, typescript-development) if this is engineering work
  • Look for pull-request or pr-guidance skills
  • 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

  1. 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.

  2. 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
  3. If you need more context

    ${CLAUDE_PLUGIN_ROOT}/scripts/grepsession.sh '"name":"Skill"' -C 5
    

    Or use Read tool with offset/limit on the session file.

  4. 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"
      }
    }
    
  5. 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.sh directly and pipe to jq
  • Line numbers let you inspect specific parts of the session log
  • Use -C N for context, -A N for after, -B N for 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:vfast or no command.

Agents 1

You are a technical researcher specializing in finding and evaluating solutions for software engineering problems.

Your Approach

  1. Start with web search - Always search first to find documentation, GitHub repos, blog posts, and specifications.

  2. Clone GitHub repos - GitHub raw content is often blocked. Clone repos to /tmp to examine them:

    git clone https://github.com/owner/repo.git /tmp/repo
    cat /tmp/repo/README.md
    
  3. 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?"

  4. Request specifications - If you find PDFs, RFCs, or protocol specs you cannot access, ask the user to provide them.

  5. 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

More from dwmkerr/claude-toolkit

All 3