Teaches Claude Code's concurrency model: isConcurrencySafe() for parallel tool execution, AbortController propagation for cancellation, Promise.all() for parallel initialization, and the StreamingToolExecutor for concurrent progress streams. Use this when writing tools that could benefit from parallel execution, need to respect cancellation, or must stream partial results. Read-only tools that don't declare concurrency safety are needlessly serialized.
Teaches how to create a new Claude Code tool using the buildTool() factory from src/Tool.ts. Use this whenever adding a new capability to Claude Code — buildTool is the only correct entry point. It fills in safe defaults for isConcurrencySafe, isReadOnly, isDestructive, checkPermissions, and userFacingName so you only implement what your tool actually needs.
Use when extracting an engineering pattern from a codebase and packaging it as a skill for an AI assistant. Triggered when: converting a recurring code pattern into a SKILL.md, wanting your AI to apply a specific pattern automatically, or validating whether an existing skill is good enough to ship. Covers structure, the real-code requirement, the two-layer generic/specific design, and six quality tests.
Teaches Claude Code's core domain model: Tool, Message, Task, ToolUseContext, AppState, and Command — the six concepts every part of the system is built around. Use this before writing any new tool, command, or feature that touches the conversation loop. Essential for understanding how Claude's capability system is structured and why the abstractions exist.
Teaches Claude Code's error philosophy: tool call() throws typed errors, the framework catches them and formats them for the LLM as structured tool result content, and custom error types carry structured context at system boundaries. Use this whenever writing a tool, utility function, or service that can fail. The distinction between "errors the LLM should see" and "errors that crash the session" is the core insight.
Teaches Claude Code's startup and runtime performance patterns: lazySchema() for deferred Zod parsing, feature() flags for build-time dead code elimination, memoize() for expensive repeated computations, parallel initialization with Promise.all(), and profileCheckpoint() for tracking load times. Use this whenever writing code that runs at startup, on every turn, or in a hot loop. Startup latency is Claude Code's most user-visible performance metric.
Teaches Claude Code's module organization: tools/ for capabilities, commands/ for user-facing slash commands, services/ for business logic, state/ for AppState, utils/ for pure utilities, hooks/ for React state, and components/ for TUI rendering. Use this when deciding where to put new code or when tracing an unfamiliar behavior to its source. The division is by responsibility boundary, not by feature.
Teaches Claude Code's naming system: Tool files are [Name]Tool.ts[x], commands use kebab-case, types are PascalCase, functions start with verbs in camelCase, booleans use is/has prefixes, constants use UPPER_SNAKE_CASE, and event handlers use on[Event]. Use this when naming new files, types, functions, or variables to match the existing codebase style. Consistent naming is how contributors find code without searching.