SKILL.md vs CLAUDE.md vs AGENTS.md

What Each File Is For

Search intent for claude.md vs agents.md is informational and comparative. The person asking is usually configuring an AI coding setup and needs to know which file should hold durable project rules, which file should hold reusable skills, and how to avoid contradictory instructions.

The cleanest answer is to treat these files as different layers. CLAUDE.md is Claude-facing project context. AGENTS.md is agent-neutral repository guidance. SKILL.md is the entrypoint for a reusable workflow inside a skill folder.

Repository instruction files describe where the agent is working; skill files describe how the agent should perform a recurring workflow.

SKILL.md vs CLAUDE.md vs AGENTS.md at a Glance

Use SKILL.md for Reusable Workflows

A SKILL.md file belongs inside a skill folder. Its job is to tell an AI agent when to load the skill and how to complete the workflow after it loads. That workflow might be code review, release prep, customer research synthesis, support escalation writing, or a content brief.

A good skill is portable. It should not depend on the exact repo where you first wrote it unless the skill is intentionally project-specific. If the same instruction would help in Claude Code today, Codex tomorrow, and ChatGPT later, it should usually be a skill rather than a line buried in a repo instruction file.

---
name: diff-risk-review
description: Use when reviewing code changes for behavior risk, missing tests, migration problems, and release impact.
---

Review behavior before style.
Inspect changed files, relevant tests, and any migration or auth boundaries.
Return findings ordered by severity, with file references and concrete repro conditions.
Do not suggest unrelated refactors unless they block the requested change.

If you need the detailed file format, read SKILL.md explained. To build one from scratch, follow how to create a Claude Skill.

Use CLAUDE.md for Claude-Specific Project Context

CLAUDE.md is useful when Claude or Claude Code needs persistent guidance inside a project. It can explain local conventions, where tests live, which commands are reliable, what architecture boundaries matter, and what tone or review style the team expects from Claude.

Keep it short enough to stay useful. A repo-level file that becomes a full manual is easy for humans to ignore and easy for agents to misapply. Put stable, project-wide rules there; move repeatable task procedures into skills.

# Project guidance for Claude

- Use npm test for the narrow test suite before broad checks.
- Do not edit billing or auth code unless the task explicitly asks.
- Prefer existing components and helpers over new abstractions.
- For code review tasks, use the diff-risk-review skill if available.

The file should describe the project, not become the only copy of your best workflow. When a review rubric, testing checklist, or writing process is useful outside this repo, extract it into a skill.

Use AGENTS.md for Cross-Agent Repo Instructions

AGENTS.md is the better home for agent-neutral repository guidance. If a repo may be worked on by Codex, Claude Code, and other coding agents, the file can establish shared expectations without tying the wording to one assistant.

Use it for commands, verification standards, ownership boundaries, release notes, and task handoff rules. Write it like an instruction file a new agent can read before touching the codebase.

# Agent instructions

- Read existing patterns before editing.
- Keep changes scoped to the requested behavior.
- Run the narrowest relevant tests and report any skipped checks.
- Never modify generated files or credentials.
- Summaries should include changed files, verification, and remaining risk.

AGENTS.md is especially helpful for teams that want one repo instruction surface across tools. It should still link out conceptually to reusable skills rather than duplicating every workflow in full.

Before and After: Cleaning Up a Confused Repo

Imagine a team has a strong pull request review process. Over time, pieces of that process end up in four places: a private Claude prompt, a CLAUDE.md file, an AGENTS.md file, and a copied checklist inside two project folders. The agent sometimes reviews migrations first, sometimes style first, and sometimes misses the release-risk notes entirely.

The fix is not to paste the longest version everywhere. The fix is to choose a source of truth. The reusable review method becomes a skill. The repo files keep only the local facts and a short instruction to use that skill when reviewing code changes.

This pattern also makes onboarding easier. A teammate can understand the repo by reading the repo file, then understand the workflow by opening the skill. They do not need to guess which duplicate copy is current.

Where Different Instructions Belong

Most confusion comes from mixing durable process, local facts, and tool-specific preferences. Use this routing table before adding another paragraph to any instruction file.

Avoid the Duplicate-Instructions Trap

The most expensive mistake is copying the same workflow into CLAUDE.md, AGENTS.md, a private prompt, and a skill folder. That works for a week. Then one copy changes, the others drift, and every agent starts following a slightly different process.

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude, so your setup follows you across every machine, repo, and tool.

The practical pattern is simple: keep the canonical reusable workflow in the skill library, then let project files mention which skill to use. That way a new machine, repo, or teammate does not require rebuilding the same setup from memory.

Setup Checklist for a Clean Agent Instruction System

1. List the repeated workflows: Code review, test writing, release prep, content editing, research synthesis, and support escalation are skill candidates.
2. Separate repo facts from workflow rules: Commands, generated folders, and product boundaries belong in repo instruction files.
3. Choose one shared repo file: If multiple agents work in the repo, use AGENTS.md for neutral guidance and keep CLAUDE.md only for Claude-specific notes.
4. Turn mature prompts into skills: When a prompt has repeated several times, convert it into a named skill with a trigger and output standard.
5. Link instead of duplicating: Repo files can say which skill to use without pasting the whole skill body.
6. Review drift monthly: Delete stale instructions, merge duplicates, and keep one source of truth for reusable workflows.

The goal is not more files. The goal is fewer lost instructions and clearer ownership.

Common Mistakes

• Putting everything in CLAUDE.md: This makes Claude better in one repo but leaves Codex, ChatGPT, and future machines behind.
• Making AGENTS.md too generic: A file that says "write good code" adds noise. Name actual commands, boundaries, and checks.
• Using SKILL.md for project trivia: A skill should not be a dumping ground for one repo's temporary facts.
• Copying skills between repos: Copies drift. Keep a source library and sync the real folders where agents need them.

People Also Ask About Agent Instruction Files

Where to Go Next

Browse the resources hub for the full skills series. For the file format, read SKILL.md explained. For folder scope, use where Claude Code stores skills. If you are comparing instruction types more broadly, read skills vs prompts and Codex skills. When you are ready to draft a portable workflow, use the free Claude Skill Creator.