skill.md vs agents.md

Last updated: June 2026

If you use Claude Code, you have two places to put instructions: agents.md (read every session) and skill.md (loaded on demand). The distinction is simple in theory but gets blurry in practice. Here's a practical guide to getting it right.

The short version

agents.md (or CLAUDE.md)

Persistent rules. Read every session. Always active.

For: coding standards, project conventions, architecture decisions, testing rules, commit format.

skill.md

On-demand instructions. Loaded when needed. Task-specific.

For: specific workflows (security audits, debugging, migrations), reusable procedures, anything not needed every session.

Decision flowchart

Ask yourself:

Q: Does this rule apply to every file, every task, every session?

Yes → agents.md

No ↓

Q: Is it a specific workflow or procedure?

Yes → skill.md

No ↓

Q: Could this be reused across different projects?

Yes → skill.md

No ↓

Q: Is it needed only occasionally?

Yes → skill.md

No → agents.md

Side-by-side examples

Same topic, different placement:

Testing instructions

agents.md:"Use Vitest for all tests. Write tests before implementation. Minimum 80% coverage."

skill.md:"Performance regression test procedure: 1. Run benchmark suite, 2. Compare against baseline, 3. Flag regressions >10%, 4. Generate report."

Security

agents.md:"Never commit secrets or API keys. Always validate user inputs."

skill.md:"Full OWASP Top 10 security audit procedure with 20-point checklist and report template."

Database

agents.md:"Use Prisma for all database access. Schema changes go through migrations."

skill.md:"Database migration procedure: 1. Create migration, 2. Test on staging, 3. Verify rollback, 4. Deploy to production."

Why the distinction matters

Every line in agents.md is read by Claude Code at the start of every message. A 200-line agents.md means 200 lines of instructions consumed per turn. More tokens = slower responses = higher cost.

Skill files solve this by keeping rarely-needed instructions out of the always-on context. Your agents.md stays at 50-80 lines. Your security audit skill (40 lines) only loads when you ask for a security audit.

For a project with 5 skill files averaging 40 lines each, that's 200 lines of context you're not burning on every message. At scale, this is the difference between a fast, cheap agent and a slow, expensive one.

Common mistakes

•Putting everything in agents.md. If your agents.md is over 100 lines, some of those instructions should be skill files.
•Using skill files for universal rules. "Use TypeScript" is not a skill. It's a persistent rule. It belongs in agents.md.
•Having both CLAUDE.md and agents.md. They're the same thing. Pick one.
•No skill files at all. If you only have agents.md, you're either overloading it or missing opportunities to give Claude Code deeper task-specific instructions.

Not sure? Just describe it.

Tell us what your AI agent should do, and we'll tell you whether it belongs in agents.md or skill.md — with generated markdown content ready to use.

Try ClaudeOrNot →