9 · The Extension System

An “extension point” means: letting third parties, or users themselves, add capabilities to the system without modifying the main program's source code. Claude Code has four kinds of extension points, each with a different mechanism.

9.1 The Four Extension Points Compared

9.2 The Skill System

Form

A skill is a SKILL.md file with YAML metadata at the top (the industry calls it frontmatter):

The core mechanism: progressive disclosure

Claude Code has a dedicated function to quantify the resident cost:

export function estimateSkillFrontmatterTokens(skill: Command): number

Because every skill's frontmatter is resident in the context, the fixed cost of installing 100 skills has to be measurable — otherwise users keep installing until they discover they're burning thousands of tokens per turn for nothing.

Loader implementation details

// skills/loadSkillsDir.ts
export type LoadedFrom = ...                    // which source it was loaded from
export function getSkillsPath(...)              // path to the skills directory
export function estimateSkillFrontmatterTokens(skill: Command): number
function parseHooksFromFrontmatter(...)         // parse hooks bundled with the skill
function parseSkillPaths(frontmatter): string[] | undefined
export function parseSkillFrontmatterFields(...)
export function createSkillCommand({...})       // wrap a skill as a command object
function isSkillFile(filePath: string): boolean
function transformSkillFiles(files: MarkdownFile[]): MarkdownFile[]
function buildNamespace(targetDir: string, baseDir: string): string   // namespace
function getSkillCommandName(filePath: string, baseDir: string): string
export const getSkillDirCommands = memoize(...)  // ★ result is cached
export function clearSkillCaches()

// dynamic skills: registered at runtime, not on disk
const dynamicSkillDirs  = new Set<string>()
const dynamicSkills     = new Map<string, Command>()

A few points worth noting:

• buildNamespace — skills have namespaces. A skill at skills/git/commit/SKILL.md gets the name git:commit. Prevents skills from different sources from colliding on names.
• memoize — the load result is cached. Scanning the skills directories means a lot of file reads, which can't happen every time. clearSkillCaches() exists alongside it for the /reload command.
• Dynamic skills — skills can be registered at runtime without writing a file. Plugins and MCP servers can use this mechanism to provide skills.

Skills are the bridge that “turns commands into tools”

Recall the dividing line from section 0.3: tools/ is what the model can call; commands/ is what only a human can type.

Skills break that boundary — they expose a piece of “command-style” content (a fixed procedure, domain knowledge) to the model in the form of a tool. And exposing it is cheap, because only a one-line description stays resident.

9.3 The Plugin System

The utils/plugins/ directory:

The corresponding slash commands live under commands/plugin/:

• ManagePlugins.tsx (314 KB) — the plugin management UI
• BrowseMarketplace.tsx (117 KB) — the marketplace browsing UI
• PluginSettings.tsx (126 KB) — plugin settings

Note that the UI code is bigger than the logic code. That's typical of terminal UIs — drawing an interactive list in a terminal, handling keyboard navigation, and rendering a scrollbar takes far more code than the same feature on a web page.

Cache-first loading

// QueryEngine.ts
// Cache-only: headless/SDK/CCR startup must not block on network for
// ref-tracked plugins. CCR populates the cache via CLAUDE_CODE_SYNC_PLUGIN_INSTALL
// (headlessPluginInstall) or CLAUDE_CODE_PLUGIN_SEED_DIR before this runs;
// SDK callers that need fresh source can call /reload-plugins.
const [skills, { enabled: enabledPlugins }] = await Promise.all([
  getSlashCommandToolSkills(getCwd()),
  loadAllPluginsCacheOnly(),        // ★ reads the cache only, no network requests
])

Put plainly: cache-only mode: headless / SDK / remote-environment startup must not block on the network to fetch “ref-tracked plugins.” … Callers that need fresh source can run the /reload-plugins command.

This is an important startup-performance constraint: startup in any automated scenario must not depend on the network. The network may be slow, down, or require authentication — and a job running in a pipeline can't hang because of it.

9.4 The MCP Client

MCP stands for Model Context Protocol, an open standard for connecting agents to external tool services. The services/mcp/ directory implements the client.

Two transports

Tool-name prefixes

MCP tool names get a prefix: mcp__server__tool. That way:

• Same-named tools from different servers don't collide
• Permission rules can be configured in bulk by server prefix (mcp__github matches every tool from that server)

But there's an exception mode: the environment variable CLAUDE_AGENT_SDK_MCP_NO_PREFIX turns the prefix off. So the Tool interface has a dedicated field to cope:

/**
 * For MCP tools: the server and tool names as received from the MCP server
 * (unnormalized). Present on all MCP tools regardless of whether `name` is
 * prefixed (mcp__server__tool) or unprefixed (CLAUDE_AGENT_SDK_MCP_NO_PREFIX mode).
 */
mcpInfo?: { serverName: string; toolName: string }

Whether or not the name is prefixed, the original server name and tool name are stored separately. That way permission checks, telemetry, and error messages all get accurate provenance without parsing the name string.

Asking the user for information (Elicitation)

The MCP protocol lets the server turn around and ask the user for information (say, “please enter your API key”). Claude Code has dedicated handling:

/**
 * Optional handler for URL elicitations triggered by tool call errors (-32042).
 * In print/SDK mode, this delegates to structuredIO.handleElicitation.
 * In REPL mode, this is undefined and the queue-based UI path is used.
 */
handleElicitation?: (
  serverName: string,
  params: ElicitRequestURLParams,
  signal: AbortSignal,
) => Promise<ElicitResult>

Two paths: in interactive mode, go through the UI queue and show a dialog (the corresponding component, ElicitationDialog.tsx, is 175 KB); in headless mode, go through the structured I/O protocol and forward the request to the outer caller.

And -32042 is a specific error code in the MCP protocol meaning “I need information from the user before I can continue.”

Other MCP-related tools

• ListMcpResourcesTool / ReadMcpResourceTool — besides tools, MCP can provide “resources” (readable data); these two tools let the model access them
• McpAuthTool — handles the OAuth authentication flow
• ReadMcpResourceDirTool — lists a resource directory (for servers that declare support)

9.5 Hooks: 15 Kinds of Lifecycle Events

Hooks let users run their own scripts at specific moments in the system. This is the most powerful and most dangerous extension point — because hooks can block operations and modify arguments.

// event types in types/hooks.ts
hookEventName: z.literal('PreToolUse')          // before a tool runs
hookEventName: z.literal('PostToolUse')         // after a tool runs
hookEventName: z.literal('PostToolUseFailure')  // after a tool fails
hookEventName: z.literal('PermissionRequest')   // on a permission request
hookEventName: z.literal('PermissionDenied')    // on a permission denial
hookEventName: z.literal('UserPromptSubmit')    // when the user submits a prompt
hookEventName: z.literal('SessionStart')        // session start
hookEventName: z.literal('Setup')               // initialization / maintenance
hookEventName: z.literal('SubagentStart')       // subagent start
hookEventName: z.literal('Notification')        // notification
hookEventName: z.literal('Elicitation')         // MCP elicitation
hookEventName: z.literal('ElicitationResult')   // elicitation result
hookEventName: z.literal('CwdChanged')          // working directory changed
hookEventName: z.literal('FileChanged')         // file modified externally
hookEventName: z.literal('WorktreeCreate')      // worktree created

claude-code/src/types/hooks.ts

A few more are defined elsewhere: Stop (before finishing), PreCompact (before compaction), and PostSampling (after model sampling).

The hook execution engine

The utils/hooks/ directory:

The existence of ssrfGuard.ts deserves attention. HTTP hooks send event content to a user-configured URL. Without protection, a malicious (or manipulated) config could make Claude Code hit http://169.254.169.254/ (the cloud provider's metadata endpoint, which hands out temporary credentials) — the classic server-side request forgery attack.

Hook progress feedback

export function startHookProgressInterval(params: {...}): ...
export const HOOK_TIMING_DISPLAY_THRESHOLD_MS = 500

Hooks are scripts users wrote themselves, so their run time is completely uncontrolled. Therefore:

• The timer is only shown past 500 milliseconds (avoids UI flicker for fast hooks)
• An interval timer periodically emits progress events so the user knows “the system isn't stuck; your hook is running”

Conditional hook matching

Hook configs can carry conditions, such as “only fire when the Bash tool runs a git command.” That takes cooperation from the tool:

/**
 * Prepare a matcher for hook `if` conditions (permission-rule patterns like
 * "git *" from "Bash(git *)"). Called once per hook-input pair; any
 * expensive parsing happens here. Returns a closure that is called per
 * hook pattern. If not implemented, only tool-name-level matching works.
 */
preparePermissionMatcher?(input: z.infer<Input>): Promise<(pattern: string) => boolean>

Note the design: it returns a closure rather than doing the match directly. Because a single tool call may need checking against dozens of hook patterns, and parsing (say, turning a shell command into a syntax tree) is expensive. So do the “expensive preparation” once and return a “cheap matcher” to call repeatedly.

9.6 Output Styles

outputStyles/ is a small but interesting extension point: it lets users replace the “personality” portion of the system prompt.

One of its effects in the code is that the query-source identifier becomes dynamic:

// Prefix-match because promptCategory.ts sets the querySource to
// 'repl_main_thread:outputStyle:<style>' when a non-default output style
// is active. The bare 'repl_main_thread' is only used for the default style.
function isMainThreadSource(querySource: QuerySource | undefined): boolean {
  return !querySource || querySource.startsWith('repl_main_thread')
}

The comment also mentions a bug this produced: