comparison / agent instruction files

SKILL.md vs
AGENTS.md.

Use AGENTS.md for repository guidance that should shape most coding work, CLAUDE.md for persistent Claude Code context, and SKILL.md for a focused workflow loaded only when relevant. They can coexist: the instruction files orient the agent, while skills provide deeper procedures without putting every manual into every task.

What is the difference between SKILL.md, AGENTS.md, and CLAUDE.md?

File	Best for	Typical loading	Portability
SKILL.md	One reusable procedure with optional scripts, references, and assets	Metadata at discovery; full workflow when invoked or matched	Open Agent Skills format across compatible clients
AGENTS.md	Repository setup, commands, conventions, and standing expectations	Read before work; nested files can refine local guidance	Open repository-instruction format across many coding agents
CLAUDE.md	Persistent project, user, or organization context for Claude Code	Loaded into Claude Code sessions within its documented scope	Claude-specific, although some other clients support it for compatibility

The practical test is frequency. If an instruction should influence nearly every task in a repository, it belongs in the repository guidance layer. If it describes how to perform one class of task, make it a skill. Start with what Agent Skills are if the format is new to you.

When should you use SKILL.md?

Use SKILL.md for a repeatable job with a recognizable trigger and an observable result: code review, incident triage, release preparation, spreadsheet analysis, or a research brief. The portable specification requires YAML frontmatter with a matching name and a description that says what the skill does and when to use it.

review-api-change/
├── SKILL.md
├── references/
│   └── compatibility-policy.md
└── scripts/
    └── check-schema.ts

The agent initially sees lightweight routing metadata. It loads the full procedure and supporting files when the task calls for them. That progressive loading makes skills a better home for detailed workflows than an instruction file included with unrelated work. Use the Agent Skill creation guide for a valid example and trigger tests.

When should you use AGENTS.md?

Use AGENTS.mdas a repository's operating manual for coding agents. Good content includes the project layout, setup and test commands, code conventions, security constraints, pull-request expectations, and non-obvious facts an agent needs before changing the codebase. It is plain Markdown with no required frontmatter.

# AGENTS.md

## Build and test
- Install with npm ci.
- Run npm test after TypeScript changes.

## Repository rules
- Keep public API changes backward compatible.
- Never commit generated credentials.

The AGENTS.md open format describes it as a README for agents. Client behavior still matters: Codex builds a global-to-local instruction chain, while VS Code supports root and optionally nested files. Verify the client before relying on precedence or overrides.

When should you use CLAUDE.md?

Use CLAUDE.md for concise context Claude Code should carry across sessions: build commands, architecture, terminology, coding standards, and rules that usually apply. Claude Code supports managed, user, project, and local scopes and can organize path-specific guidance under .claude/rules/.

Anthropic's Claude Code memory documentation says multi-step procedures or guidance relevant to only one part of a codebase should move to a skill or path-scoped rule. Its skills documentation adds the key reason: unlike CLAUDE.md, a skill body loads only when used.

Can AGENTS.md and CLAUDE.md share the same instructions?

Yes, but avoid maintaining two drifting copies. Claude Code does not natively treat AGENTS.md as its project memory file; its official documentation recommends importing an existing AGENTS.md from CLAUDE.md, then adding only Claude-specific guidance below the import.

@AGENTS.md

## Claude Code
- Use plan mode for changes under src/billing/.

This keeps shared repository rules in one source while preserving client-specific additions. Cross-client behavior changes, so test what each agent actually loads instead of assuming all tools interpret every filename.

Where should common instructions go?

Instruction	Best home	Why
Install, build, lint, and test commands	`AGENTS.md` or `CLAUDE.md`	Needed across many repository tasks
Architecture and naming conventions	`AGENTS.md` or `CLAUDE.md`	Standing project context
Step-by-step release workflow	`SKILL.md`	Task-specific procedure with a finish condition
Detailed API or policy reference	Skill `references/`	Loaded only when that workflow needs it
Deterministic validation command	Skill `scripts/` or repository script	Executable behavior stays inspectable and testable
Hard security enforcement	Permissions, sandbox, hooks, or CI	Prompt instructions are guidance, not an enforcement boundary

Do not duplicate a procedure across all three files. Keep the durable fact or rule in the persistent layer, link to one canonical skill for the workflow, and enforce non-negotiable controls in code or platform settings. The Agent Skill security checklist explains the trust boundary.

How do you verify which file an agent loaded?

Codex: ask it to summarize active instructions from the target directory and inspect documented session logs when needed.
Claude Code: use /memory to see loaded CLAUDE.md, local, and rules files; test a skill with both matching and non-matching prompts.
VS Code: use the chat customization diagnostics view to inspect instruction sources and errors.
Any client: test from the actual working directory because scope and nested-file behavior depend on location.

For skills, verify both routing and output: confirm the description activates on relevant requests, stays silent on nearby unrelated requests, and produces the promised artifact. The installation guide covers activation checks, updates, and removal.

What do developers ask about agent instruction files?

Should a workflow go in AGENTS.md or SKILL.md?

Put repository-wide expectations that should guide most work in AGENTS.md. Put a focused, reusable procedure in its own SKILL.md so a compatible agent can discover and load it only for matching tasks.

Should a Claude Code workflow go in CLAUDE.md or SKILL.md?

Keep concise facts, commands, conventions, and always-applicable rules in CLAUDE.md. Move multi-step procedures and task-specific reference material into a skill. Claude Code's documentation explicitly recommends this split.

Is AGENT.md the same as AGENTS.md?

No. The cross-agent repository instruction file is AGENTS.md, plural. Some products use other similarly named files; for example, VS Code custom agents use files ending in .agent.md to define selectable agent personas with tools and instructions.

Is the Agent Skills file named SKILL.md or SKILLS.md?

The open Agent Skills specification requires one uppercase SKILL.md file, singular, at the root of each skill folder. SKILLS.md is not the standard filename.

Which primary sources define these files?

This comparison was checked against the Agent Skills specification, the AGENTS.md open format, and current instruction and skills documentation from OpenAI Codex, Claude Code, and VS Code. File discovery and precedence vary by client and version.

Continue with the Agent Skills versus MCP comparison, directory guide, or browse real Agent Skills and inspect their source manuals.