Reusable Claude Code extensions solve different problems. Put durable facts in always-on project context, put a repeatable procedure in a Skill, delegate a focused investigation or implementation task to a subagent, use Model Context Protocol (MCP) for an external capability, and package a coherent distribution of extensions as a plugin. The right choice is governed by invocation, context isolation, tools, and distribution—not by which feature seems most powerful.
Architecture Overview: Select by Responsibility
Claude Code offers several extension mechanisms, including project memory, Skills, subagents, MCP connections, hooks, and plugins. The extension overview is a useful starting map because it shows that these mechanisms are complementary rather than interchangeable.
Begin with four questions:
- Must this guidance be present in every relevant session?
- Does the work need a reusable step-by-step procedure or a separately scoped worker?
- Does it require an external system or a distributable package of related configuration?
- Which files, commands, network access, and credentials should be available?
The answer should minimize ambient context and authority. Reuse is valuable only when it remains understandable and safe to maintain.
Always-On Context and Rules
Use CLAUDE.md and targeted rules for stable repository guidance: coding standards, architecture boundaries, test commands, and non-negotiable safety constraints. Claude Code documents these as memory and rule mechanisms that apply project instructions at appropriate scope.
Always-on context is a poor fit for lengthy procedures, specialist reference material, secrets, or advice relevant to only one task family. Excess detail competes for attention on every request and creates more opportunities for stale or conflicting instructions. Keep the baseline concise; link or package specialised material elsewhere.
Skills: Reusable, On-Demand Procedures
Claude Code Skills provide reusable instructions that can be invoked for a focused task. Claude Code loads a Skill's description at session start, can auto-invoke the Skill when the request matches, and defers the full Skill content until it is used. A Skill is therefore suitable when the same procedure, quality checklist, or domain workflow should be available on demand without placing all of its instructions in every conversation.
Good Skill boundaries are procedural: “prepare a release note,” “run the approved security review,” or “generate a report from this repository's sources.” Define inputs, required checks, safe defaults, and expected artifacts. The documented disable-model-invocation: true setting makes a Skill user-invocable only; user-invocable: false makes it Claude-only. When a shared Skill cannot be edited, skillOverrides can use user-invocable-only or off to control visibility and invocation. Do not write a Skill as an all-purpose agent biography or use it to smuggle broad permissions into unrelated work.
Subagents: Isolated Specialists
Use a subagent when a task benefits from a focused context, distinct instructions, or restricted tool access. Claude Code subagents can be defined with a purpose, tools, permissions, and model selection, allowing the main session to delegate an isolated piece of work and receive a result.
Choose a subagent for work that has a clear handoff: investigate a dependency, review a limited change set, or carry out a bounded transformation. State what it may change, what evidence it should return, and when it must stop for approval. Context isolation reduces distraction, but it also means the handoff must include the facts and constraints the worker needs.
This Claude Code extension model is distinct from Claude Agent SDK runtime orchestration. In an SDK application, the developer designs an application-controlled agent loop and runtime behavior. In Claude Code, a subagent is a configured development-workflow worker. Do not transfer runtime assumptions, session management, or production execution contracts from one layer to the other.
MCP Connections and Plugins
Use MCP when Claude Code needs to connect to an external tool, data source, or service through a protocol-defined integration. The MCP host controls connection permissions, consent requirements, user authorization decisions, and security boundaries; clients negotiate capabilities with their server connections; and servers expose their declared capabilities subject to security constraints. A connection does not automatically grant trust or broad credentials.
Use a plugin when several related Claude Code extensions should be installed and distributed together. Plugins can group capabilities such as commands, agents, Skills, hooks, and MCP configuration, making shared workflows easier to publish and manage.
Package only cohesive behavior. A plugin should make ownership and updates clearer, not become a miscellaneous archive of powerful scripts and connections. Review every packaged component for secret handling, command execution, network access, and upgrade compatibility.
A Selection Framework
| Need | Preferred mechanism | Why |
|---|---|---|
| Stable project conventions | CLAUDE.md or rules | Relevant guidance is available without a separate invocation. |
| Repeatable specialist procedure | Skill | Reusable on demand without permanent context overhead. |
| Focused task with its own context or tools | Subagent | Creates a clear scope and handoff. |
| Access to an external system | MCP | Uses a defined client-server integration boundary. |
| Shared distribution of related extensions | Plugin | Packages coherent configuration and workflows. |
Before publishing a reusable extension, test it in a non-sensitive repository, review its effective permissions, and document its expected inputs and side effects. A reusable workflow that runs commands or touches external systems must retain the same approval and least-privilege controls as a one-off workflow.
Common Mistakes
Do not place every instruction in CLAUDE.md, or create a subagent for every short procedure. Do not use an MCP connection merely to organize local guidance, and do not call a plugin a security boundary. Each mechanism may make a workflow more convenient, but permission policy and external-system authorization remain separate controls.
Skills and subagents guide and perform work; they are not deterministic lifecycle enforcement. If a control must run at a particular event or in continuous integration (CI), design that automation separately.
Conclusion
The cleanest Claude Code extension architecture gives each mechanism one job: durable context, on-demand procedure, isolated worker, external integration, or distribution package. Selecting by responsibility keeps repositories understandable, limits unintended authority, and avoids conflating development configuration with production agent runtime design.
Authoritative Sources
- Extend Claude Code
- How Claude remembers your project
- Extend Claude with skills
- Create custom subagents
- Model Context Protocol architecture