11 / 20 Extension Points src/commands.ts · src/skills/ · src/services/mcp/ · src/utils/hooks/

6 extension mechanisms. Priority matters.

MCP servers, custom agents, skills, hooks, plugins, and CLAUDE.md — each extends Claude Code differently. They load in a specific priority order, and name conflicts are resolved by first-wins deduplication. Bundled skills always beat user skills.

Extension types — each with different scope

Bundled skills — highest priority

MCP transports — stdio, SSE, HTTP, WS, SDK, in-proc

Loading Priority (Highest → Lowest)

When two extensions share a name, the first one loaded wins. Assembly happens in loadAllCommands() (commands.ts lines 449-469).

1Bundled Skills — compiled into binary. registerBundledSkill() at startup. Examples: /schedule, /loop, /claude-api, /simplify. Always override user skills with same name.

2Built-in Plugin Skills — from enabled built-in plugins (e.g., Claude in Chrome). Second-highest priority.

3Skill Directory — from ~/.claude/projects/<slug>/skills/ or ~/.claude/skills/. User-written markdown files with frontmatter. Override built-in CLI commands.

4Workflow Commands — from ~/.claude/workflows/ (if WORKFLOW_SCRIPTS feature enabled). Registered as commands.

5Plugin Commands + Plugin Skills — from user-installed plugins. Lower priority than skill directory.

6Built-in CLI Commands — /help, /status, /config, /memory, etc. LOWEST priority — user skills can override these.

Deduplication: First occurrence wins. Dynamic skills (discovered mid-session) are inserted before built-in commands but after plugins. MCP skills live OUTSIDE this dedup chain — can coexist with same-named disk skills.

6 Extension Mechanisms

MCP Servers

Add unlimited tools via Model Context Protocol. 6 transports: stdio (subprocess), SSE (HTTP streaming), HTTP (custom), WebSocket (TLS/proxy), SDK Control (embedded), In-Process (zero overhead).

Configured in settings.json under mcpServers. 24 integration files in services/mcp/. OAuth authentication supported. Tool schemas merged at boot.

Custom Agents

Markdown files in ~/.claude/agents/ define reusable subagents with system prompts, tool restrictions, and model overrides.

Invoked via Agent tool or /agent command. Can define their own MCP servers in frontmatter (cleaned up on exit).

Skills

Markdown files in ~/.claude/skills/ define reusable slash commands. Frontmatter: name, description, model override, allowed tools, execution context (inline or fork).

19 bundled skills compiled into binary. User skills can reference disk files (extracted on first use, memoized).

Hooks

Shell commands running before/after tool execution. Configured per-tool in settings.json under hooks.

PreToolUse hooks CAN block execution. PostToolUse hooks run after, can transform output. 20 hook events from Setup to PermissionDenied. 15s default timeout. 10min tool timeout. Workspace trust gating.

Plugins

Community packages installed via /plugin install @author/name. Can provide commands, skills, MCP servers, hooks.

Extra marketplaces configurable. Policy pluginOnlyPolicy restricts MCP to plugin-only mode. Admin-trusted sources: built-ins, policySettings, plugin providers.

CLAUDE.md

Project instruction files discovered by walking directory tree up to git root. Supports @import composition with circular reference prevention.

4-priority hierarchy: global /etc/ → user ~/.claude.md → project ./CLAUDE.md → local overrides. Injected into system prompt. NOT subject to 200-line truncation (unlike MEMORY.md). Committable to VCS.

Hook Interception — What Can & Can't Be Done

What hooks CAN do

PreToolUse — block tool execution (return non-zero)
Run shell commands, HTTP requests, prompts after tool use
Modify tool output via response attachment
Track tool usage, trigger alerts, enrich results
Run custom validators (e.g., lint after every file write)

What hooks CANNOT do

Override the permission system (hooks are separate layer)
Modify tool INPUT before execution (only output after)
Run during speculation (hooks are real-execution only)
Exceed timeout (15s default, configurable)

CLAUDE.md vs MEMORY.md

Aspect	CLAUDE.md	MEMORY.md
Purpose	Project instructions	Cross-session memory index
Source	Code (version controlled)	Generated (by Claude + user)
Truncation	No limit	200 lines / 25KB
Content	Direct instructions	Pointer index to topic files
Discovery	Walk dir tree to git root	Fixed path in memory dir
Composition	`@import` with cycle detection	Pointer links to *.md files
Injection	User context (system prompt)	Memory section (system prompt)