Agents Md

Agents Md

This skill should be used when the user asks to "create AGENTS.md", "update AGENTS.md", "maintain agent docs", "set up CLAUDE.md", or needs to keep

Category: development Source: getsentry/skills

What Is This?

Overview

AGENTS.md is a structured documentation file designed to provide AI coding agents with the essential context they need to operate effectively within a software project. Rather than overwhelming agents with exhaustive documentation, the format enforces a minimal, high-signal approach that delivers only the most critical instructions. The file serves as the canonical source of truth for agent-facing documentation, ensuring consistent behavior across automated workflows.

The core philosophy behind AGENTS.md is that modern AI agents are capable systems that do not require hand-holding. Verbose documentation introduces noise, increases the chance of conflicting instructions, and dilutes the importance of genuinely critical rules. A well-maintained AGENTS.md file targets under 60 lines and never exceeds 100, keeping every line purposeful and actionable.

This skill also applies to CLAUDE.md, a functionally equivalent file used in Anthropic Claude-based agent workflows. Both formats follow the same principles: concise structure, clear commands, and zero redundancy. Maintaining these files correctly is a foundational practice for teams building reliable AI-assisted development pipelines.

Who Should Use This

  • Backend and full-stack developers who integrate AI coding agents into their daily development workflows and need a reliable way to communicate project conventions.
  • DevOps and platform engineers who configure automated agent pipelines and require consistent, machine-readable project instructions.
  • Engineering team leads responsible for standardizing how AI tools interact with a shared codebase across multiple contributors.
  • Open source maintainers who want to provide clear onboarding context for AI agents contributing to or reviewing their repositories.

Why Use It?

Problems It Solves

  • Inconsistent agent behavior caused by missing or scattered project context, leading to agents making incorrect assumptions about code style, testing requirements, or deployment steps.
  • Instruction overload from lengthy documentation files that bury critical rules in unnecessary prose, reducing agent compliance with key directives.
  • Duplicated or conflicting guidance spread across README files, wikis, and inline comments that agents cannot reliably reconcile.
  • Onboarding friction when new agents or automated tools are introduced to a project without a single authoritative reference point.

Core Highlights

  • Enforces a strict line limit, targeting under 60 lines and never exceeding 100
  • Provides a single canonical file for all agent-facing instructions
  • Compatible with multiple agent frameworks, including Claude-based workflows via CLAUDE.md
  • Prioritizes high-signal content, removing anything an agent can reasonably infer
  • Reduces cognitive load for both agents and the humans maintaining the file
  • Supports clear command examples for build, test, and lint workflows
  • Encourages regular review cycles to keep instructions current and accurate

How to Use It?

Basic Usage

Create an AGENTS.md file in the root of your repository. The structure should be flat and direct, using short sections with imperative language.

## Project Instructions

## Setup
Run `npm install` to install dependencies.

## Testing
Run `npm test` to execute the full test suite.
Run `npm run test:unit` for unit tests only.

## Linting
Run `npm run lint` before committing. Fix all errors before opening a pull request.

## Conventions
- Use TypeScript strict mode
- Prefer named exports over default exports
- All new functions require JSDoc comments

Specific Scenarios

Scenario 1: Monorepo with multiple services. Add a root-level AGENTS.md with global rules, then place service-specific AGENTS.md files in each subdirectory. Agents should read both, with the local file taking precedence.

Scenario 2: Migrating from a verbose README. Extract only the commands and conventions that agents cannot infer from the codebase itself. Discard explanatory prose and historical context.

Real-World Examples

A Python project might include the following in its AGENTS.md to communicate testing and formatting requirements clearly.

## Testing
Run `pytest` from the project root. All tests must pass before merging.

## Formatting
Run `black .` and `isort .` before committing. CI will reject unformatted code.

When to Use It?

Use Cases

  • Setting up a new repository that will use AI coding agents for development tasks
  • Standardizing agent behavior across a team working on a shared codebase
  • Replacing scattered documentation with a single authoritative agent reference
  • Configuring Claude-based agents using the equivalent CLAUDE.md format
  • Auditing existing agent documentation for verbosity and outdated instructions
  • Onboarding automated pull request review or code generation tools
  • Establishing project conventions that agents must follow consistently

Important Notes

Requirements

  • The file must be placed in the repository root to ensure agents locate it reliably.
  • Content must stay under 100 lines, with 60 lines as the recommended target.
  • All commands listed must be tested and verified to work in the current project environment.