Ecosystem — Skills, Plugins, MCP

Skills: Markdown as Executable Configuration

Claude Code ships 17 bundled skills. A skill is a Markdown file with YAML frontmatter — it’s documentation that the system treats as configuration.

The frontmatter carries metadata: the skill’s name, what triggers it, what tools it requires, what permissions it needs, and whether it should auto-activate in certain contexts. The body of the file is the skill’s instruction text, which gets injected into the system prompt when the skill is active.

This design makes skills inspectable and editable without code changes. If you want to understand what the /web-access skill does, you read a Markdown file. If you want to modify how it behaves, you edit that file. If you want to write a new skill, you write Markdown — not TypeScript.

The bundled 17 cover the common cases: web access, PDF handling, code review, planning, etc. The skill system is also how custom workflows get added to Claude Code — the same mechanism the bundled skills use is available to anyone writing their own.

Plugins: Runtime Modification

The plugin system lives in 42 files and operates at a deeper level than skills. Where a skill adds instructions to the prompt, a plugin can modify three things:

1. The system prompt — add, remove, or modify prompt sections
2. The tool set — add new tools or restrict existing ones
3. The permission rules — add new permission rules or override existing ones

Plugins run at agent initialization, before the session starts. By the time the main loop begins, any active plugins have already modified the runtime. From the model’s perspective, the result looks like a different Claude Code — different capabilities, different rules.

This is how IDE integrations work. The VS Code extension and JetBrains plugin both load as plugins that modify the tool set (adding IDE-specific tools like “get current editor selection”) and the permission rules (pre-approving operations that the IDE’s environment makes safe).

The 42-file plugin system is larger than the 20-file skill system because plugins need to handle lifecycle management, conflict resolution when multiple plugins modify the same thing, and rollback if a plugin fails to load cleanly.

MCP: Protocol-Level Extension

MCP (Model Context Protocol) is the third extension point and operates at the protocol level. When Claude Code connects to an MCP server, two things happen:

Tool injection: The MCP server’s exposed tools become available as MCPTool instances in Claude Code’s tool registry. From the main loop’s perspective, these are indistinguishable from native tools — they go through the same 14-step execution pipeline, the same permission checks, the same hook system.

Instruction injection: The MCP server can inject text into Claude Code’s system prompt. This is how an MCP server tells the model how to use its tools correctly — context about what the tools do, when to use them, what their outputs mean.

The injection happens in the static section of the system prompt, which means it’s cached. An MCP server that injects 2000 tokens of instruction text pays the KV processing cost once per session, not once per turn.

Model Awareness as the Key Design Insight

The insight that connects skills, plugins, and MCP is this: the model needs to know about its capabilities to use them well.

This sounds obvious but has a non-obvious consequence: the extension mechanism isn’t just “add a tool.” It’s “add a tool and tell the model about the tool.” A tool that exists in the registry but isn’t mentioned in the system prompt is a tool the model doesn’t know to use. The model can’t search the tool registry — it can only use what’s in its context.

Every extension mechanism in Claude Code pairs capability addition with instruction injection:

• Skills inject instruction text alongside their activation
• Plugins modify the prompt alongside modifying the tool set
• MCP servers inject instruction text alongside their tool definitions

This is why the skill/plugin/MCP architecture is unified despite having three different extension points. They all solve the same problem: extending Claude Code means extending both what the agent can do and what the agent knows it can do.

The 17 Bundled Skills vs. 42 Plugin Files

The count difference is instructive. Skills are stateless — a skill is just a Markdown file that adds context. Plugins are stateful — they need initialization, lifecycle management, conflict detection. The 42 plugin files relative to 17 skill files reflects the overhead of adding runtime mutation on top of simple context injection.

If you’re building an extension, start with a skill. Only reach for the plugin system if you need to add tools or modify permissions, not just add instructions.

---

Reference: This chapter draws on Xiao Tan’s (@tvytlx) Claude Code Architecture Deep Dive V2.0 report.