Claude Code has transformed from an internal Anthropic prototype to a $500M+ ARR enterprise-ready AI coding assistant in less than a year. Released publicly in February 2025 and reaching general availability in May 2025, it represents a sophisticated agentic coding tool that operates directly in terminals, IDEs, and web browsers. This guide provides comprehensive technical details on its four core extensibility features: sub agents, CLAUDE.md files, MCP servers, and Skills.
Sub agents are independent AI instances with isolated context windows that Claude Code delegates specialized tasks to. They transform Claude from a single assistant into a coordinated team of domain experts, enabling parallel execution and context preservation.
Each sub agent operates with three critical components: a separate 200K token context window isolated from the main thread, a custom system prompt defined in Markdown with YAML frontmatter, and configurable tool permissions that control access to Claude Code's internal capabilities and MCP servers. Sub agents are defined as Markdown files stored in .claude/agents/ (project-specific) or ~/.claude/agents/ (user-level global), with project agents taking precedence over global ones.
The basic structure looks like this:
---
name: test-runner
description: Use proactively to run tests and fix failures
tools: Read, Write, Edit, Bash, Grep
model: sonnet
---
You are a test automation expert. When you see code changes,
proactively run the appropriate tests. If tests fail, analyze
the failures and fix them while preserving the original test intent.Sub agents can be triggered two ways: automatic delegation where Claude intelligently selects agents based on context analysis and task classification, or explicit invocation where users directly request a specific agent. Claude pays a 20,000 token overhead per sub agent invocation for context loading, meaning sessions with multiple sub agents consume 3-4x more tokens than single-threaded operations.
Sub agents run with a critical architectural constraint: they cannot spawn other sub agents. This is by design, not a bug. Only one level of delegation exists, maintaining clear role separation where the main Claude instance orchestrates and sub agents execute specialized tasks. When a sub agent tries to use the Task tool, it receives nothing back.
Sub agents can read and be trained on project CLAUDE.md files, but this must be explicitly mentioned in the sub agent's system prompt. The pattern looks like:
---
name: code-reviewer
description: Expert code review specialist
---
You are a specialized code reviewer. You have been trained on this
project's CLAUDE.md file and understand all architectural patterns
and best practices defined there. Always check code against these standards.Without explicit reference, sub agents start with a "clean slate" each invocation and may add latency gathering required context.
The recommended approach uses the interactive CLI wizard:
/agents
# Choose "Create New Agent"
# Select scope: Project-level or User-level
# Configure name, description, system prompt, and tools
# Press 'e' to edit system prompt in editorFor manual creation, place files directly in agent directories. Critically important: write specific, action-oriented descriptions that include trigger terms. Compare these approaches:
- Bad: "Data analysis" (too vague)
- Good: "MUST BE USED for ExUnit testing and test file generation. Expert in test patterns. Use proactively after code changes."
Anthropic recommends generating initial sub agents with Claude's help, then iterating to personalize them.
Maximum 10 concurrent sub agents can execute simultaneously, with additional tasks queuing in batches. Each sub agent costs at minimum 20,000 tokens even for simple responses, rapidly exhausting usage limits. Sub agents cannot see each other's work directly—all communication routes through the main thread, adding latency and token overhead.
Results can be truncated or summarized when transferred back, potentially losing critical details like stack traces. No progress visibility exists during execution; sub agents operate as black boxes until completion. Configuration drift occurs as Claude's base model updates, requiring regular testing of sub agent behavior.
For resource management, running multiple sub agents simultaneously strains system resources. Context isolation prevents context pollution but requires file-based communication or main thread coordination for sub agents to share information.
Use sub agents for context preservation (preventing main conversation clutter), task specialization (dedicated experts for code review, testing, security), parallel execution (multiple agents working simultaneously), and workflow automation (reusable, consistent procedures).
Avoid sub agents for working with 2-3 specific files, simple sequential operations under 30 seconds, or when token cost matters more than speed. For these cases, stay in the main thread.
CLAUDE.md files are special Markdown configuration files that Claude Code automatically reads to gain project-specific context. They serve as a "constitution" for the AI assistant, providing persistent instructions that persist throughout coding sessions.
Claude Code operates with a strict instruction hierarchy where CLAUDE.md instructions are treated as immutable system rules with superior adherence over user prompts. Files are automatically loaded at session start and prepended to every prompt, remaining in context throughout the session. They are not re-read during the session unless you start fresh with /clear or use /memory to reload.
Claude Code supports four memory locations in hierarchical order:
- Enterprise policy (
/Library/Application Support/ClaudeCode/CLAUDE.mdon macOS) - Organization-wide instructions - User memory (
~/.claude/CLAUDE.md) - Personal preferences across all projects - Project memory (
./CLAUDE.md) - Team-shared project instructions - Subdirectory memory (
./subdirectory/CLAUDE.md) - Context-specific guidance
Files higher in the hierarchy take precedence. When working on a file deep in the structure, all applicable CLAUDE.md files in the hierarchy load, from user global down to the specific subdirectory.
CLAUDE.md uses standard Markdown with optional XML-style tags for organization:
<system_context>
Full-stack SaaS application using Next.js 14, TypeScript, Prisma, PostgreSQL.
Multi-tenant architecture with row-level security.
</system_context>
<file_map>
- `app/` - Next.js 14 App Router pages and API routes
- `components/` - Reusable React components
- `lib/` - Utilities, API clients, database client
</file_map>
<critical_notes>
## MISSION CRITICAL RULES
1. **NEVER use `any` types** - Request explicit user approval if necessary
2. **NEVER commit to main** - Always use feature branches
3. **ALWAYS write tests** - No PR without test coverage
</critical_notes>
<paved_path>
## Architecture Pattern (MUST FOLLOW)
1. Define types in `types/`
2. Create database schema in `prisma/schema.prisma`
3. Build service layer in `lib/services/`
4. Create API routes in `app/api/`
5. Build UI components in `components/`
6. Write tests in `tests/`
</paved_path>
<commands>
- `npm run dev` - Start development server
- `npm run build` - Production build
- `npm test` - Run all tests
</commands>Essential content includes tech stack and versions, project architecture overview, directory structure, development commands, code style guidelines, testing requirements, git workflow conventions, and file boundaries (what to/not to edit).
CLAUDE.md files support imports using @path/to/import syntax:
# CLAUDE.md
See @README.md for project overview and @package.json for available commands.
@docs/git-instructions.md
@docs/coding-standards.md
@~/.claude/my-project-instructions.mdThis enables modular organization and personal preference injection. Maximum import depth is 5 hops for recursive imports.
Use /init in a Claude Code session to automatically generate a boilerplate CLAUDE.md based on project analysis. During sessions, press # to add instructions that automatically incorporate into the relevant CLAUDE.md file. Use /memory to open the appropriate CLAUDE.md in your system editor for extensive edits.
Respect the token budget: CLAUDE.md content is prepended to every prompt, consuming context tokens. Use short declarative bullet points, trim redundancy, and include only essential information. Target 100-200 lines per file as a guideline.
Front-load critical information by placing the most important rules at the top. Use formatting for emphasis: **IMPORTANT**, **YOU MUST**, **NEVER**.
Provide examples showing good vs bad patterns. LLMs learn exceptionally well from concrete code samples:
<example>
// Good: Proper typing and documentation
async function getUser(id: string): Promise<User> {
return await db.users.findUnique({ where: { id } });
}
// Bad: Missing types
async function getUser(id) {
return await db.users.findUnique({ where: { id } });
}
</example>Use pointers to save context by referencing example files rather than duplicating code:
<example>
For form validation patterns: @app/features/auth/LoginForm.tsx, search:`validateForm`
</example>Version control everything: Commit CLAUDE.md files to git, review changes in PRs, and update after major project changes.
Large CLAUDE.md files consume significant context, reducing available space for conversation. Performance warnings may appear, but front-loading complete context is often more effective than having Claude read files that may "poison" context.
Instruction bleeding occurs without clear organization—use XML tags or clear section headers to separate functional areas. Too many rules can confuse Claude; regularly review and consolidate.
CLAUDE.local.md is deprecated—use imports from home directory instead: @~/.claude/personal-preferences.md. Changes during a session require /clear or /memory to reload. Never include secrets or credentials; use environment variables for sensitive data.
The Model Context Protocol (MCP) is an open-source standard introduced by Anthropic in November 2024 that provides a universal interface for connecting AI assistants to external data sources, tools, and services. Claude Code fully supports MCP integration through a client-server architecture.
MCP uses a client-server model where Claude Code acts as an MCP host with built-in client capabilities that maintain 1:1 stateful connections with MCP servers. Communication occurs over JSON-RPC 2.0 with three message types: requests (bidirectional with responses), responses (results or errors), and notifications (one-way, no response). Transport methods include stdio (standard input/output), HTTP, SSE (Server-Sent Events), and WebSockets.
MCP servers expose three core primitives:
- Resources: Read-only data/content (e.g.,
docs://api/reference, file contents) - Tools: Executable functions the LLM can invoke with user approval (e.g., query_database, send_notification)
- Prompts: Pre-written templates exposed as slash commands in Claude Code
During initialization, clients and servers perform a handshake to negotiate capabilities, ensuring both parties understand supported functionality while maintaining protocol extensibility.
When Claude Code starts, it connects to configured MCP servers and discovers their capabilities. Users interact through natural language—Claude autonomously determines when to use MCP tools based on context. Claude requests permission, executes tools through MCP servers, receives results, and integrates them into context for generating responses.
Resources appear when typing @ and are referenced as @server:protocol://resource/path. Tools automatically trigger when relevant, appearing in the "Search and tools" menu. Prompts appear as slash commands: /mcp__servername__promptname.
Three configuration scopes exist: local (default, current project only), project (shared via .mcp.json in project root), and user (across all projects, formerly "global").
Method 1: CLI Wizard (Recommended)
# Add server with wizard
claude mcp add github --scope user
# Add with environment variables
claude mcp add clickup \
--env CLICKUP_API_KEY=YOUR_KEY \
--env CLICKUP_TEAM_ID=YOUR_ID \
-- npx -y @hauptsache.net/clickup-mcp
# List servers
claude mcp list
# Test connection
claude mcp get [name]Method 2: Direct Config File
Configuration file locations vary by platform:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.claude.json
Example configuration:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
}
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "postgresql://..."
}
}
}
}Environment variable substitution is supported: ${VAR} expands to environment variable VAR, while ${VAR:-default} uses VAR if set or the default value otherwise.
Method 3: Project-Scoped
Create .mcp.json at project root for team-shared configurations that version control alongside code.
The ecosystem includes 200+ MCP servers across official and community sources:
Official Anthropic servers: Filesystem (secure file operations), Fetch (web content), Git/GitHub (repository management), Google Drive, Slack, Memory (knowledge graph), Sequential Thinking, Postgres, Puppeteer (browser automation).
Popular third-party servers: Database systems (PostgreSQL, MySQL, MongoDB, Redis, Supabase), development tools (Kubernetes, Docker, Linear, Jira, Asana), APIs (Stripe, Notion, Confluence), communication (Discord, Teams, email), cloud platforms (AWS, Azure, GCP), and specialized tools (Apify web scraping, Playwright automation, financial data, blockchain).
Discovery resources include https://modelcontextprotocol.io/examples, https://github.com/modelcontextprotocol/servers, https://mcp.so, and https://smithery.ai.
Claude Code supports unlimited simultaneous MCP server connections. Each server maintains an independent 1:1 connection, and Claude automatically selects appropriate servers based on user intent:
{
"mcpServers": {
"github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "token" } },
"slack": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-slack"], "env": { "SLACK_BOT_TOKEN": "token" } },
"postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres"], "env": { "DATABASE_URL": "url" } }
}
}This enables complex workflows: query GitHub for PR details, analyze code patterns, store insights in PostgreSQL, post summary to Slack—all in a single conversation.
MCP servers can be built in Python (official SDK mcp[cli]), TypeScript/JavaScript (SDK @modelcontextprotocol/sdk), C#/.NET (Microsoft SDK), Go, or PHP (official SDK with PHP Foundation).
Python example:
from mcp.server.fastmcp import FastMCP
import httpx
mcp = FastMCP("my-server")
@mcp.tool()
async def get_weather(city: str) -> str:
"""Get current weather for a city"""
response = await httpx.get(f"https://api.weather.gov/...")
return response.json()
@mcp.resource("config://settings")
async def get_settings() -> str:
"""Expose configuration settings"""
return "Settings content here"
if __name__ == "__main__":
mcp.run(transport='stdio')Critical development rule: NEVER write to stdout in stdio-based servers. This breaks the JSON-RPC protocol. Use stderr or file-based logging exclusively.
Test servers using MCP Inspector: npx @modelcontextprotocol/inspector uv run my-server.py. This provides a GUI for testing tool calls, viewing resources, checking prompts, and debugging responses.
MCP has significant security risks that demand attention. Command injection vulnerabilities exist in many servers, with RCE (Remote Code Execution) risks present. Security research from April 2025 identified fundamental issues including authentication weaknesses, prompt injection attacks, token/credential exposure, excessive permissions, and insufficient sandboxing.
Local MCP servers execute with the same permissions as the host process, accessing host filesystem and network without restrictions. Configuration files store credentials in plaintext. OAuth token theft enables server impersonation. Malicious prompts can trick models into unsafe tool calls.
Security best practices: Use containerized MCP servers (Docker MCP Toolkit), implement network isolation and resource limits, enable cryptographic verification, use MCP Gateway for security enforcement, regular audits, secret scanning and rotation, strict input validation, read-only mode where possible, and verify server sources before installation.
Protocol limitations: No built-in authentication guidance leads to inconsistent implementations. LLM reliability decreases with many available tools—too many tools confuse the model. Large MCP outputs consume context tokens (default limit: 25,000 tokens per tool output).
Configuration gotchas: Absolute paths required (no relative paths), JSON syntax errors break entire configuration, must restart Claude Code after changes, Windows requires cmd /c wrapper for npx. Check logs at ~/Library/Logs/Claude/mcp*.log for debugging.
The MCP ecosystem is rapidly evolving with adoption from major players, but security maturity lags behind functional capabilities. Proceed with comprehensive security planning while embracing powerful integration capabilities.
Claude Skills (officially "Agent Skills") package expertise, instructions, scripts, and resources into discoverable, reusable capabilities that Claude loads on-demand. They work across Claude.ai, Claude Code, and the Claude API using a progressive disclosure pattern for efficiency.
Skills use a three-tier loading system to optimize token usage:
- Tier 1 (Startup): Only metadata (name + description) loaded into system prompt (~30-50 tokens per skill)
- Tier 2 (Triggered): Full SKILL.md file loaded when relevant (~2,000 tokens typical)
- Tier 3 (As-needed): Additional referenced files and scripts loaded only when required
File structure:
skill-name/
├── SKILL.md # Required: YAML frontmatter + instructions
├── scripts/ # Optional: Python/JS/bash scripts
├── templates/ # Optional: Document templates
├── resources/ # Optional: Data files, examples
└── tests/ # Optional: Validation tests
SKILL.md format:
---
name: skill-name
description: Brief description of what this does and when to use it
allowed-tools: [bash, python] # Claude Code only
---
# Skill Name
## Instructions
Step-by-step guidance
## Examples
Concrete usage examples
## Guidelines
Best practices and edge casesSkills run in Claude's secure sandboxed code execution container at /mnt/skills/{skill-name}/ (API/Web) or ~/.claude/skills/ and .claude/skills/ (Claude Code).
At session start, Claude scans available skill directories, reads YAML frontmatter (30-50 tokens each), and loads metadata into system prompt. Full content remains on disk. During conversation, when Claude detects relevant requests, it invokes bash tool to read SKILL.md, loads full instructions (~2,000 tokens), and may subsequently read referenced files as needed.
Skills are model-invoked, not manually triggered like slash commands. Claude autonomously decides when to use skills based on semantic similarity matching against descriptions and context relevance scoring. Users see skills being loaded in Claude's chain-of-thought reasoning.
What persists: Skill definitions remain installed between sessions, all files persist on disk, metadata always loads at session start.
What does NOT persist: Conversation state (each conversation is independent), container state (API/Claude.ai runs isolated containers per request), loaded context (full skill content reloads each trigger), execution state (no runtime state between sessions).
Official documentation confirms: "Skills in Claude and the API operate in Claude's secure sandboxed environment with no data persistence between sessions."
Platform-specific behavior varies: Claude.ai Web keeps toggled skills enabled across all chats but requires re-triggering per conversation. Claude Code discovers skills at startup from filesystem; changes require restart. API specifies skills per request in container parameter with containers persisting only for conversation duration.
Yes, multiple skills can be used simultaneously. The API enforces a hard limit of 8 skills per request. Claude.ai and Claude Code have no stated limit, though practical limits exist based on token efficiency.
Claude automatically composes multiple skills in a single task without manual orchestration:
response = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{"type": "anthropic", "skill_id": "pptx", "version": "latest"},
{"type": "custom", "skill_id": "skill_01AbCd...", "version": "latest"}
]
},
messages=[{"role": "user", "content": "Create financial model and presentation"}]
)Skills cannot be explicitly "unloaded" mid-session, but you control availability through several methods:
Claude.ai: Toggle skills on/off in Settings → Capabilities → Skills. Disabled skills won't be available; changes apply to future conversations.
Claude Code: Remove skill directory (rm -rf ~/.claude/skills/my-skill) and restart Claude Code. Skills not in filesystem won't be discovered.
API: Don't include unwanted skills in the container.skills array. Each request specifies exactly which skills to make available.
Skill metadata always loads at startup (unavoidable if skill exists), but full content only loads when triggered. With 200K context windows, you can have 100+ skills before token overhead becomes significant.
Method 1: Using Claude (No-Code)
- Enable "skill-creator" skill in Settings → Capabilities
- Start new chat: "Help me create a skill for [workflow]"
- Claude asks questions, generates SKILL.md and structure
- Download as ZIP, upload via Settings → Capabilities
Method 2: Manual Creation
mkdir -p ~/.claude/skills/my-skill
cat > ~/.claude/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Clear description of what this does and when to use it
---
# My Skill
## Instructions
1. Step one
2. Step two
## Examples
- Example 1
## Best Practices
- Guideline 1
EOF
# For Claude Code: Restart to load
# For Claude.ai: ZIP and uploadMethod 3: API Upload
import anthropic
from pathlib import Path
client = anthropic.Anthropic()
skill_files = [
{"path": "SKILL.md", "content": Path("SKILL.md").read_bytes()},
{"path": "scripts/helper.py", "content": Path("helper.py").read_bytes()}
]
skill = client.beta.skills.create(files=skill_files)Container environment constraints: No network access (skills cannot make external API calls or access internet), no runtime package installation (cannot pip install during execution), isolated environment (each API request gets fresh container), pre-configured dependencies only.
Size and structure limits: Maximum skill upload size 8MB (all files combined), maximum 8 skills per API request, name field 64 characters max (lowercase, numbers, hyphens), description field 1024 characters max.
Platform-specific issues: Built-in document skills (docx, xlsx, pptx, pdf) that work in Claude.ai are not automatically available in Claude Code—must install as plugin. Path differences and lack of centralized admin management for organizations exist.
Skills don't trigger: Vague descriptions cause this. Compare "Data analysis" (bad) vs "Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format" (good).
YAML parsing errors: Invalid syntax (tabs, missing dashes, incorrect indentation) breaks skills. Verify frontmatter structure carefully.
Context compaction issues: After hitting context limits, Claude Code may become "dumber," losing track of examined files and repeating earlier mistakes.
Security risks: Skills execute arbitrary code in Claude's environment. Only install from trusted sources, audit contents before enabling, never hardcode sensitive information, review scripts for malicious code, and check for instructions connecting to untrusted external sources.
Anthropic-provided: xlsx (Excel), docx (Word), pptx (PowerPoint), pdf (PDF handling)—all included in paid plans for Claude.ai, must install as plugin for Claude Code.
Community/Example: algorithmic-art, canvas-design, artifacts-builder, mcp-server, webapp-testing, brand-guidelines, internal-comms, skill-creator.
Third-party collections: obra/superpowers (20+ battle-tested skills), BehiSecc/awesome-claude-skills, michalparkola/tapestry-skills-for-claude-code.
Partners: Notion (documentation integration), Box (file transformation), Canva (design workflows).
Combining all four features—sub agents, CLAUDE.md files, MCP servers, and Skills—creates a powerful, context-aware development environment. Here's how to architect an effective setup.
Step 1: Initialize project memory
cd your-project
claude
/initThis generates a boilerplate CLAUDE.md. Edit it to include tech stack, architecture overview, directory structure, development commands, code style guidelines, testing requirements, git workflow, and file boundaries.
Step 2: Configure MCP servers
Create .mcp.json in project root for team-shared integrations:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "${DATABASE_URL}"
}
}
}
}Add .env file with actual credentials (gitignored). Test connections: /mcp command shows connection status.
Step 3: Create project sub agents
/agents
# Create specialized agents:
# - test-runner: Proactively run and fix tests
# - code-reviewer: Review changes against standards
# - security-auditor: Check for vulnerabilities
# - doc-writer: Update documentationStore in .claude/agents/ and commit to version control for team sharing.
Step 4: Set up Skills
For Claude Code, install plugins:
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skillsCreate project-specific skills in .claude/skills/ for repeatable workflows (e.g., release process, deployment checklist, brand compliance).
CLAUDE.md as foundation: This provides base context loaded into every prompt. Include high-level architecture, coding standards, workflow conventions. Keep root CLAUDE.md to 100-200 lines; use nested CLAUDE.md files in subdirectories for context-specific details.
MCP servers for external data: Use when you need access outside the codebase—GitHub PRs, Slack notifications, database queries, API interactions. MCP provides the "senses and actuators" for Claude to interact with external systems.
Sub agents for specialization: Deploy when you need focused expertise (testing, security, documentation) or parallel execution (multiple components simultaneously). Sub agents consume additional tokens but preserve main context and enable task delegation.
Skills for procedures: Package repeatable workflows as Skills when you perform the same type of task frequently across projects. Skills auto-trigger based on task similarity and benefit from progressive disclosure (minimal token cost until needed).
project/
├── .claude/
│ ├── agents/
│ │ ├── test-runner.md
│ │ ├── code-reviewer.md
│ │ └── security-auditor.md
│ ├── skills/
│ │ ├── release-process/
│ │ │ ├── SKILL.md
│ │ │ └── scripts/
│ │ └── brand-compliance/
│ │ ├── SKILL.md
│ │ └── templates/
│ └── commands/
│ └── review.md
├── .mcp.json
├── CLAUDE.md
├── frontend/
│ └── CLAUDE.md
├── backend/
│ └── CLAUDE.md
└── docs/
└── architecture.md
Root CLAUDE.md references subdirectory contexts:
# CLAUDE.md (root)
<system_context>
Full-stack application. See subdirectories for specific context.
</system_context>
<architecture>
@docs/architecture.md
</architecture>
<module_contexts>
Frontend: @frontend/CLAUDE.md
Backend: @backend/CLAUDE.md
</module_contexts>1. Specification phase: User requests new feature. Claude consults root CLAUDE.md for architecture patterns, invokes planner sub agent to analyze requirements and create implementation plan.
2. Design phase: Architect sub agent (with backend/CLAUDE.md context) designs database schema and API structure. Writes Architecture Decision Record (ADR).
3. Implementation phase: Main Claude implements code following paved path from CLAUDE.md. Uses GitHub MCP server to check related PRs. Writes implementation following style guidelines.
4. Testing phase: Test-runner sub agent proactively runs test suite after each change. Fixes failures while preserving test intent.
5. Review phase: Code-reviewer sub agent (trained on CLAUDE.md standards) reviews changes against project conventions, security patterns, accessibility requirements.
6. Documentation phase: Release-process skill (auto-triggered by "prepare release") generates changelog, updates version numbers, creates release notes, using brand-compliance skill for formatting.
7. Deployment phase: Uses Slack MCP server to notify team, Linear MCP server to update ticket status, commits with conventional commit message.
Token exhaustion: Sub agents cost 20K tokens each; multiple invocations drain context quickly. Solution: Use sub agents selectively for complex tasks requiring specialization. For simple operations, stay in main thread.
Configuration complexity: Managing multiple CLAUDE.md files, MCP servers, and sub agents creates maintenance burden. Solution: Start minimal. Add one feature at a time. Measure effectiveness before expanding.
Context pollution: Loading too much into CLAUDE.md or having too many skills active simultaneously. Solution: Keep CLAUDE.md files lean (100-200 lines), use nested files for modularity, leverage progressive disclosure of Skills.
Security vulnerabilities: MCP servers with excessive permissions, sub agents executing untrusted code, Skills from unknown sources. Solution: Audit all configurations, use principle of least privilege, implement containerization where possible, regular security reviews.
Team coordination: Different team members with different configurations producing inconsistent results. Solution: Version control all project configurations (.claude/, .mcp.json, CLAUDE.md), document setup in README, include setup validation in onboarding.
Over-engineering: Creating sub agents, Skills, and MCP servers for every possible scenario. Solution: Follow YAGNI (You Aren't Gonna Need It). Create extensions only when you've performed a task manually 3+ times and see clear repeatability.
1. Progressive enhancement: Start with root CLAUDE.md only. Add MCP servers when you need external integrations. Create sub agents when you have clear specialization needs. Package Skills when workflows become repetitive.
2. Clear boundaries: CLAUDE.md for "what and how" (standards, patterns, workflows). MCP servers for "where" (external data sources, APIs). Sub agents for "who" (specialized expertise). Skills for "when" (reusable procedures).
3. Token awareness: Every feature costs tokens. CLAUDE.md prepends to every prompt. Sub agents cost 20K minimum. Skills cost 30-50 until triggered. MCP outputs consume context. Design with token budget in mind.
4. Security first: Audit all code before installation. Use environment variables for credentials. Implement principle of least privilege. Regular security reviews. Monitor for unusual behavior.
5. Version control everything: Commit .claude/ directory (agents, skills, commands), CLAUDE.md files, .mcp.json configuration. Review changes in PRs. Document rationale for configurations.
6. Test configurations: Verify sub agents work as expected after creation. Test MCP server connections. Validate Skills trigger correctly. Check CLAUDE.md instructions produce desired behavior.
7. Iterate based on usage: Track what features provide value. Remove unused sub agents, Skills, MCP servers. Consolidate overlapping configurations. Refine based on team feedback.
Use this matrix to decide which features to implement:
| Need | Feature | Why |
|---|---|---|
| Project conventions, coding standards | CLAUDE.md (root) | Always-on context, zero token cost until session start |
| Module-specific context | CLAUDE.md (nested) | Contextual guidance without polluting root context |
| Access external APIs, databases, services | MCP servers | Bidirectional integration with live systems |
| Specialized expertise (testing, security, review) | Sub agents | Isolated context, parallel execution, focused prompts |
| Repeatable procedures across projects | Skills | Progressive disclosure, auto-triggering, portable |
| Team-wide consistency | Version controlled configs | Shared standards, reproducible environments |
Hybrid orchestration: Main thread analyzes request → Task tool reads files in parallel → Architect sub agent designs solution → Task tool implements in parallel → Test-runner sub agent validates → Main thread coordinates git operations.
Context preservation: Use sub agents early in conversations for complex problems to prevent main context exhaustion. Telling Claude "use subagents to verify details" preserves context availability for longer sessions.
Skill composition: Multiple skills automatically compose. Example: "Create financial report" triggers xlsx skill → brand-guidelines skill → pdf skill sequentially, all coordinated by Claude.
MCP chaining: Query GitHub MCP for PR → Analyze with Claude → Store insights in Postgres MCP → Notify via Slack MCP. Single conversation, multiple integrations.
Dynamic tool selection: With many MCP tools available, use MCP toolsets feature to limit scope and improve LLM reliability. Too many tools confuse the model.
Claude Code represents a paradigm shift in AI-assisted development, evolving from a simple coding assistant to a comprehensive agentic platform. The four extensibility features—sub agents, CLAUDE.md files, MCP servers, and Skills—provide complementary capabilities that, when combined thoughtfully, create a powerful development environment.
Start simple: Initialize with root CLAUDE.md defining project standards. Add features progressively as needs emerge. Measure effectiveness at each step. Focus on value: Every feature has a token cost and maintenance burden. Only implement what provides clear benefit. Remove what doesn't. Prioritize security: Audit all external code, use least privilege, version control everything, regular reviews. Iterate continuously: Configurations that work today may need adjustment as your project and team evolve.
The Claude Code ecosystem is rapidly maturing but still evolving. Expect breaking changes in MCP protocol, refinements to Skills API, enhancements to sub agent capabilities. Stay current with official documentation, engage with community resources, and contribute learnings back to the ecosystem. Most importantly, use these powerful tools to focus on what matters: building exceptional software.