Skip to main content
Skills & Subagents

Skills & Subagents

Extend Claude Code with modular Skills and delegate tasks to specialized Subagents running in their own context.

Skills

Skills are modular capability packages defined as Markdown files. Claude auto-discovers them and loads them on demand, keeping the main context window clean.

Skill File Structure

Create a SKILL.md file in any directory:

# Skill: Database Migration

## Metadata
- trigger: "migration", "database change", "schema update"
- level: 2

## Instructions
When the user asks about database migrations:
1. Check the current schema at @prisma/schema.prisma
2. Generate a migration with `npx prisma migrate dev --name [name]`
3. Update TypeScript types with `npx prisma generate`
4. Run tests to verify nothing broke

## Resources
- @prisma/schema.prisma
- @src/db/client.ts

Three-Layer Progressive Disclosure

Skills use a three-layer loading strategy to minimize context usage:

  1. Level 1 — Metadata (~100 tokens) — Always loaded. Contains trigger keywords and description so Claude knows the skill exists.
  2. Level 2 — Instructions — Loaded when triggered. The main operational instructions.
  3. Level 3 — Resources — Loaded on demand. Full file contents, examples, and reference material.

Auto-Discovery

Claude Code scans for SKILL.md files in:

  • .claude/skills/ — Project-local skills
  • ~/.claude/skills/ — Global skills (shared across projects)
  • Any directory referenced in CLAUDE.md

Subagents

Subagents are independent Claude instances that run in their own context window. The main agent delegates tasks to them, keeping its own context clean.

When to Use Subagents

  • Parallel tasks — Run tests in one subagent while refactoring in another
  • Context isolation — Explore a large module without polluting the main conversation
  • Specialized work — Delegate "write comprehensive tests for this module" as a self-contained task

Using Subagents

You can ask Claude to spawn subagents naturally:

run a subagent to write tests for @src/api/auth.ts
while we continue working on the frontend.

Or be more explicit:

spawn two subagents:
1. one to audit @src/api/ for security issues
2. one to check test coverage for @src/utils/

report back when both are done.

Custom Subagents

Define reusable subagent configurations in .claude/agents/:

# .claude/agents/test-writer.md
You are a test-writing specialist.

Given a source file, write comprehensive tests:
- Unit tests for all public functions
- Edge cases and error conditions
- Mock external dependencies
- Follow the project's existing test patterns

Output only test files. Do not modify source code.

Skills are a fundamental agent design pattern

The three-layer progressive disclosure pattern (metadata → instructions → resources) is how production agent systems manage context efficiently. Understanding this architecture helps you build better AI-powered tools, not just use them.

Learn Agent Architecture & multi-agent patterns

Next Steps

  • Hooks — Deterministic automation (complements skills)
  • MCP — Connect to external tools and data sources
  • CLAUDE.md Guide — Project context that skills build upon