Language: English
Start 14-day free trial

Guide

SKILL.md vs AGENTS.md: what goes in each

Updated

AGENTS.md and SKILL.md do different jobs. AGENTS.md is a repository's standing instructions for coding agents, read at the start of every session: how to build and test, the project's conventions, the "always do X" rules. A SKILL.md is the method for one task, such as writing release notes or reviewing a migration, and the agent loads it only when a request matches its description. Put what every session needs in AGENTS.md, and move each multi-step procedure into its own skill, so the always-on file stays short and the procedures load only when they're used.

Short answer

  • AGENTS.md: facts and rules for every session, at the repository root.
  • SKILL.md: one task's steps, loaded when the task comes up.
  • Claude Code reads AGENTS.md when there's no CLAUDE.md, or through an import.
  • Rule of thumb: if it's a procedure, it's a skill.

Side by side

 AGENTS.mdSKILL.md
What it holdsBuild and test commands, conventions, project layoutOne task's method: steps, template, example
When it's readBefore any work, every sessionWhen a request matches its description, or when called by name
Where it livesRepository root; nested files for subprojects, the nearest winsA skill folder, such as .claude/skills/<name>/ or Codex's skill locations
FormatPlain Markdown, no required fieldsFront matter with name and description, then instructions
SizeCodex stops adding files at 32 KiB by defaultClaude Code advises under 500 lines; reference files beside it

From agents.md, the Codex and Claude Code docs, and the Agent Skills specification, read 5 November 2026.

A worked example: splitting one crowded file

Illustration: a made-up business. A 9-person product team's AGENTS.md had grown to 400 lines: the test command and naming rules, plus a 120-line procedure for release notes and a 90-line checklist for database migrations. Agents read all of it before every task, including the many tasks that had nothing to do with releases.

  • Kept in AGENTS.md (60 lines): build and test commands, folder layout, naming conventions, "never commit secrets".
  • Moved to a release-notes skill: the procedure, with the description "Use when someone asks for release notes or a customer changelog".
  • Moved to a migration-review skill: the checklist, described as "Use when a change adds or alters a database migration".

Claude Code users on the team add one line to their CLAUDE.md, @AGENTS.md, so both tools read the same standing rules. Now every session starts with 60 lines, and the two procedures load only when someone asks for them.

Split yours

  1. Read your AGENTS.md and mark each section "every task" or "one task".
  2. Keep the "every task" sections short: commands, conventions, layout, hard rules.
  3. Turn each "one task" section into a skill with a name and a "use when" description.
  4. Point Claude Code at AGENTS.md with an import in CLAUDE.md, if the team uses both.
  5. Test: ask for each task in plain words and check that the right skill loads.

Next step: share the skills

Skills in one repository reach the people who work in it. For skills a whole team uses across repositories and tools, see sharing Claude skills on GitHub and syncing skills across Claude Code, Codex, Cursor and OpenCode.

Skills for this

All skills

Questions

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

AGENTS.md is a repository's standing instructions for coding agents, read at the start of every session: how to build, test and follow the project's conventions. A SKILL.md describes one task, such as writing release notes, and is loaded only when a request matches its description. Facts for every session go in AGENTS.md; procedures for one task go in a skill.

Does Claude Code read AGENTS.md?

Yes. Claude Code's docs say it reads a repository's AGENTS.md as project instructions when there's no CLAUDE.md in the working directory or above it, and a CLAUDE.md can import AGENTS.md so both tools share one file.

Can a skill replace AGENTS.md?

No. A skill loads only when its task comes up, so rules that must apply in every session, like the test command or a naming convention, would be missed. Keep those in AGENTS.md and move multi-step procedures out of it into skills.

AI skill

Have your AI turn a prompt that works into a skill your team can reuse

Put this skill in AI Skill Pod and everyone on your team gets it in their Claude, Cursor or ChatGPT (Pro, Business, Enterprise): one invite link, free to start. Turn a prompt into a skill has your AI turn a procedure that's crowding your AGENTS.md into its own skill: a name, a description that says when to load it, the steps and an example.

Use this skill in your AI

14 days free · No card needed

Sources

  1. AGENTS.md — an open format for guiding coding agents: a README for agents at the repository root, nested files for subprojects, the nearest file wins; read by Codex, Cursor, Gemini CLI, GitHub Copilot's coding agent and others (read 2026-11-05)
  2. Codex docs: AGENTS.md — read before any work; global file in ~/.codex, project files from root down; combined size capped at 32 KiB by default (read 2026-11-05)
  3. Claude Code docs: How Claude remembers your project — CLAUDE.md loads every session; Claude Code reads AGENTS.md when there's no CLAUDE.md, or through an import; multi-step procedures belong in a skill (read 2026-11-05)
  4. Claude Code docs: Skills — loaded when a request matches the description, or by /name (read 2026-11-05)
  5. Agent Skills specification — a folder with SKILL.md: name, description, instructions (read 2026-11-05)
  6. ChatGPT docs: Build skills — Codex skills in the repository, $HOME/.agents/skills and admin locations (read 2026-11-05)