AGENTS.md vs. Agent Skills: Understanding the Difference

Introduction

AI coding agents need more than a task description to work effectively. They also need information about the repository, its architecture, coding conventions, testing requirements, and the procedures they should follow when performing specialized tasks.

Two mechanisms help provide this context: AGENTS.md files and Agent Skills, commonly defined through a "SKILL.md" file.

Although both can contain instructions for AI agents, they address different problems. Understanding their roles helps developers build better-organized repositories and avoid duplicating instructions unnecessarily.

What Is AGENTS.md?

"AGENTS.md" is an open Markdown-based format for providing coding agents with project-specific instructions.

It acts as a reference guide explaining how an agent should work within a repository. Depending on the tools being used, the agent may discover instructions at the repository root or in nested directories.

Typical content includes:

- Project architecture and directory structure.
- Dependency installation and development commands.
- Coding conventions and naming rules.
- Testing and validation requirements.
- Security constraints and prohibited operations.
- Pull request and code review expectations.

For example:

# AGENTS.md

## Project Guidelines
- Use TypeScript for new frontend modules.
- Follow the existing service-layer architecture.
- Avoid modifying generated files.

## Testing
- Run pnpm test before submitting changes.
- Run pnpm lint after modifying source files.

## Security
- Never commit API keys or credentials.

The purpose is to give the agent persistent guidance about the project rather than describing every step of a particular task.

The exact way instructions are discovered and applied depends on the coding agent and its implementation.

What Are Agent Skills?

Agent Skills package reusable instructions and supporting resources for performing specific tasks.

A skill typically consists of a directory containing a "SKILL.md" file. It may also include scripts, reference documents, templates, and other supporting files.

Unlike project-wide instructions, a skill focuses on a particular capability or procedure.

Examples include:

- Reviewing code for security vulnerabilities.
- Generating API documentation.
- Performing database migration reviews.
- Creating standardized release notes.
- Analyzing performance bottlenecks.
- Preparing structured test plans.

A simplified skill could look like this:

.agents/
└── skills/
└── code-review/
├── SKILL.md
├── references/
│ └── review-checklist.md
└── scripts/
└── check-files.py

Its "SKILL.md" might define the task and workflow:

---
name: code-review
description: Review code changes for correctness, security,
maintainability, and missing tests.
---

# Code Review Workflow

1. Identify the purpose of the changes.
2. Inspect the affected files and their dependencies.
3. Check error handling and security implications.
4. Verify that appropriate tests exist.
5. Report actionable findings with file references.

This example illustrates the general structure; exact requirements and supported directories vary by implementation.

Skills can be reused across projects when they are designed to avoid unnecessary assumptions about a particular repository.

Key Differences

Aspect| AGENTS.md| Agent Skills
Primary purpose| Explain how to work in a project| Define how to perform a specific task
Scope| Repository-wide or directory-specific guidance| Focused, reusable capability
Typical content| Architecture, commands, conventions, constraints| Procedures, checklists, references, scripts
Structure| A Markdown file| A skill directory containing "SKILL.md"
Activation| Read according to the agent's instruction-discovery rules| Discovered and used according to the agent's skill-loading mechanism
Reusability| Often tailored to a repository| Can be shared across compatible projects and tools

One important distinction is that "AGENTS.md" does not automatically behave identically across every AI coding tool. Similarly, not every tool discovers or activates skills in exactly the same way.

Can They Be Used Together?

Yes. In many projects, using both is more effective than choosing only one.

Consider a React application with a Python backend.

The repository's "AGENTS.md" could explain the overall architecture, identify the frontend and backend directories, document installation commands, and establish testing requirements.

A dedicated "code-review" skill could provide a detailed review process. A separate "database-migration-review" skill could explain how to evaluate schema changes, data integrity, rollback strategies, and migration safety.

The division of responsibility is straightforward:

- AGENTS.md establishes the project's rules and context.
- Skills provide specialized procedures that can be applied when relevant.

This separation keeps general instructions easier to maintain while allowing specialized workflows to evolve independently.

Common Mistakes to Avoid

Putting Everything in AGENTS.md

An excessively long instruction file can become difficult to maintain and may consume unnecessary context. Keep essential project-wide guidance in the main file and move detailed, repeatable procedures into suitable skills or reference documents.

Making Skills Depend on Hidden Assumptions

A reusable skill should clearly state its prerequisites and explain which inputs it needs. If it assumes a particular framework, directory structure, or tool, those requirements should be explicit.

Duplicating Conflicting Instructions

If the same procedure appears in multiple files, the instructions can become inconsistent over time. Keep project rules in one authoritative location and reference reusable procedures where appropriate.

Assuming Every Tool Supports Both Formats

Before adopting a convention, verify that the intended coding agent supports it. A file's presence in a repository does not guarantee that every agent will discover or follow it.

Conclusion

"AGENTS.md" and Agent Skills are complementary mechanisms for guiding AI coding agents.

Use "AGENTS.md" to communicate project-specific expectations and constraints. Use skills to package repeatable, specialized workflows that can be invoked when needed.

Together, they provide a practical foundation for organizing AI development instructions without turning every task prompt into a lengthy set of rules.

Further Reading

- "AGENTS.md — Official Project" (https://agents.md/)
- "Agent Skills — OpenAI Documentation" (https://developers.openai.com/api/docs/guides/tools-skills)
- "AGENTS.md vs. Skills — CircleCI" (https://circleci.com/blog/agents-md-vs-skills/)