name: agents-md-creator
description: Create AGENTS.md files for AI agent context. Use when setting up project-level agent instructions, defining constraints, establishing conventions, or documenting agent-specific guidance.

AGENTS.md Creator

Create well-structured AGENTS.md files that give AI agents the context they need.

When This Triggers

• User wants to create an AGENTS.md file
• User is setting up agent instructions for a project
• User asks about AGENTS.md format or best practices
• User wants to document constraints or conventions for agents

What AGENTS.md Is For

A briefing file that tells agents:
- What domain this covers
- How to do work in this context
- What NOT to do
- Conventions to follow
- Gotchas to watch for

Template

# [Project/Domain Name]

## Context & Scope

[What this covers, boundaries of agent authority]

## Commands & Actions

[Exact commands, tools, or procedures to use]

## Architecture

[Overview of how things are organized]

## Constraints

[What the agent must NOT do]

## Conventions

[Naming, formatting, style rules]

## Gotchas

[Non-obvious pitfalls, edge cases]

Section Guidelines

Context & Scope

• Define what domain this AGENTS.md covers
• Set boundaries on agent authority
• Link to broader documentation if needed

Commands & Actions

• Use inline code for exact commands
• Be specific about tool usage
• Include expected outputs when helpful

Constraints

• Hard limits the agent must respect
• Things that should never happen
• Security or safety boundaries

Conventions

• Naming patterns (files, variables, etc.)
• Formatting rules
• Style guidelines specific to this context

Gotchas

• Non-obvious edge cases
• Common mistakes to avoid
• Domain-specific quirks

Best Practices

• Keep it short: ≤150 lines — long files bury signal
• Be concrete: Specific instructions > vague guidance
• One source of truth: Link to docs, don't duplicate
• Define success: How does the agent know it's done?
• Update it: Treat as living documentation

What Belongs in AGENTS.md

Good candidates:
- Default behaviors that should always apply
- High stability content unlikely to change
- Constraints where violation is a bug
- Rules about how work is done

Not good candidates:
- Invoked workflows → use slash commands
- Complex procedures → use skills
- Personal notes → keep as reference

Discovery

Agents find AGENTS.md by searching:
1. Current working directory
2. Parent directories up to project root
3. Sub-folders being worked on
4. User home directory (~/AGENTS.md)

Closer files take precedence.

See Also

references/agents-md-guide.md for detailed specs.