claude-code-sdk

What this skill does

# Claude Code SDK

Authoritative reference for Claude Code extensibility and configuration. Use this skill when building, configuring, or
debugging any Claude Code extension mechanism.

## References

- **Skills** — [`${CLAUDE_SKILL_DIR}/references/skills.md`] frontmatter fields, invocation control matrix, `paths:`
  shared mechanic with rules, `skillOverrides` setting, string substitutions, dynamic context injection, subagent
  execution via fork, compaction budget, description budget (1,536-char per-entry, 1% context aggregate), bundled skills
- **Rules** — [`${CLAUDE_SKILL_DIR}/references/rules.md`] `.claude/rules/*.md` discovery (recursive), two loading modes
  (unconditional = launch-time priority; conditional via `paths:`), `paths:` syntax (comma-string OR YAML list), project
  vs personal scope, InstructionsLoaded hook with all 5 matchers, sharing patterns, `claudeMdExcludes`
- **Plugins** — [`${CLAUDE_SKILL_DIR}/references/plugins.md`] plugin.json schema (incl. `dependencies` array v2.1.110+,
  `experimental.monitors` v2.1.105+, `experimental.themes` v2.1.118+), directory layout, `${CLAUDE_PLUGIN_ROOT}`/`_DATA`
  env vars, marketplace.json (5 source types + `allowCrossMarketplaceDependenciesOn`), LSP server configs, `bin/` PATH
  contract, `claude plugin tag --push` and `claude plugin prune`, `allowedChannelPlugins` managed setting
- **Hooks** — [`${CLAUDE_SKILL_DIR}/references/hooks.md`] all **29** events with input/output JSON schemas and matcher
  values, **5** hook types (command, http, prompt, agent, mcp_tool) with handler fields, exit code blocking table (incl.
  PreCompact blocking v2.1.105+), async hooks, decision control patterns, security
- **Subagents** — [`${CLAUDE_SKILL_DIR}/references/subagents.md`] 5 built-in agents, custom agent frontmatter, tool
  control, MCP scoping, worktree isolation, invocation methods, agent teams (architecture, tasks, messaging, hooks,
  lifecycle)
- **MCP** — [`${CLAUDE_SKILL_DIR}/references/mcp.md`] `.mcp.json` schema, 3 transports (HTTP/SSE/stdio), scopes and
  precedence, OAuth (incl. headersHelper), env var expansion, managed config, tool search, `alwaysLoad` (v2.1.121+), 2KB
  description cap, `anthropic/maxResultSizeChars` per-tool override, elicitation, resources, prompts as commands
- **Memory** — [`${CLAUDE_SKILL_DIR}/references/memory.md`] full `.claude` directory tree, CLAUDE.md hierarchy and
  loading order, `@import` syntax (max depth 5), auto memory (`MEMORY.md` 200-line/25KB cap), path-specific rules
- **Settings** — [`${CLAUDE_SKILL_DIR}/references/settings.md`] 5-level scope hierarchy, server-managed settings
  (v2.1.30 Enterprise / v2.1.38 Teams), 50+ settings keys, permission rule syntax per tool type, 6 permission modes,
  sandbox config (filesystem/network isolation), `claude project purge` (v2.1.126), expanded protected paths
- **Auto Mode** — [`${CLAUDE_SKILL_DIR}/references/auto-mode.md`] classifier mechanics (Sonnet 4.6 background, never
  sees tool results), prompt-injection resistance, default block lists, failure modes (3-consecutive / 20-total circuit
  breaker), `autoMode.{environment,allow,soft_deny}` config (v2.1.118+ `$defaults` sentinel), CLI subcommands,
  enterprise lockdown
- **Cloud** — [`${CLAUDE_SKILL_DIR}/references/cloud.md`] surface comparison (versions, plans, provider restrictions),
  Routines (v2.1.105+, schedule/API/GitHub triggers, `/fire` endpoint), Ultraplan (v2.1.91+), Ultrareview (v2.1.86+ with
  pricing tier), Remote Control (v2.1.51+ vs `--teleport`), Claude Code on the Web, Code Review, Computer Use (v2.1.85+
  macOS-only)
- **Model config** — [`${CLAUDE_SKILL_DIR}/references/model-config.md`] aliases (incl. `[1m]` variants), effort levels
  (low/medium/high/xhigh/max — available levels depend on the model), opusplan hybrid routing, third-party provider
  pinning, prompt caching env vars
- **Output styles** — [`${CLAUDE_SKILL_DIR}/references/output-styles.md`] 3 built-in styles, custom style frontmatter,
  `keep-coding-instructions` flag, system prompt modification pipeline, activation timing (session start only)
- **Channels** — [`${CLAUDE_SKILL_DIR}/references/channels.md`] MCP server contract, one-way vs two-way types, sender
  gating, permission relay, console (API key) auth (v2.1.128+), `allowedChannelPlugins` allowlist (v2.1.84+), enterprise
  controls, built-in plugins (Telegram/Discord/iMessage/fakechat)
- **Tools** — [`${CLAUDE_SKILL_DIR}/references/tools.md`] built-in tools by category with permission requirements, name
  patterns for permission rules, agent tool restrictions, hook matchers, skill `allowed-tools`
- **Status line** — [`${CLAUDE_SKILL_DIR}/references/statusline.md`] configuration fields, complete JSON input schema,
  ANSI colors, OSC 8 clickable links, caching by session_id, plugin delivery
- **Agent SDK** — [`${CLAUDE_SKILL_DIR}/references/agent-sdk.md`] entry points (`query`/`ClaudeSDKClient`/
  `unstable_v2_*` preview), session-based send/stream patterns, full options reference, sessions (continue/resume/fork),
  system prompt config, permissions, hooks, custom tools, MCP, subagents, streaming, structured outputs, headless
  `init.plugin_errors` schema, Claude Agent SDK v0.1.0 migration, TS↔Python differences
- **Best practices** — [`${CLAUDE_SKILL_DIR}/references/best-practices.md`] context window mechanics, verification
  patterns, scheduling (`/loop`/`/proactive` alias, cron tools, cloud/desktop), checkpointing and rewind, extension
  mechanism selection table

Read the relevant reference before making detailed changes. References provide field-level schemas, complete tables, and
implementation details.

## Concepts

<concepts>

**Skill** — Prompt template in `SKILL.md` loaded on-demand when description matches user request. Frontmatter controls
invocation, tool access, model, effort (incl. `xhigh` where the model supports it), execution context (`context: fork`
for subagent), scoped hooks, and `paths:` glob filter for file-pattern auto-activation. Supports string substitutions
(`$ARGUMENTS`, `${CLAUDE_SKILL_DIR}`, `${CLAUDE_EFFORT}`) and dynamic context injection via `` !`command` ``. Per-skill
description cap: 1,536 chars (raised from 250 in v2.1.105). Aggregate description budget: 1% of context window with
8,000-char fallback (override via `SLASH_COMMAND_TOOL_CHAR_BUDGET`). The `skillOverrides` setting toggles per-skill
visibility/invocability in four states; the `/skills` menu writes it.

**Rule** — Modular project context in `.claude/rules/*.md` (project) or `~/.claude/rules/*.md` (personal). Two loading
modes: **without `paths:`** loads at launch with the same priority as `.claude/CLAUDE.md` — use to split an overgrown
CLAUDE.md into topic files. **With `paths:`** is conditional, only injected when working with files matching the glob.
Discovery is recursive across subdirectories. `paths:` accepts a comma-separated string or a YAML list (YAML-list form
added in v2.1.84). The `InstructionsLoaded` hook fires for each rule loaded with matchers `session_start`,
`nested_traversal`, `path_glob_match`, `include`, and `compact`. Rules are file-triggered; skills are task-triggered.
The `paths:` field is a **shared mechanic** between rules and skills — same syntax, same semantics, applied to two
primitives.

**Plugin** — Distributable package of skills, agents, hooks, MCP servers, LSP servers, output styles, monitors, themes,
and default settings. Manifest at `.claude-plugin/plugin.json` (only `name` is required when present). Skills namespaced
as `/plugin:skill`. Two path variables: `${CLAUDE_PLUGIN_ROOT}` (install dir, changes on update) and
`${CLAUDE_PLUGIN_DATA}` (persistent data dir). Marketplace supports 5 source types. `bin/` adds executables to Bash PATH
(W14 2026). Plugins ship custom color themes via `experimental.themes` (v2.1.118+) and background monitors via
`experimental.monitors` (v2.1.105+; the top-level `monitors` key is deprecated as of v2.1.129).

**Plugin Dependencies** — A plugin can declare other