Claude Skills

Skills vs CLAUDE.md vs Subagents vs Hooks: Choosing the Right Customization

Claude Code offers several customization options: Skills, CLAUDE.md, subagents, hooks, and MCP servers. They solve different problems, and knowing when to use each prevents you from building the wrong thing. This guide breaks down the key differences and shows you how to combine them effectively.

The Five Customization Options

Before diving into comparisons, let's define each option:

Skills — Task-specific expertise that loads on demand when Claude matches your request to the skill's description.

CLAUDE.md — Project-wide instructions that load into every conversation automatically.

Subagents — Isolated execution contexts that receive a task, work independently, and return results.

Hooks — Event-driven automation that fires on specific triggers (file saves, tool calls, etc.).

MCP Servers — External tools and integrations that extend Claude's capabilities.

CLAUDE.md vs Skills

This is the most common point of confusion. Both provide instructions to Claude, but they differ in when those instructions are active.

CLAUDE.md: Always-On Instructions

CLAUDE.md loads into every conversation, always. It's part of the base context before you even start typing.

Use CLAUDE.md for:

Project-wide standards that always apply
Constraints like "never modify the database schema"
Framework preferences ("use TypeScript strict mode")
Coding style guidelines
File organization rules
Testing requirements that apply to all code

Example CLAUDE.md:

# Project Standards

## TypeScript
- Always use TypeScript strict mode
- Prefer interfaces over types for object shapes
- Use explicit return types on all functions

## Testing
- Every new feature requires tests
- Use Jest for unit tests
- Use Playwright for E2E tests

## Database
- Never modify the schema directly
- All schema changes require migrations
- Use Prisma for database access

## Code Style
- Use Prettier for formatting
- Follow Airbnb style guide
- Maximum line length: 100 characters

Skills: On-Demand Expertise

Skills load only when relevant. When Claude matches a request to a skill's description, that skill's instructions join the conversation.

Use Skills for:

Task-specific expertise (code reviews, documentation generation)
Knowledge that's only relevant sometimes
Detailed procedures that would clutter every conversation
Domain-specific workflows

Example Skill:

---
name: api-design
description: Designs RESTful APIs following best practices. Use when creating endpoints, designing APIs, or when the user asks about API structure.
---

When designing an API:

1. Use RESTful conventions:
   - GET for retrieval
   - POST for creation
   - PUT for full updates
   - PATCH for partial updates
   - DELETE for removal

2. Use plural nouns for resources: `/api/users`, `/api/posts`

3. Nest resources logically: `/api/users/:id/posts`

4. Return consistent response format:
   ```json
   {
     "data": { ... },
     "meta": { "page": 1, "total": 100 },
     "errors": []
   }

Include proper error handling with HTTP status codes


### When to Choose Which

**Choose CLAUDE.md when:**
- The instruction applies to **every** conversation
- You want it active without having to ask
- It's a constraint or standard, not task-specific knowledge

**Choose Skills when:**
- The instruction applies to **specific tasks**
- You want to keep base context lean
- The knowledge is detailed and would clutter CLAUDE.md

**Example:**
- ✅ CLAUDE.md: "Always use TypeScript strict mode"
- ✅ Skill: "How to write unit tests for React components"

## Skills vs Subagents

Skills and subagents both provide specialized capabilities, but they differ in **execution context**.

### Skills: Enhanced Knowledge in Current Context

Skills add knowledge to your **current conversation**. When a skill activates, its instructions join the existing context. Claude continues working in the same conversation with additional expertise.

**Use Skills when:**
- You want to enhance Claude's knowledge for the current task
- The expertise applies throughout a conversation
- You want Claude to remember the skill's guidance as the conversation continues

### Subagents: Isolated Execution

Subagents run in a **separate context**. They receive a task, work on it independently, and return results. They don't share conversation history with the main agent.

**Use Subagents when:**
- You want to delegate a task to a separate execution context
- You need different tool access than the main conversation
- You want isolation between delegated work and your main context
- You're running parallel tasks

**Example:**

You're working on a feature and want to:
1. **Skill**: Activate your "api-design" skill to guide endpoint creation
2. **Subagent**: Delegate test generation to a separate agent while you continue working

The skill enhances your current conversation. The subagent works independently and returns completed tests.

## Skills vs Hooks

Skills and hooks both automate behavior, but they trigger differently.

### Skills: Request-Driven

Skills activate based on **what you're asking**. Claude matches your request to skill descriptions and loads relevant expertise.

**Trigger**: User request matches skill description

**Use Skills when:**
- You want automatic expertise based on the task
- The behavior depends on what you're asking for
- You want Claude to apply knowledge, not just run code

### Hooks: Event-Driven

Hooks fire on **events**. A hook might run a linter every time Claude saves a file, or validate input before certain tool calls.

**Trigger**: Specific event (file save, tool call, etc.)

**Use Hooks for:**
- Operations that should run on every file save
- Validation before specific tool calls
- Automated side effects of Claude's actions
- Enforcing constraints automatically

**Example:**

**Skill**: "When reviewing code, check for security vulnerabilities"
- Activates when you ask for a code review
- Provides knowledge about what to look for

**Hook**: "Run ESLint on every file save"
- Fires automatically when any file is saved
- Executes code, doesn't provide knowledge

## Skills vs MCP Servers

This is a category difference, not a choice between similar options.

### Skills: Knowledge and Procedures

Skills provide **instructions** to Claude. They tell Claude how to approach tasks, what to check for, and what procedures to follow.

**Skills provide:**
- Task-specific knowledge
- Procedures and workflows
- Guidelines and best practices

### MCP Servers: Tools and Integrations

MCP (Model Context Protocol) servers provide **external tools** that Claude can use. They extend Claude's capabilities with new actions.

**MCP servers provide:**
- Database access
- API integrations
- File system operations
- External service connections

**Example:**

**Skill**: "How to write database migrations"
- Teaches Claude the procedure
- Provides migration template
- Explains best practices

**MCP Server**: Database connection
- Lets Claude query the database
- Provides tools to read schema
- Enables direct database operations

**They work together**: The skill teaches Claude how to write good migrations. The MCP server gives Claude the tools to inspect the current schema.

## Putting It All Together

A typical production setup combines multiple features:

### Example: Full-Stack Development Setup

**CLAUDE.md** (always active):
```markdown
# Project Standards

- Use TypeScript strict mode
- All API routes require authentication
- Never commit secrets or API keys
- Run tests before committing
- Use Prettier for formatting

Skills (load on demand):

api-design — Activates when designing endpoints
code-review — Activates when reviewing code
database-migration — Activates when working with schema
react-component — Activates when building UI components

Hooks (event-driven):

Run ESLint on every file save
Run Prettier before commits
Validate environment variables before deployment

Subagents (isolated execution):

Test generation agent (writes tests while you continue coding)
Documentation agent (updates docs in parallel)

MCP Servers (external tools):

Database MCP (query schema, run migrations)
GitHub MCP (create PRs, manage issues)
Slack MCP (send notifications)

Decision Matrix

When to Use CLAUDE.md

✅ Use CLAUDE.md when:

Instruction applies to every conversation
It's a project-wide standard or constraint
You want it active without asking
It's short and doesn't clutter context

❌ Don't use CLAUDE.md when:

Instruction only applies to specific tasks
It's long and detailed
You want it to load conditionally

When to Use Skills

✅ Use Skills when:

Expertise applies to specific tasks
You want automatic activation based on request
Knowledge is detailed and would clutter CLAUDE.md
You want to share expertise across projects (personal skills)

❌ Don't use Skills when:

Instruction should always be active (use CLAUDE.md)
You need isolated execution (use subagents)
You need event-driven behavior (use hooks)

When to Use Subagents

✅ Use Subagents when:

You want to delegate work to isolated context
You need parallel execution
You want different tool permissions
Task is independent of main conversation

❌ Don't use Subagents when:

You want knowledge to persist in current conversation (use skills)
You need event-driven automation (use hooks)

When to Use Hooks

✅ Use Hooks when:

You need event-driven automation
Operation should run on every file save
You want to enforce constraints automatically
You need validation before tool calls

❌ Don't use Hooks when:

You want request-driven behavior (use skills)
You need to provide knowledge, not run code

When to Use MCP Servers

✅ Use MCP Servers when:

You need external tool integration
You want to extend Claude's capabilities
You need database, API, or service access

❌ Don't use MCP Servers when:

You just need to provide instructions (use skills or CLAUDE.md)

Real-World Examples

Example 1: Code Review Workflow

CLAUDE.md:

- All code must pass ESLint before commit
- Security is our top priority

Skill (code-review):

---
name: code-review
description: Performs comprehensive code reviews
---

When reviewing code:
1. Check security (read references/security-checklist.md)
2. Check performance
3. Check style
4. Verify tests exist

Hook:

// Run ESLint on every file save
onFileSave(() => {
  runESLint();
});

How they work together:

CLAUDE.md ensures security is always a priority
Skill provides detailed review procedure when you ask for a review
Hook automatically runs ESLint on every save

Example 2: API Development

CLAUDE.md:

- All API routes require authentication
- Use RESTful conventions
- Return consistent JSON format

Skill (api-design):

---
name: api-design
description: Designs RESTful APIs
---

When designing an API:
1. Read references/api-conventions.md
2. Use assets/api-route-template.ts
3. Include input validation
4. Add error handling

MCP Server:

Database MCP (inspect schema, run queries)

How they work together:

CLAUDE.md enforces authentication requirement
Skill provides detailed API design guidance when building endpoints
MCP server lets Claude inspect database schema to design accurate endpoints

Example 3: Testing Workflow

CLAUDE.md:

- Every feature requires tests
- Use Jest for unit tests
- Minimum 80% coverage

Skill (test-writing):

---
name: test-writing
description: Writes unit tests for React components
---

When writing tests:
1. Use assets/test-template.spec.ts
2. Test happy path and edge cases
3. Mock external dependencies
4. Verify accessibility

Subagent:

Test generation agent (writes tests in parallel)

Hook:

// Run tests before commit
beforeCommit(() => {
  runTests();
});

How they work together:

CLAUDE.md requires tests for all features
Skill provides detailed testing guidance when you write tests
Subagent can generate tests in parallel while you continue coding
Hook ensures tests pass before commit

Common Mistakes

Mistake 1: Putting Everything in CLAUDE.md

❌ Wrong:

# CLAUDE.md (5,000 lines)

- TypeScript standards
- API design guide (500 lines)
- Security checklist (300 lines)
- Testing procedures (400 lines)
- Deployment guide (600 lines)
- Database conventions (400 lines)
...

✅ Right:

# CLAUDE.md (50 lines)

- Use TypeScript strict mode
- All features require tests
- Never commit secrets
- Run Prettier before commit

+ Skills for detailed procedures:

api-design skill (loads when designing APIs)
security-review skill (loads when reviewing security)
test-writing skill (loads when writing tests)

Mistake 2: Using Skills for Always-On Rules

❌ Wrong:

---
name: typescript-strict
description: Enforces TypeScript strict mode
---

Always use TypeScript strict mode.

This should be in CLAUDE.md because it applies to every conversation.

✅ Right:

Put "Use TypeScript strict mode" in CLAUDE.md.

Mistake 3: Using Hooks for Request-Driven Tasks

❌ Wrong:

// Hook that tries to detect when user wants a code review
onToolCall(() => {
  if (/* somehow detect review intent */) {
    runCodeReview();
  }
});

✅ Right:

Use a skill that activates when you ask for a review:

---
name: code-review
description: Performs code reviews. Use when reviewing code or checking pull requests.
---

Mistake 4: Using Subagents for Simple Knowledge

❌ Wrong:

Creating a subagent just to provide API design guidelines.

✅ Right:

Use a skill — subagents are for delegated work, not knowledge sharing.

Feature Comparison Table

| Feature | When Active | Context | Use Case | |---------|-------------|---------|----------| | CLAUDE.md | Always | Shared | Project-wide standards | | Skills | On request match | Shared | Task-specific expertise | | Subagents | On delegation | Isolated | Parallel/delegated work | | Hooks | On event | N/A | Automated operations | | MCP Servers | When tool called | N/A | External integrations |

Combining Features Effectively

Scenario 1: Building a New Feature

You say: "Build a new user registration endpoint"

What happens:

CLAUDE.md is already active (TypeScript strict, auth required, etc.)
Skill activates: api-design skill loads API conventions
MCP Server: Database MCP lets Claude inspect User schema
Subagent: Optionally delegate test writing to test-generation agent
Hook: ESLint runs automatically when Claude saves files

Scenario 2: Code Review

You say: "Review this pull request"

What happens:

CLAUDE.md is already active (security priority, style guide, etc.)
Skill activates: code-review skill loads review checklist
Skill runs: scripts/run-linter.sh to check style
Skill reads: references/security-checklist.md for security review
Hook: Not used (reviews are request-driven, not event-driven)

Scenario 3: Deployment

You say: "Deploy to production"

What happens:

CLAUDE.md is already active ("run tests before deploy")
Skill activates: deployment skill loads deployment checklist
Hook: Pre-deployment hook validates environment variables
Subagent: Optionally run tests in parallel while preparing deployment
MCP Server: CI/CD MCP triggers deployment pipeline

Migration Guide

Moving from CLAUDE.md to Skills

If your CLAUDE.md is getting too long, migrate task-specific content to skills:

Before (CLAUDE.md):

# Project Standards

- Use TypeScript strict mode
- All features require tests

## API Design (500 lines of detailed guidance)
...

## Security Review (300 lines of checklist)
...

After:

CLAUDE.md:

# Project Standards

- Use TypeScript strict mode
- All features require tests

Skills:

api-design skill (500 lines)
security-review skill (300 lines)

Result: Leaner base context, expertise loads only when needed.

Best Practices

1. Start with CLAUDE.md

Begin with project-wide standards in CLAUDE.md. Add skills as you identify task-specific needs.

2. Keep CLAUDE.md Under 100 Lines

If CLAUDE.md exceeds 100 lines, consider moving detailed procedures to skills.

3. Use Skills for Detailed Procedures

Anything longer than a few bullet points probably belongs in a skill.

4. Use Hooks for Automation

If it should happen automatically on an event, use a hook.

5. Use Subagents for Delegation

If you want work done in parallel or isolation, use a subagent.

6. Use MCP for External Tools

If you need to connect to external services, use MCP servers.

Lesson Reflection

Before moving on, consider these questions:

Look at your current CLAUDE.md file. Is there anything in it that would work better as a skill (loaded only when relevant)? Are there detailed procedures that clutter the base context?

Think about your team's development workflow. Which combination of Claude Code features (skills, hooks, subagents, MCP) would address your most common pain points?

Consider your most frequent tasks. Would they benefit from:

Always-on standards (CLAUDE.md)?
On-demand expertise (skills)?
Automated operations (hooks)?
Parallel execution (subagents)?
External integrations (MCP)?

Quick Reference

CLAUDE.md

When: Always active
Use for: Project-wide standards
Example: "Use TypeScript strict mode"

Skills

When: On request match
Use for: Task-specific expertise
Example: Code review procedures

Subagents

When: On delegation
Use for: Isolated/parallel work
Example: Test generation while coding

Hooks

When: On events
Use for: Automated operations
Example: Run linter on file save

MCP Servers

When: When tool called
Use for: External integrations
Example: Database access

Conclusion

Each Claude Code customization option handles its own specialty:

CLAUDE.md — Always-on project standards
Skills — On-demand task expertise
Subagents — Isolated execution contexts
Hooks — Event-driven automation
MCP Servers — External tools and integrations

Don't force everything into one approach. Use the right tool for each job, and combine them for comprehensive customization.

Start with CLAUDE.md for project standards, add skills for task-specific expertise, use hooks for automation, delegate to subagents when needed, and integrate external tools with MCP servers.

The best Claude Code setups use multiple features working together, each handling what it does best.