8 min readJust now

–

Press enter or click to view image in full size

Claude Code isn’t just an AI you prompt to write code, it’s a highly configurable tool that adapts to your workflow. Its real power comes from its configuration mechanisms: structured ways to define project context, automate workflows, delegate tasks, and connect to external tools. From CLAUDE.md to Skills, Commands, Subagents, MCP Servers, Hooks, and Plugins, each configuration type plays a specific role in shaping how Claude interacts with your project.

In this guide, we’ll break down the seven key configurations, explain when and how to use each, and show you how to combine them effectively. Master these, and Claude Code transforms from a generic assistant into a tailored coding partner that understands your project, your team, and your workflow.

The Seven Configuration Types at a Glance

┌─────────────┬──────────────────┬─────────────┬────────────────────────┐│ Config      │ Trigger          │ Token Cost  │ Best For               │├─────────────┼──────────────────┼─────────────┼────────────────────────┤│ CLAUDE.md   │ Always           │ Session     │ Project identity       │├─────────────┼──────────────────┼─────────────┼────────────────────────┤│ Skills      │ Auto             │ On-demand   │ Task patterns          │├─────────────┼──────────────────┼─────────────┼────────────────────────┤│ Commands    │ Manual           │ On-demand   │ Explicit workflows     │├─────────────┼──────────────────┼─────────────┼────────────────────────┤│ Subagents   │ Auto/manual      │ Separate    │ Specialized tasks      │├─────────────┼──────────────────┼─────────────┼────────────────────────┤│ MCP Servers │ When needed      │ On-demand   │ External tools & APIs  │├─────────────┼──────────────────┼─────────────┼────────────────────────┤│ Hooks.      │ Lifecycle events │ On-demand   │ External tools & APIs  │├─────────────┼──────────────────┼─────────────┼────────────────────────┤│ Plugins     │ Toggle           │ Varies      │ Shareable bundles      │└─────────────┴──────────────────┴─────────────┴────────────────────────┘

CLAUDE.md: Your project’s identity card

What it is: A markdown file at your project root that Claude reads and add to Claude Code’s context every time.

When to use it:

• Define your tech stack and versions
• Establish coding conventions
• List common commands
• Brief architecture overview
• Anything Claude needs to know every single time

Example:

# CLAUDE.md## StackPython 3.12, FastAPI, SQLAlchemy (async), Pydantic v2## Commands- Tests: `pytest -xvs`- Lint: `ruff check . && ruff format .`- Run: `uvicorn app.main:app --reload`## Conventions- Repository pattern for data access- Inject AsyncSession via FastAPI Depends- All functions require type hints

Key principle: Keep it concise. This file is always loaded into the session context, so large content increases total context size.

Official documentation link: Using CLAUDE.md files

Skills: Auto-Triggered Expertise

What it is: Skills are folders containing instructions, scripts, and resources that Claude loads automatically when relevant to a task. Unlike CLAUDE.md, which is always loaded, Skills only activate when needed, keeping Claude efficient.

When to use it:

• File-type specific patterns (e.g., “when creating repository classes…”)
• Detailed workflows too long for CLAUDE.md
• Recurring patterns you keep forgetting to mention
• Large reference material with examples

Official documentation notes:

*“Claude scans available skills to find relevant matches. When one matches, it loads only the minimal information and files needed — keeping Claude fast while accessing specialized expertise.” — *Claude Skills Blog

Example:

# .claude/skills/api-endpoint/SKILL.md---name: fastapi-endpoint-generatordescription: Use when creating new FastAPI endpoints or routes---## StructureCreate these files for each endpoint:1. Router: `/drivers/api/v1/{resource}/router.py`2. Schemas: `/drivers/api/v1/{resource}/schema.py`3. Domain entity: `/domain/entities/v1/{entity_name}.py`4. Use case: `usecases/{resource_folder}/{action}_use_case.py`5. Repository: `adapters/repositories/{resource}_repositories/sqlalchemy-{resource}_repository.py`## Patterns- Routers handle HTTP concerns only- Entities represent core domain objects with a unique identity and encapsulate business rules and behaviors related to that identity- Use cases coordinate business logic through domain objects and ports.- Repositories handle data access- Always return Pydantic models from routes## Template[... 50+ lines of detailed templates and examples ...]

Key principle: If you keep saying “remember to do X when doing Y” then make it a skill.

Commands: Manual Workflows

What it is: Markdown files defined in .claude/commands/ (project‑specific) or ~/.claude/commands/ (personal), which become slash‑commands you invoke explicitly (e.g. /review).

When to use it:

• Code review checklists
• Deployment procedures
• Scaffolding new components
• Any workflow you want to control when it runs

Example:

# .claude/commands/review.md---description: Comprehensive code review---Review the current changes for:1. **Code Quality**   - Type hints on all functions   - No unused imports   - DRY principles applied2. **Security**   - No hardcoded secrets   - Input validation present   - SQL injection prevention3. **Tests**   - New functionality has tests   - Edge cases covered   - Mocks used appropriately

Usage:

bash

> /review

Pro tip: Commands support arguments with $1, $2, or $ARGUMENTS:

# .claude/commands/new-endpoint.mdCreate a complete FastAPI endpoint for $1 resource following our patterns.

> /new-endpoint users

Subagents: Specialized Task Delegation

What it is: Subagents are custom AI assistants in Claude Code, each with its own system prompt, context window, and controlled tool access. They are designed to handle specialized tasks — e.g. code reviews, security audits, test‑running, documentation analysis, etc

When to use it:

• Complex tasks requiring focused expertise
• Parallel workstreams (review while implementing)
• Keep main conversation clean (subagent context is separate)
• Domain-specific specialists (security, testing, frontend)

Creating subagents:

# Interactive creation/agents# Or create files directly# .claude/agents/code-reviewer.md (project)# ~/.claude/agents/code-reviewer.md (personal)

Example subagent:

# .claude/agents/security-reviewer.md---name: security-reviewerdescription: Use PROACTIVELY for security audits and vulnerability detectiontools: Read, Grep, Glob---You are a security specialist focusing on:- Authentication/authorization flaws- SQL injection, XSS, CSRF vulnerabilities  - Secrets in code- Dependency vulnerabilitiesFor each review:1. Scan for common vulnerability patterns2. Check auth flows3. Review input validation4. Report findings with severity levels

How Claude uses subagents:

• Auto-delegation — Claude routes tasks based on description field
• Explicit call — “Use the security-reviewer agent on the auth module”
• Built-in agents — Explore (codebase search), Plan (planning mode)

Key benefits:

• Separate context — Subagent work doesn’t pollute main conversation
• Specialized prompts — Deep expertise without bloating CLAUDE.md
• Tool restrictions — Limit what each agent can do (read-only reviewers)
• Reusable — Share across projects, bundle in plugins

Popular subagent types:

• Code Reviewer
• Security Auditor
• Tech Lead / Architect

Pro tip: Use directive language in descriptions: “Use PROACTIVELY for…” or “MUST BE USED when…” to ensure Claude delegates appropriately.

MCP Servers: External Tools & Data Sources

What it is: Model Context Protocol (MCP) is an open standard that connects Claude Code to external tools, APIs, and data sources.

When to use it:

• Access live documentation (Context7)
• Connect to services (GitHub, Jira, Slack, databases)
• Query internal APIs
• Fetch real-time data Claude doesn’t have

Configuration (**.mcp.json**** in project root):**

{  "mcpServers": {    "context7": {      "command": "npx",      "args": ["-y", "@context7/mcp-server"]    }  }}

How Claude uses MCP:

• Claude discovers available MCP tools automatically
• Calls them when relevant to your request
• You can also prompt explicitly: “Use context7 to get the latest FastAPI docs”

Popular MCP servers:

• Context7 — Live documentation lookup
• GitHub — PR reviews, issue management
• Postgres/SQLite — Database queries

Pro tip: Add instructions in CLAUDE.md to guide MCP usage:

## Tools- Use context7 for up-to-date library docs- Use github MCP for PR operations

Hooks: Deterministic Automation

What it is: User-defined shell commands that execute automatically at specific points in Claude Code’s lifecycle. Unlike other configuration types, hooks provide deterministic control — they always run, not relying on Claude to choose.

When to use it:

• Auto-format code after every edit
• Block modifications to sensitive files
• Log all executed commands for compliance
• Custom notifications when Claude needs input
• Run tests automatically after changes
• Enforce project-specific rules

Hook events:

• PreToolUse: Before tool calls (can block them)
• PostToolUse: After tool calls complete
• Notification: When Claude needs your attention
• Stop: When Claude stops working
• SubagentStop: When a subagent completes

Configuration (**/hooks**** or settings.json):**

{  "hooks": {    "PostToolUse": [      {        "matcher": "Edit|Write",        "hooks": [          {            "type": "command",            "command": "npx prettier --write \"$CLAUDE_PROJECT_DIR/$(jq -r '.tool_input.file_path')\""          }        ]      }    ]  }}

Example use cases:

Auto-format TypeScript after edits:

{  "hooks": {    "PostToolUse": [{      "matcher": "Edit|Write",      "hooks": [{        "type": "command",        "command": "jq -r '.tool_input.file_path' | xargs -I {} sh -c 'echo {} | grep -q \\.ts$ && npx prettier --write {}'"      }]    }]  }}

Block edits to sensitive files:

{  "hooks": {    "PreToolUse": [{      "matcher": "Edit|Write",      "hooks": [{        "type": "command",        "command": "jq -r '.tool_input.file_path' | grep -qE '(\\.env|secrets|credentials)' && exit 2 || exit 0"      }]    }]  }}

Desktop notification when Claude needs input:

{  "hooks": {    "Notification": [{      "matcher": "",      "hooks": [{        "type": "command",        "command": "notify-send 'Claude Code' 'Awaiting your input'"      }]    }]  }}

Key benefits:

• Deterministic — Always runs, no LLM decision-making
• Zero token cost — Shell commands, not prompts
• Safety guardrails — Block dangerous operations
• Automation — Linting, formatting, testing without asking

Pro tip: Use exit 2 in PreToolUse hooks to block the operation and provide feedback to Claude about what to do differently.

Plugins: Shareable Extension Bundles

What it is: A lightweight way to package and share Claude Code customizations. Plugins can bundle any combination of:

• Slash commands — Custom shortcuts for frequent operations
• Subagents — Purpose-built agents for specialized tasks
• MCP servers — Connect to external tools and data sources
• Hooks — Customize behavior at key workflow points

When to use it:

• Share workflows across your team
• Install community-built tooling
• Enforce standards across projects
• Connect internal tools and data sources

Installing plugins:

# Install from a marketplace/plugin marketplace add user-or-org/repo-name# Browse and install/plugin

Example use cases:

• DevOps automation plugins
• PR review workflows
• Security guidance agents
• Documentation generators
• Testing suites

Community marketplaces:

• wshobson/agents — 80+ specialized subagents
• Anthropic’s example plugins for PR reviews, security, and Claude Agent SDK

Key benefit: Toggle on/off as needed — enable when you need capabilities, disable to reduce context complexity.

The Decision Framework

When you need to add configuration, ask yourself:

Is it project context Claude needs every message?└── YES → CLAUDE.mdIs it a workflow you trigger manually?└── YES → CommandShould Claude auto-detect when to apply it?└── YES → SkillDo you need a specialized agent with separate context?└── YES → SubagentDo you need to connect to external tools/APIs/data?└── YES → MCP ServerDo you want to share/install bundled customizations?└── YES → Plugin┌──────────────────────────┬─────────────────────────────┐│ Need                     │ Solution                    │├──────────────────────────┼─────────────────────────────┤│ Personal/team workflow   │ Command or Skill            │├──────────────────────────┼─────────────────────────────┤│ Specialized delegation   │ Subagent                    │           │├──────────────────────────┼─────────────────────────────┤│ Community tooling        │ Plugin (marketplace)        │├──────────────────────────┼─────────────────────────────┤│ External services        │ MCP Server                  │└──────────────────────────┴─────────────────────────────┘

Common Mistakes to Avoid

1. Bloating CLAUDE.md — Every line costs tokens on every message. Move detailed instructions to Skills.
2. Using Commands instead of Skills — If you keep forgetting to run a command, it should probably be a Skill that auto-triggers.
3. Duplicating built-in knowledge — Claude already knows FastAPI best practices. Use Skills for your conventions, not general knowledge.
4. Vague subagent descriptions — Use directive language like “Use PROACTIVELY for…” to ensure Claude delegates correctly.
5. Not guiding MCP usage — Configure MCP servers but forget to tell Claude when to use them. Add hints in CLAUDE.md.
6. Ignoring team sharing — Commands, Skills, Subagents, and .mcp.json are version-controlled. Share them with your team via git or Plugins.

Conclusion

The power of Claude Code isn’t just in the AI — it’s in how well you configure it for your workflow.

Start with a lean CLAUDE.md, add commands for workflows you repeat, create subagents for specialized tasks, configure MCP servers for external integrations, then introduce skills only when you notice patterns Claude should auto-apply. Use plugins to share your setup with teammates or install community solutions.

The goal isn’t to configure everything upfront — it’s to evolve your configuration as you discover friction in your workflow.