Create AGENTS.md

Guide for creating AGENTS.md files for project-specific inline rules.

When to Use AGENTS.md

• •Small, project-specific instructions that should be committed in the repo
• •Folder-scoped rules for specific directories
• •Package-specific instructions in monorepos
• •Test-specific guidance in test directories

When NOT to Use AGENTS.md

• •Reusable knowledge across projects → Use skills
• •Large documentation → Use skills with references
• •Complex workflows → Use skills with scripts

AGENTS.md Structure

AGENTS.md is a simple markdown file without metadata:

# Project Instructions

## Code Style

- Use TypeScript for all new files
- Prefer functional components in React
- Use snake_case for database columns

## Architecture

- Follow the repository pattern
- Keep business logic in service layers

Location

• •Project root: AGENTS.md – Primary, inline instructions and references for the whole project (commands, tech stack, testing, code style, architecture, safety boundaries).
• •Subdirectories: subdirectory/AGENTS.md – Folder- or package-scoped instructions when local behavior meaningfully diverges from the root (e.g., a specific package, service, or test tree).
• •Nested support: Agents typically combine instructions from the closest AGENTS.md with parent ones; keep root general and use nested AGENTS.md only where you truly need more specific rules.

Best Practices

• •Keep AGENTS.md files small and focused
• •Use for project-specific conventions
• •Prefer short, concrete references over long prose:
  • •Link to project docs, specs, and runbooks
  • •Point to example files or directories (e.g., see src/api/users.ts for canonical pattern)
  • •Include the most important commands with exact CLI invocations
• •Reference existing code examples when possible
• •Update as project evolves

References

For detailed best practices, see references/best-practices.md.