Claude Code Internals: How Skills, Hooks, MCP, and Subagents Actually Work

Source-labeled extension layers from local context to external state.

Updated July 2026: This refresh keeps the original network-trace analysis, but updates the mental model for current Claude Code docs. Custom commands are now documented as merged into skills, hooks cover more lifecycle events, subagent context behavior has important exceptions, plugins are part of the extension story, and MCP needs a clearer security and state boundary.

Claude Code internals are easiest to misunderstand when every extension feature is described as "instructions for the agent." That is too broad to be useful. A CLAUDE.md file, an output style, a skill, a hook, a subagent, a plugin, and an MCP server can all change what happens in a Claude Code session, but they do it at different points in the harness.

Quick answer: As of July 2026, Claude Code assembles a run through several extension layers: CLAUDE.md contributes persistent project and user context, output styles adjust response behavior through the system-prompt layer, skills and slash invocation add reusable procedures when invoked manually or when Claude decides they are relevant, hooks run at lifecycle events and can enforce deterministic policy, subagents delegate work into separate context windows, plugins package shareable extension sets, and MCP connects Claude Code to external tools, resources, prompts, and durable systems. This article separates official documentation, first-party Agiflow traces, third-party analysis, community claims, and practical inference so the implementation facts do not blur together.

The practical thesis is simple: use the smallest layer that owns the job. Put stable project context in CLAUDE.md. Put response behavior in output styles. Put repeatable procedures in skills or slash-invoked skills. Put non-negotiable lifecycle policy in hooks. Put isolated, verbose work in subagents. Put distribution in plugins. Put shared tools and durable state in MCP-connected systems.

Two companion guides apply that boundary to durable project work: Claude Code task persistence limits covers local task state, while the Claude Code project board guide covers shared MCP-readable state.

That boundary matters for teams. When everything lives in one local session, debugging becomes a guessing game: was the behavior caused by a project memory file, an output style left on from yesterday, a skill that loaded automatically, a hook that changed the tool path, a subagent with its own context, or an MCP server schema? The answer determines the fix.

Claude Code Internals: What changed since the original analysis

The original October 2025 post was built from instrumented Claude Code network traffic. That trace work is still the article's first-party value. The update needed is source discipline. Some older implementation observations remain useful, but they need version labels and current docs beside them.

The confidence model for this article

I use five source labels throughout the rest of the post:

The extension layer map

Claude Code is an agentic coding tool that can read code, edit files, run commands, and integrate with development tools across terminal, IDE, desktop app, and browser surfaces [1]. The extension system sits around that agent loop. Each mechanism changes a different part of the run.

Official: Claude Code memory docs describe CLAUDE.md files as persistent instructions that guide behavior. The same docs describe multiple scopes, including managed, user, project, and local memory. Subdirectory CLAUDE.md files can load lazily when Claude reads files in those directories [2].

The important detail for Claude Code internals is placement. The memory docs say CLAUDE.md content is delivered as a user message after the system prompt, not as the system prompt itself [2]. That matches the older Agiflow observation that project memory appeared in message-level context rather than the system array [20].

Use CLAUDE.md for stable project standards, architecture notes, naming conventions, test commands, and domain rules that should be visible across a project. Keep it short. If the file becomes a policy engine, a checklist library, and a knowledge base at the same time, the model sees too much context on too many turns.

Do not use CLAUDE.md when the behavior must happen regardless of model choice. Claude Code's own memory docs point teams toward hooks when fixed lifecycle behavior is required [3]. That is a useful bright line: CLAUDE.md guides. Hooks execute.

Output styles change how Claude responds

Official: Output styles change how Claude responds rather than what it knows, and they modify system-prompt behavior to set role, tone, and output format [4].

That is why output styles belong in a separate category from CLAUDE.md. Project memory says, "Here is the codebase and its rules." An output style says, "Answer like this." In the original trace set, output style content appeared as an additional system-prompt block [20]. That trace is useful, but the current supported claim is narrower: output styles affect response behavior through the system-prompt layer [4].

Use output styles when you want a session-wide answer shape: terse code review, teaching mode, software-architect critique, or implementation-only responses. Avoid using them for one-off instructions. A forgotten output style is hard to see and easy to misdiagnose.

Skills and slash invocation are now a merged mental model

Official: Claude Code skills use a SKILL.md file, can be invoked directly with /skill-name, can be used automatically when relevant, and load their body only when used [5]. The same docs say custom commands have been merged into skills. A legacy .claude/commands/deploy.md file and a .claude/skills/deploy/SKILL.md file can both create /deploy, while existing .claude/commands/ files keep working [6].

That means the old split of "slash commands are deterministic, skills are model-invoked" needs nuance. Slash invocation is still user-explicit. Skills can also be direct-invoked. The bigger distinction is that skills are folders with metadata, instructions, supporting files, invocation controls, and progressive disclosure [5][7].

The practical rule:

• Use direct slash invocation when the user should choose the exact moment.
• Use automatic skill use when the procedure is relevant by task, not by ritual.
• Use supporting files when the procedure needs examples, scripts, references, or templates that should not sit in the always-loaded body.
• Keep descriptions concrete. If a skill's trigger language is vague, the model has less to match against.

There is also a hook interaction worth knowing. Current hook docs say UserPromptExpansion covers direct slash command or skill paths that bypass PreToolUse on the Skill tool, and that this hook can block expansion or add context [10]. If your governance model assumes every skill path crosses one PreToolUse gate, update it.

Hooks are lifecycle policy, not polite suggestions

Official: Hooks are user-defined commands at Claude Code lifecycle points. They provide deterministic control for rules, automation, and tool integration [8]. Current hook events include SessionStart, UserPromptSubmit, UserPromptExpansion, PreToolUse, PostToolUse, PostToolBatch, SubagentStart, SubagentStop, InstructionsLoaded, ConfigChange, and more [9].

Hooks matter because the trigger does not depend on whether the model remembers a rule. A PreToolUse hook can block tool execution [9]. Hook handlers can also be command, HTTP, MCP tool, prompt, or agent hooks, with MCP tool hooks depending on connected MCP servers [9].

This is the right layer for lifecycle policy:

• block a risky command before it runs
• add context at a specific lifecycle point
• log or audit tool use
• coordinate with an external service
• add guardrails around prompt expansion
• run validation after a batch of tool calls

Do not overstate hooks as a complete security boundary. They can enforce rules inside the Claude Code lifecycle, but the surrounding environment still matters: trusted hook code, permissions, shell behavior, configured tools, and what the user can override.

Subagents are separate work contexts with exceptions

Official: Subagents are specialized assistants with their own context window, custom system prompt, tool access, and independent permissions [11]. They fit verbose, self-contained, permission-restricted work. The main conversation is still better for quick changes, latency-sensitive work, and tasks that need frequent back-and-forth [13].

The current docs correct an important older claim. Built-in Explore and Plan skip CLAUDE.md files and parent-session git status, while every other built-in and custom subagent loads both [12]. The original trace set showed subagent delegation as a separate conversation, which remains the useful architectural point [20]. The context-loading detail now needs the official exception.

Use subagents when the work would flood the main context: codebase exploration, log analysis, security review, migration planning, or a long research sweep. Do not use them for a tiny answer. Spawning a separate worker adds coordination cost, and the subagent only knows what its own context provides.

For multi-agent systems beyond one Claude Code session, the same principle shows up in agent handoff discipline: pass the evidence the next worker needs, not an undifferentiated transcript.

Plugins package capabilities for sharing

Official: Claude Code's extension overview describes plugins as bundles for feature sets, including skills, hooks, subagents, and MCP servers [14]. The settings docs also place project settings in the team-shared layer for permissions, hooks, MCP servers, and plugins [15].

Think of plugins as distribution, not as a new reasoning primitive. A plugin can carry the same kinds of components described above. Its job is to make a bundle installable, namespaced, and shareable across users or projects.

That creates one governance problem: a plugin can bring several control points at once. Before installing one into a team workflow, inspect the skills, hooks, subagents, and MCP servers it includes. A community GitHub issue has alleged namespace impersonation risk around skill paths that look official; treat that as a community security claim, not a confirmed Anthropic finding, but the review habit is still sound [23].

MCP is the external tool and state boundary

Spec: MCP standardizes JSON-RPC communication between hosts, clients, and servers. Servers can expose resources, prompts, and tools; clients can expose capabilities such as sampling, roots, and elicitation [17].

That makes MCP different from a local instruction mechanism. It is not just "more context." It is a protocol boundary where Claude Code can reach external systems with defined tools and resources. The MCP spec also names security principles around user consent, data privacy, tool safety, and the fact that tool descriptions from untrusted servers should not automatically be trusted [18].

Use MCP when the assistant needs structured access to something outside the session: a project board, source of truth, artifact store, deployment tool, documentation system, or business data source. Do not treat MCP as automatically safer than local skills or hooks. It needs trusted servers, scoped permissions, clear consent, and careful tool descriptions.

For the project-management version of this boundary, see MCP-native project management. The same idea also shows up in AI coding control surfaces: the important question is not only which model is smarter, but where the steering point and shared state live.

Updated decision matrix

Network trace notes and version boundaries

The original post instrumented Claude Code API traffic and published the logs at AgiFlow/claude-code-prompt-analysis [20]. Keep reading those traces as observed behavior, not as a stable Anthropic API contract.

The trace value is still real. It shows the difference between context added to message arrays, output-style behavior added around the system prompt, skill use through tool calls, and subagent delegation as a separate conversation. It also explains why two mechanisms that feel similar in the UI can have different cost, latency, and debugging properties.

Observed: CLAUDE.md appeared in message-level context

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "<system-reminder>... Contents of /path/to/CLAUDE.md ...</system-reminder>"
        }
      ]
    }
  ]
}

That historical observation lines up with current memory docs saying CLAUDE.md is delivered as user-message context after the system prompt [2][20]. The current docs add the scoping and lazy-loading nuance that a raw trace snippet alone will not teach you [2].

Observed: output styles changed the system-prompt layer

{
  "system": [
    { "type": "text", "text": "You are Claude Code..." },
    { "type": "text", "text": "# Output Style: software-architect\n..." }
  ],
  "messages": []
}

That is why output styles should not be used for project knowledge. They change response behavior. They do not replace memory files, tools, or external state [4].

Observed: skills used a tool-call flow

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "name": "Skill",
      "input": { "command": "example-skill" }
    }
  ]
}

The current docs describe the supported skill model more broadly: SKILL.md, direct slash invocation, automatic use when relevant, and body loading only when used [5]. That is enough for design decisions. Do not infer every current skill expansion path from an older captured payload unless you rerun instrumentation.

Observed: subagents delegated into separate conversations

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "name": "Task",
      "input": {
        "subagent_type": "Explore",
        "prompt": "Analyze auth flows..."
      }
    }
  ]
}

The durable point is isolation. Subagents are not just a different prompt template; they are separate work contexts with their own system prompt, tool access, permissions, and context window [11]. The current docs add the Explore and Plan exception for CLAUDE.md and parent git status [12].

Security and context cost trade-offs

Claude Code extension design has two recurring costs: context cost and control cost.

Context cost is the amount of instruction, schema, memory, or intermediate result the model has to carry. CLAUDE.md and output styles can become persistent overhead. Skills load when used. Hooks fire at specific lifecycle points. Subagents move work into a separate context window. MCP servers expose external capabilities through a protocol, and the amount of tool description or resource context depends on the server and host integration.

Control cost is how hard it is to guarantee behavior. CLAUDE.md and output styles guide the model. Slash invocation gives the user direct control over starting a procedure. Hooks are deterministic at configured lifecycle points and can block tool execution [9]. MCP gives structured access to external tools and resources, but the MCP spec still requires consent, privacy protection, tool safety, and distrust of untrusted tool descriptions [18].

A third-party architecture preprint frames Claude Code mechanisms such as MCP, plugins, skills, and hooks as different context-cost tiers [22]. I find that framing directionally useful, but I would not treat it as official Anthropic doctrine. The safer design rule is: do not pay persistent context cost for a rule that only matters at one lifecycle event, and do not ask the model to remember a policy that a hook can enforce.

Community discussions point to the same operational pain. Practitioners ask whether hooks, skills, slash commands, subagents, plugins, and MCP are overlapping features or distinct control points [24][25][26]. They are distinct control points, but the overlap is real enough that teams need placement rules.

Team operating recommendations

Start with the smallest owner of the job

If a plain prompt solves the problem, use a plain prompt. If the prompt becomes a repeated ritual, turn it into a slash-invoked skill. If the same procedure should load automatically when relevant, make the skill description specific and keep heavy references in supporting files. If the rule must fire regardless of model choice, move it into a hook.

That sequence keeps the system debuggable. It also prevents "extension sprawl," where every workflow has a CLAUDE.md rule, a skill, a hook, a subagent, and an MCP tool all trying to own the same behavior.

Keep stable context out of procedural skills

Project architecture, coding conventions, and domain vocabulary belong in memory. A deployment checklist, incident review procedure, or design critique rubric belongs in a skill. Mixing the two makes both worse. The model sees too much background in every procedure, and the project memory becomes a library of commands nobody can quickly audit.

If the procedure needs examples, templates, or reference material, use the skill folder's supporting files and progressive disclosure pattern [7]. That keeps SKILL.md readable while preserving deeper instructions for when the skill actually runs.

Use hooks when behavior must not depend on the model

Claude Code's memory docs explicitly recommend hooks for fixed lifecycle behavior [3]. That is the rule I would use for teams. If a behavior is a preference, put it in memory or style. If it is a policy, put it in a hook or external enforcement layer.

Examples:

• "Prefer Vitest examples" can live in CLAUDE.md.
• "Never run destructive migration commands without approval" belongs in a hook.
• "Log every production deployment command" belongs in a hook or external automation.
• "When a skill expands, add compliance context" may belong in UserPromptExpansion [10].

Use subagents for context isolation, not as a decoration

Subagents help when the work is self-contained and verbose. They are a bad fit for tiny tasks or work that needs constant user judgment. The official docs say the main conversation is better for quick changes and frequent back-and-forth [13].

When delegating, write the prompt as a handoff contract: goal, scope, allowed tools, required evidence, and output shape. Do not assume the subagent can infer the main conversation. For multi-agent handoffs outside Claude Code, the same discipline appears in role separation and handoff contracts.

Move shared state out of session-local context

Claude Code can shape one run. It does not, by itself, give a team a durable system of record for every task, artifact, decision, lock, and handoff. That boundary is where MCP-connected project systems become useful.

For a single developer, repo-local memory and skills may be enough. For a team, the failure mode changes. The question becomes: who owns the state after the session ends? If the answer is "the last transcript," the next agent starts by reconstructing reality. That is the same context-decay problem described in why AI coding agents lose context, only spread across more people and machines.

Where Agiflow fits

Agiflow does not replace Claude Code extension mechanisms. It sits on the other side of the boundary.

Use Claude Code mechanisms to shape the run:

• CLAUDE.md for local project context
• output styles for response behavior
• skills for procedures
• hooks for lifecycle policy
• subagents for isolated work
• plugins for distribution
• MCP for external access

Use an external system when the state has to outlive the run: task status, acceptance criteria, artifacts, vault context, workflow locks, review gates, and cross-machine handoffs. That is the operating model behind Agiflow's category: durable project context for AI-assisted work, exposed to agents through MCP-native and CLI-accessible workflows.

If you are evaluating this boundary, start with the concrete failure: two sessions need the same truth. One needs to know what is in progress, the other needs to know what evidence was produced, and a human needs to know whether the work is blocked. That truth should not be hidden in a chat transcript. For the broader state architecture, read MCP project management tools and scaling AI agents across machines with Agiflow CLI.

Use Agiflow to keep AI agent work tied to durable tasks, artifacts, and handoffs when one Claude Code session is no longer the whole operating surface.

Final mental model

Claude Code internals make more sense when you stop asking which extension mechanism is "best" and start asking which layer owns the job.

That is the architecture. The hard part is restraint.

Most teams do not need more agent magic. They need fewer overlapping control points, clearer source labels, and a shared place where task state survives the next context window. Claude Code gives you a powerful local harness. Use it deliberately, and move durable state outside the harness when the work has to survive beyond one run.

References

[1] Official: Claude Code overview. Captured 2026-07-04. https://code.claude.com/docs/en/overview

[2] Official: Claude Code memory docs. Captured 2026-07-04. https://code.claude.com/docs/en/memory

[3] Official: Claude Code memory docs, hooks recommendation for fixed lifecycle behavior. Captured 2026-07-04. https://code.claude.com/docs/en/memory

[4] Official: Claude Code output styles docs. Captured 2026-07-04. https://code.claude.com/docs/en/output-styles

[5] Official: Claude Code skills docs, SKILL.md, direct invocation, automatic use, and loading behavior. Captured 2026-07-04. https://code.claude.com/docs/en/skills

[6] Official: Claude Code skills docs, custom commands merged into skills and legacy .claude/commands/ compatibility. Captured 2026-07-04. https://code.claude.com/docs/en/skills

[7] Official: Claude Code skills docs, supporting files and progressive disclosure. Captured 2026-07-04. https://code.claude.com/docs/en/skills

[8] Official: Claude Code hooks guide. Captured 2026-07-04. https://code.claude.com/docs/en/hooks-guide

[9] Official: Claude Code hooks reference. Captured 2026-07-04. https://code.claude.com/docs/en/hooks

[10] Official: Claude Code hooks reference, UserPromptExpansion and direct slash or skill expansion paths. Captured 2026-07-04. https://code.claude.com/docs/en/hooks

[11] Official: Claude Code subagents docs. Captured 2026-07-04. https://code.claude.com/docs/en/sub-agents

[12] Official: Claude Code subagents docs, Explore and Plan context-loading exception. Captured 2026-07-04. https://code.claude.com/docs/en/sub-agents

[13] Official: Claude Code subagents docs, suitable and unsuitable tasks. Captured 2026-07-04. https://code.claude.com/docs/en/sub-agents

[14] Official: Claude Code extension overview, plugins. Captured 2026-07-04. https://code.claude.com/docs/en/features-overview

[15] Official: Claude Code settings docs. Captured 2026-07-04. https://code.claude.com/docs/en/settings

[16] Official: Claude Code Agent SDK overview and TypeScript reference. Captured 2026-07-04. https://code.claude.com/docs/en/agent-sdk/overview and https://code.claude.com/docs/en/agent-sdk/typescript

[17] Spec: Model Context Protocol specification, host, client, server, resources, prompts, and tools. Captured 2026-07-04. https://modelcontextprotocol.io/specification/2025-11-25

[18] Spec: Model Context Protocol security principles. Captured 2026-07-04. https://modelcontextprotocol.io/specification/2025-11-25

[19] Official: Anthropic skills repository. Captured 2026-07-04. https://github.com/anthropics/skills

[20] First-party trace: AgiFlow Claude Code prompt-analysis repository. Captured 2026-07-04. https://github.com/AgiFlow/claude-code-prompt-analysis

[21] Official changelog: Claude Code changelog. Captured 2026-07-04. https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md

[22] Third-party analysis: Claude Code architecture preprint. Captured 2026-07-04. https://arxiv.org/html/2604.14228v1

[23] Community claim: Anthropic skills issue 492 about namespace confusion risk. Captured 2026-07-04. https://github.com/anthropics/skills/issues/492

[24] Community listening: Hacker News discussion of Claude Code command, skill, subagent, plugin, and MCP consolidation. Captured 2026-07-04. https://news.ycombinator.com/item?id=48289950

[25] Community listening: Reddit discussion of hooks, slash commands, and skills. Captured 2026-07-04. https://www.reddit.com/r/ClaudeCode/comments/1tot1zw/hooks_vs_slash_commands_vs_skills_whats_the_real/

[26] Community listening: Reddit discussion of skills and subagents. Captured 2026-07-04. https://www.reddit.com/r/ClaudeAI/comments/1obq6wq/understanding_claude_skills_vs_subagents_its_not/

[27] Community listening: Reddit discussion of hooks and skills. Captured 2026-07-04. https://www.reddit.com/r/AI_Agents/comments/1smmjvl/hooks_vs_skills_for_claude/