Agd Agents Md

AGENTS.md Format

AGENTS.md is a standardized markdown file that serves as a "README for AI coding agents" - providing dedicated, predictable context to help AI coding agents work effectively on a project.

Purpose

Unlike README.md (designed for humans), AGENTS.md contains:

• Build and test commands
• Code style guidelines
• Testing instructions
• Security considerations
• Any context a new teammate would need

Key principle: Give agents a clear, predictable place for instructions while keeping READMEs concise for human contributors.

Basic Structure

AGENTS.md is standard Markdown with no required fields:

# AGENTS.md

## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible

Simple First Approach

Default: Create one compact, lean AGENTS.md file. This satisfies most projects.

References folder (optional): Only create docs/agents/ when:

• Project has complex, project-specific patterns that need detailed explanation
• User explicitly wants separate reference files
• Content exceeds ~100 lines and cannot be condensed

Commands use AskUserQuestion to ask about references folder when appropriate.

Progressive Disclosure Pattern

Key Principle: Keep AGENTS.md lean by referencing detailed documentation instead of duplicating content inline.

Keep in AGENTS.md (inline):

• Essential commands (install, test, build)
• Critical conventions (quotes, semicolons, etc.)
• Security requirements (brief reminders)
• Brief project overview (1-2 sentences)

Move to references (only if needed, default: docs/agents/):

• Detailed architecture explanations
• Extensive code examples (>5 lines)
• Long-form documentation (>10 lines per section)
• Project-specific patterns and conventions

Example reference format:

## Testing instructions
- Unit tests: `pnpm test`
- E2E tests: `pnpm test:e2e`
See docs/agents/testing.md for detailed guidelines.

Cross-skill references: Use skill names instead of duplicating content from other domains:

## PR instructions
- Use Conventional Commits (see agd-conventional-commits skill)

Relative Path References for Subprojects

Use relative paths when referencing files within the same repository. This makes references portable and works from any subdirectory.

Syntax: Use paths relative to the file's location (e.g., ./relative/path/to/file.md)

Examples:

# In packages/api/AGENTS.md

## Architecture
See ../shared/architecture.md for shared patterns.

## Testing
See ../../docs/agents/testing.md for test guidelines.

Best practices:

• Use ./ for files in the same directory
• Use ../ to go up one directory level
• Use ../../ to go up two directory levels
• Keep paths short and intuitive

Cross-subproject references:

# In packages/web/AGENTS.md

## API Integration
See ../api/AGENTS.md for API conventions and patterns.

## Shared Components
See ../../packages/shared/components/ for shared UI components.

When to use:

• Documenting shared patterns between subprojects
• Referencing common utilities or libraries
• Linking to centralized documentation
• Avoiding duplication across monorepo structure

Implementation checklist:

• AGENTS.md under 100 lines (ideally 50-80)
• References folder only created if needed
• Essential commands remain inline

Recommended Sections

1. Project Overview: Brief description (1-2 sentences)
2. Dev Environment Setup: Essential commands
3. Testing Instructions: How to run and write tests
4. Code Style Guidelines: Conventions and patterns
5. PR/Commit Guidelines: Reference agd-conventional-commits skill
6. Security Considerations: Critical security reminders

See examples/basic-agents-md.md for a complete example.

Lifecycle Management

Commands

Decision Tree

No AGENTS.md exists? → Use init-agents-md
AGENT.md or other format exists? → Use migrate-agents-md
AGENTS.md exists but outdated? → Use update-agents-md

References Folder Decision

Commands use AskUserQuestion to ask about creating the references folder:

Ask when:

• Project has complex, project-specific patterns
• Content would benefit from detailed documentation
• User wants to add architecture diagrams, tutorials, etc.

Default path: docs/agents/

See references/lifecycle.md for detailed processes.

Agent Compatibility

AGENTS.md works across AI coding agents: OpenAI Codex, Cursor, Claude Code, Aider, Google Jules, Factory.

Symlinks: Create symbolic links for agent-specific files to maintain one source of truth:

• Claude Code: ln -s AGENTS.md CLAUDE.md
• Cursor: ln -s AGENTS.md .cursorrules
• Windsurf: ln -s AGENTS.md .windsurfrules

See references/agent-compatibility.md for tool-specific configs and monorepo patterns.

Migration

Automated

Use /agd-migrate-agents-md [source-file] to auto-detect and convert AGENT.md, .cursorrules, etc.

Manual

mv AGENT.md AGENTS.md
ln -s AGENTS.md AGENT.md  # backward compatibility

See examples/migration-example.md for a complete before/after example.

Best Practices

Do

• Keep it concise and scannable
• Use code blocks for commands
• Include actual commands agents can execute
• Treat it as living documentation
• Apply progressive disclosure

Don't

• Don't duplicate README content verbatim
• Don't include vague instructions
• Don't make it too long (agents work better with focused context)
• Don't forget to update as project evolves

Validation

After creating, migrating, or updating AGENTS.md, verify:

• All commands are executable
• File is concise (under 100 lines)
• Progressive disclosure applied
• No placeholder content
• Essential commands remain inline

See references/validation.md for comprehensive validation checklist.

Agent Behavior Rules

References

• references/lifecycle.md - Detailed create/update/migrate processes
• references/agent-compatibility.md - Tool configs, symlinks, monorepo patterns
• references/validation.md - Comprehensive validation checklist
• examples/basic-agents-md.md - Complete working example
• examples/migration-example.md - Before/after migration example