What is skill.md?

A skill.md file is a set of instructions for Claude Code that gets loaded on demand. Unlike agents.md, which is read every session, skill.md files are only pulled in when you ask Claude Code to do a specific task.

Think of agents.md as the employee handbook — rules that always apply. A skill.md is a standard operating procedure for a specific task — follow it when you need it, ignore it otherwise.

Why skill.md matters

Without skill files, every instruction you want Claude Code to follow has to go in agents.md. That file gets read on every message. More instructions = more tokens consumed = slower responses = higher cost.

Skill files solve this by letting you keep task-specific instructions separate. Your agents.md stays lean with universal rules. Your skill files hold detailed procedures for specific tasks. Claude Code loads the right skill when needed.

Annotated example

# Performance Optimization Skill
## Purpose
Optimize slow-running code by identifying bottlenecks
and applying targeted fixes.

## When to Use
- User reports slow page load times
- API response time exceeds 500ms
- Lighthouse performance score below 80

## Procedure
1. Measure first — never optimize without data
   - Use performance.now() for timing
   - Check Chrome DevTools Performance tab
   - Run Lighthouse audit
2. Identify the bottleneck
   - Is it CPU-bound or I/O-bound?
   - Is it rendering, network, or computation?
3. Apply the fix
   - Rendering: memo, virtualization, code splitting
   - Network: caching, batching, pagination
   - Computation: algorithm choice, Web Workers
4. Verify the improvement
   - Re-run the same benchmarks
   - Ensure no regressions in other areas
   - Document the before/after numbers

## Anti-patterns to Avoid
- Premature optimization without profiling
- Adding caching without understanding cache invalidation
- Over-optimizing code that runs once at startup

## Output Format
Markdown report with:
- Benchmark before/after comparison
- What was changed and why
- Any trade-offs introduced

Notice the structure: purpose, when to use, step-by-step procedure, anti-patterns, and expected output. A good skill file reads like a well-written runbook, not a pile of rules.

When to use skill.md vs agents.md

The rule is simple: if an instruction applies to everything Claude Code does in your project, put it in agents.md. If it only matters for a specific task, put it in a skill file.

Where to put skill files

The convention is .claude/skills/. Name each file after what it does. Claude Code finds and loads the right skill based on your request.