agent-documentation

name	agent-documentation
description	Standards for creating AGENTS.md files that guide AI coding agents working with your codebase. Use when creating instructions for AI agents to follow project conventions, setup, and workflows.

AGENTS.md Documentation

This skill provides standards for creating AGENTS.md files - dedicated instructions for AI coding agents working with your codebase.

What is AGENTS.md?

AGENTS.md is the "README for AI agents" - a machine-readable guide that provides explicit instructions for AI coding tools (like Claude, Copilot, Cursor) working with your project. Unlike README.md (for humans), AGENTS.md gives AI agents unambiguous, step-by-step guidance.

Purpose

• Centralized Instructions: Single source of truth for all AI agents
• Explicit Guidance: Clear setup commands, coding standards, testing workflows
• Project Context: Architecture decisions, conventions, constraints
• Consistency: Ensures AI-generated code matches project standards

AGENTS.md Structure

Based on real-world examples, a well-structured AGENTS.md follows this pattern:

# ProjectName - Development Guide

**Stack**: [Tech stack components]
**Principles**: [Core development principles, e.g., SOLID, KISS, YAGNI]

## Project Overview

[Brief description of architecture and approach]

## Repository Structure

- `path/to/main/`: [Description]
- `path/to/tests/`: [Description]
- `path/to/config/`: [Description]

## Key Commands

```bash
# Core commands
[build command]
[test command]
[format command]

# Additional tools
[migration/deployment commands]
[additional commands]

Quality Gates (Required)

Define the quality standards that must be met:

Code Quality

• Build succeeds without errors
• All tests pass
• Code formatting/linting passes
• No compiler warnings

Testing Requirements

• Integration tests for key workflows (favor sociable tests over isolated unit tests)
• Avoid excessive mocking - test real collaborations
• All edge cases and error paths covered

Code Review Standards

• Follows project conventions
• No code smells or anti-patterns
• Proper error handling
• Security considerations addressed

Coding Conventions (Optional)

[Project-specific coding standards]

Testing Guidelines (Optional)

[Testing expectations]

## Key Sections Explained

### 1. Title and Metadata (Required)
**Format**: `# ProjectName - Development Guide`

Include **Stack** and **Principles** at the top for quick reference.

### 2. Project Overview (Required)
Brief architectural summary - what type of project, key technologies, approach.

### 3. Repository Structure (Required)
Map of directories with brief descriptions. Helps agents understand where code lives.

### 4. Key Commands (Required)
Copy-paste commands for:
- Building the project
- Running tests
- Formatting code
- Database migrations or other critical operations

### 5. Quality Gates (Required)
Define quality standards that code must meet:
- **Code Quality**: Build, test, lint requirements
- **Testing Requirements**: Coverage thresholds, test types needed
- **Code Review Standards**: Conventions, patterns, security checks

### 6. Optional Sections
Add as needed:
- **Coding Conventions**: Project-specific rules
- **Testing Guidelines**: Reference separate tests/AGENTS.md for detailed testing guidelines

## Best Practices

### Start with Essentials
Include at minimum: Stack, Principles, Project Overview, Repository Structure, and Key Commands.

### Be Explicit and Specific
❌ "Set up the environment"  
✅ "npm install && cp .env.example .env"

❌ "Write good tests"  
✅ "Write integration tests for all API endpoints, test real collaborations"

### Use Exact Commands
Provide copy-paste ready commands. AI agents will execute them literally.

### Keep It Updated
Review and update AGENTS.md when project structure or conventions change.

## Integration with Claude Code

AGENTS.md works alongside Claude Code agents:
- Claude Code agents can reference AGENTS.md for project context
- Use AGENTS.md for project-specific conventions
- Use agent specifications (.md files) for agent-specific behavior

## Complete Example

```markdown
# StockToolset - Development Guide

**Stack**: .NET 10, ASP.NET Core Minimal APIs, .NET Aspire 13, PostgreSQL, PGMQ.
**Principles**: SOLID, KISS, YAGNI. Consistency over innovation.

## Project Overview

Cloud-native .NET 10 modular monolith using Vertical Slice Architecture, 
Aspire 13, PostgreSQL, and PGMQ.

## Repository Structure

- `StockStorage/src/`: Main app (Features/, Database/, Infrastructure/)
- `StockStorage/tests/`: Unified test project (Unit, Integration, System). **See `StockStorage/tests/AGENTS.md`**.
- `StockStorage.AppHost/`: .NET Aspire orchestration
- `StockStorage.ServiceDefaults/`: Shared Aspire defaults

## Key Commands

```bash
# Core
dotnet build
dotnet test # Requires Docker
dotnet format

# EF Core
dotnet ef migrations add <MigrationName>
dotnet ef database update

Testing

Refer to StockStorage/tests/AGENTS.md for all testing guidelines.

• Stack: TUnit, AwesomeAssertions, Testcontainers.
• Categories: Unit, Integration, System.

Quality Gates

Code Quality

• dotnet build succeeds with zero warnings
• dotnet format shows no formatting issues
• All tests pass (dotnet test)

Testing Requirements

• Integration tests for key workflows (favor sociable tests)
• Avoid excessive mocking - test real collaborations
• All edge cases and error paths tested

Code Review Standards

• Follows Vertical Slice Architecture
• SOLID, KISS, YAGNI principles applied
• No code duplication
• Proper error handling and logging

Coding Conventions

• Follow SOLID, KISS, YAGNI principles
• Consistency over innovation
• Use Vertical Slice Architecture per feature

## Further Reading

- [AGENTS.md Specification](https://agents.md/)
- [GitHub's AGENTS.md Guide](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)
- [OpenAI AGENTS.md Repo](https://github.com/openai/agents.md)