AGENTS.md and SKILL.md: The Complete Guide to Configuring AI Coding Agents

What AGENTS.md Does

Every AI coding agent starts a task by scanning your repository. It reads file trees, package manifests, READMEs. But READMEs are written for humans. They explain what a project does, not how an agent should work on it.

AGENTS.md fills that gap. It is a markdown file, placed at the root of your repository, that contains the context coding agents need to work effectively: build commands with exact flags, test procedures, code style rules that differ from defaults, architectural constraints, and boundaries (files the agent should never touch).

The format is plain markdown. No required fields. No YAML frontmatter. No special syntax. Write headings and bullet points. The agent parses the text and adjusts its behavior accordingly.

The specification is stewarded by the Agentic AI Foundation under the Linux Foundation. It emerged in mid-2025 to solve a real problem: developers were maintaining separate instruction files for each tool (.cursorrules, CLAUDE.md, .github/copilot-instructions.md). AGENTS.md is the cross-tool standard. One file, every agent.

The Research: 28.6% Faster, 16.6% Fewer Tokens

A study from Princeton researchers measured the impact of AGENTS.md on real-world coding tasks. They ran OpenAI Codex (gpt-5.2-codex) across 10 repositories and 124 merged pull requests, executing each task twice in isolated Docker environments: once with the repository's AGENTS.md file present, once without.

The mechanism is straightforward. Without AGENTS.md, the agent spends time exploring: reading directory structures, inferring build systems, guessing test commands. With AGENTS.md, that context is provided upfront. The agent skips exploratory steps and works directly toward the solution.

What to Include in AGENTS.md

An analysis of 2,500+ repositories by GitHub's engineering team identified six categories that consistently improve agent performance. Effective files prioritize copy-pasteable commands over vague tool names, real code snippets over descriptive prose, and explicit boundaries over implicit assumptions.

# Invoice API

FastAPI, Python 3.12, PostgreSQL, SQLAlchemy 2.0, Alembic.

## Commands

- `uv run dev`: Dev server (port 8000)
- `uv run pytest tests/ -v`: Full test suite
- `uv run pytest tests/unit/test_handlers.py -v`: Single test file
- `uv run ruff check --fix .`: Lint and auto-fix
- `alembic upgrade head`: Run migrations

## Architecture

- /app/api/v1/       Route handlers (thin, delegate to services)
- /app/services/     Business logic
- /app/models/       SQLAlchemy models
- /app/schemas/      Pydantic v2 request/response schemas
- /app/repositories/ Data access layer (no raw SQL)

## Code Style

- Type hints on all function signatures
- Async handlers by default
- Pydantic v2 models for all request/response shapes
- Named exports from __init__.py, no star imports

## Rules

- Handlers must not contain business logic. Delegate to services.
- All endpoints return { data, error, meta } shape.
- Redis is for caching only, not primary storage.
- Never modify /app/legacy/. It uses sync code intentionally.

## Testing

- pytest-asyncio for async tests
- Factory Boy for test data, never fixtures
- No mocking the database. Use test database.

Start with 20 to 30 lines covering the information agents most often get wrong. Add sections based on real agent mistakes, not hypothetical ones.

What NOT to Include

The follow-up research found that auto-generated AGENTS.md files that duplicated existing README content actually reduced task success. Redundancy is the enemy. Every line should contain information the agent cannot get from reading your code, package manifests, or existing documentation.

Codex enforces a 32 KiB default size limit on AGENTS.md. Content beyond that limit is silently truncated. Even within the limit, shorter files perform better because every line competes for the agent's attention budget.

AGENTS.md vs CLAUDE.md vs .cursorrules vs copilot-instructions.md

Four tools, four configuration files. They serve the same purpose (giving agents project context) but differ in scope, loading behavior, and features.

If you use only one tool, use its native format. If you use multiple tools, put shared instructions in AGENTS.md and tool-specific configuration in the native file. Claude Code reads both AGENTS.md and CLAUDE.md when both are present.

Which Tools Support Which Files

AGENTS.md has the broadest compatibility. If you maintain one instruction file, make it AGENTS.md. Add CLAUDE.md or .cursorrules only if you need features specific to those tools.

What is SKILL.md

AGENTS.md tells agents about your project. SKILL.md tells agents about a specific capability. A skill is a portable directory containing a SKILL.md file plus optional scripts, references, and assets. Skills work across Claude Code, OpenAI Codex, GitHub Copilot, and other compatible agents.

The standard uses progressive disclosure. When a session starts, the agent reads only skill names and descriptions (the YAML frontmatter). When a task matches a skill's domain, the agent loads the full SKILL.md body. Supplementary files (scripts, reference docs) load only when the agent needs them. This keeps context lean until the moment detail is required.

---
name: deploy
description: Deploy the application to production or staging environments
---

# Deploy

## Steps

1. Run the test suite: `bun run test`
2. Build for production: `bun run build`
3. Check for TypeScript errors: `bun run typecheck`
4. If all checks pass, deploy:
   - Staging: `vercel deploy --env preview`
   - Production: `vercel deploy --prod`
5. Verify health: `curl -s https://myapp.com/health | jq .status`

## Rules

- Never deploy to production without passing tests
- Always deploy to staging first for new features
- Production deploys require the main branch

SKILL.md vs AGENTS.md

Skill Directory Structure

my-skill/
├── SKILL.md            # Required: instructions + frontmatter
├── scripts/            # Optional: executable scripts
│   └── validate.sh
├── references/         # Optional: reference documentation
│   └── api-spec.yaml
└── assets/             # Optional: images, templates
    └── logo.svg

Where Skills Live

Skills can be stored in multiple locations depending on the tool:

• Project skills: .github/skills/, .claude/skills/, or .agents/skills/
• Personal skills: ~/.copilot/skills/, ~/.claude/skills/, or ~/.agents/skills/
• Installable skills: npx skills add https://docs-url (Vercel's skills CLI)

AGENTS.md Templates

Copy the template closest to your stack. Delete lines that do not apply. A shorter, accurate file outperforms a comprehensive, generic one.

Next.js / React / TypeScript

# Project Name

Next.js 15 App Router, React 19, TypeScript, Tailwind CSS, Drizzle ORM, Bun.

## Commands

- `bun run dev`: Dev server (port 3000)
- `bun run build`: Production build
- `bun run test`: Vitest suite
- `bunx vitest run src/path/to/test.ts`: Single test file
- `bun run db:push`: Push Drizzle schema changes
- `bun run lint`: ESLint

## Architecture

- /src/app/          App Router pages and layouts
- /src/components/   React components (named exports only)
- /src/lib/          Utilities, DB client, helpers
- /src/lib/db/       Drizzle schema and migrations
- /src/actions/      Server actions (all mutations go here)

## Code Style

- Server Components by default. Client components only for interactivity.
- ES modules (import/export). No CommonJS.
- No default exports except page.tsx and layout.tsx.
- Tailwind for styling. No CSS modules.

## Rules

- Mutations through server actions, not API routes.
- All DB access through Drizzle ORM in server components/actions.
- Run typecheck before committing: bun run typecheck.
- Never commit .env files.

Python / FastAPI

# Project Name

FastAPI, Python 3.12, PostgreSQL, SQLAlchemy 2.0, Alembic, uv.

## Commands

- `uv run dev`: Dev server (port 8000)
- `uv run pytest tests/ -v`: Full test suite
- `uv run pytest tests/unit/test_handlers.py::test_create -v`: Single test
- `uv run ruff check --fix .`: Lint
- `alembic upgrade head`: Migrations

## Architecture

- /app/api/v1/       Route handlers (thin, delegate to services)
- /app/services/     Business logic
- /app/models/       SQLAlchemy models
- /app/schemas/      Pydantic v2 schemas
- /app/repositories/ Data access (repository pattern)

## Rules

- Type hints on all functions. Async handlers by default.
- Handlers delegate to services. No business logic in routes.
- All DB access through repositories. No raw SQL.
- Return { data, error } shape from all endpoints.
- Use dependency injection for DB sessions.
- Never modify /app/legacy/. Sync code, intentionally.

Monorepo

# Monorepo Name

Turborepo, pnpm workspaces. Frontend (Next.js) + API (Express) + shared packages.

## Commands

- `pnpm dev`: Start all services
- `pnpm build`: Build all packages
- `pnpm test`: Run all tests
- `turbo run test --filter=@app/api`: Test single package

## Structure

- /apps/web/       Next.js frontend (see apps/web/AGENTS.md)
- /apps/api/       Express API (see apps/api/AGENTS.md)
- /packages/ui/    Shared React components
- /packages/db/    Drizzle schema, shared across apps
- /packages/types/ Shared TypeScript types

## Rules

- Shared types in @app/types. Never duplicate type definitions.
- Import shared packages by name: import { Button } from '@app/ui'
- Never use relative paths across package boundaries.
- Each package has its own AGENTS.md for package-specific rules.
- DB schema changes require migrations in both dev and test databases.

SKILL.md Template

---
name: my-skill
description: >
  When to use: [specific trigger condition].
  When NOT to use: [explicit exclusion].
user-invocable: true
disable-model-invocation: false
---

# Skill Name

## Prerequisites

- [Required tools, access, or state]

## Steps

1. [First action with exact command]
2. [Second action]
3. [Verification step]

## Rules

- [Constraint 1]
- [Constraint 2]

## Examples

[One real example showing input and expected output]

FAQ

Should I use AGENTS.md or CLAUDE.md?

If you use multiple coding agents, use AGENTS.md for shared instructions and CLAUDE.md for Claude-specific features (@imports, skills, hooks). If you only use Claude Code, CLAUDE.md alone is sufficient since it has more features. Claude Code reads both files when both are present. See our CLAUDE.md guide for detailed Claude Code configuration.

How long should AGENTS.md be?

Start with 20 to 30 lines. The best files from the GitHub analysis of 2,500 repositories were concise and specific. Codex enforces a 32 KiB cap and silently truncates beyond it. Shorter files performed better in the Princeton study because agents spent less time parsing instructions and more time on the task.

Can I have multiple AGENTS.md files in one repository?

Yes. Nested AGENTS.md files provide directory-specific context. The agent reads the nearest file to the code being edited. Root-level rules apply everywhere; subdirectory rules override for that subtree. OpenAI's Codex repository uses 88 AGENTS.md files across its directory structure.

Does AGENTS.md replace documentation?

No. AGENTS.md complements your README and docs. It contains agent-specific context that would clutter human documentation: exact test flags, architectural constraints an agent needs to follow, files it should never modify. Keep your README for humans, AGENTS.md for agents.

Should I auto-generate AGENTS.md?

Be careful. The second research study found that LLM-generated AGENTS.md files reduced success rates by 2% and increased cost by 23%, primarily because they duplicated content already available in the repository. Human-written files that contain genuinely non-obvious information performed better. Use /init or a generator as a starting point, then aggressively edit and trim.