Architecture decision

AGENTS.md vs Agent Skills

Where should durable agent instructions and repeatable workflows live?

Get the short answerReview evidence

The short answer

If the guidance describes the repository, put it in AGENTS.md. If it describes how to perform a reusable task, package it as a Skill.

Choose

Repository instructions

Durable, version-controlled guidance that tells coding agents how a repository is organized, how to verify work, and which boundaries matter.

  • Build, test, formatting, or architecture guidance applies broadly across the repository.
  • Nested packages need closer, path-specific instructions.
  • The rule should be version-controlled and visible in most relevant sessions.
Open the Repository instructions guide

Choose

Agent Skills

Discoverable, reusable packages of instructions and resources that teach an agent a specialized workflow without loading the whole procedure into every session.

  • The workflow has a trigger, sequence, supporting references, and an output contract.
  • Loading the full procedure in every session would waste context.
  • The capability should be reusable across projects or compatible agents.
Open the Agent Skills guide
Use both

How the layers combine

  1. 01

    Keep the repository's short definition of done in AGENTS.md.

  2. 02

    Link to the Skill for the detailed deployment, review, or release procedure.

  3. 03

    Enforce non-negotiable checks with CI or hooks instead of duplicating them in both files.

Decision review

Questions to answer before implementation

  • Does every always-on instruction apply to most work in its scope?
  • Can the Skill be selected from its description without extra explanation?
  • Are duplicated or contradictory instructions removed?
  • Does the Skill fail clearly when a prerequisite is missing?
  • Can a reviewer trace each instruction to a current repository need?

Evidence ledger

Primary documentation for both sides

Reviewed July 26, 2026. Use the provider documentation for current configuration and security behavior.

AGENTS.md specification and examples

AGENTS.md

The portable AGENTS.md format and repository instruction pattern.

Codex AGENTS.md guidance

OpenAI

Codex discovery, precedence, scope, and maintenance guidance.

How Claude remembers your project

Anthropic

CLAUDE.md locations, loading behavior, concise instruction guidance, and AGENTS.md interoperability.

Agent Skills specification

Agent Skills

The open SKILL.md package format and progressive-disclosure model.

Build skills for ChatGPT and Codex

OpenAI

Current OpenAI Skill structure, discovery, and authoring guidance.

Extend Claude with skills

Anthropic

Claude Code Skill discovery, configuration, supporting files, and invocation behavior.