agents-md-writer

Writes effective AGENTS.md files — a "README for machines" with structured technical guidance for AI coding agents. Based on analysis of 2,500+ repositories, OpenAI Codex, and GitHub Copilot best practices.

When to Use

• Creating a new AGENTS.md for a project.
• Updating or reviewing an existing AGENTS.md.
• Converting CLAUDE.md / .cursorrules / copilot-instructions.md to AGENTS.md.
• Splitting a large AGENTS.md into hierarchical sub-files.
• Auditing whether an AGENTS.md is current (commands still work, structure still matches).

When NOT to Use

• Human-facing project documentation → write a README.md, not AGENTS.md.
• Skill authoring (SKILL.md files in ~/.zcode/skills/) → skill-creator (the official plugin version).
• Agent definition files (with tools:, skills:, color:) → they are a different schema.

Hard Rules

1. All AGENTS.md files must be ≤150 lines. Root and sub-files share the same limit. Larger → condense or split.
2. Six core areas every AGENTS.md must cover: Commands, Testing, Structure, Style, Git, Boundaries.
3. Never include secrets. Reference where they live, not the values.
4. Commands must be copy-pasteable. Exact commands with flags, not "run the tests."
5. File-scoped commands first. Full suite only as fallback.
6. Code examples over explanations. One snippet beats three paragraphs.
7. Document how skills are activated in a dedicated section, because agents need to know how to load them.
8. Complements README.md: AGENTS.md is for machines; do not duplicate human-oriented content.
9. Treat AGENTS.md as code, not documentation: update on PR, audit quarterly, update immediately when commands/structure change, and update when the agent makes the same mistake twice.

Examples

Good vs. vague command:

# Good — file-scoped, exact flags
pnpm vitest run src/lib/format.test.js

# Vague — agent has to guess
"run the tests"

Good vs. bad Boundaries:

## Boundaries
- **Always:** Run tests before finishing, write scratch files to tmp/
- **Ask first:** Adding dependencies, modifying package.json
- **Never:** git commit, git push, create files outside the defined structure

Six Core Areas

Skills Section in AGENTS.md

Every AGENTS.md should include a skills section explaining how skills are activated:

## Skills (Activate on Demand)

Skills are loaded via the `skill` tool. When a task matches a skill's
description, call `skill({ name: "skill-name" })` to load its instructions.

| Skill | When |
|-------|------|
| **skill-name** | Trigger description |

Separate global skills from project-local skills when both exist.

Workflow

1. Evaluate

Assess the current AGENTS.md structure and content: is it hierarchical or simple? What patterns exist? What must be preserved?

2. Analyze

Detect build system, test framework, package manager, tech stack from package.json, lockfiles, folder structure, and any existing config.

3. Plan

Determine changes needed while preserving existing patterns. Identify what goes in the root vs. sub-AGENTS.md.

4. Write

Commands first, then structure, style, boundaries. Keep the file lean.

5. Check Size

If >150 lines → condense or split. Do not ship an oversized AGENTS.md.

6. Validate

Can an agent setup, test, build, and deploy from this file alone? If not, the file is incomplete.

Evaluation Guidelines

Before making changes to an AGENTS.md file, evaluate its current state:

1. Structure Type: Determine if it's hierarchical or simple.
2. Consistency Check: Identify patterns to maintain.
3. Change Impact: Assess what needs to be preserved.

Hierarchical vs Simple

Evaluation Process

1. Read the entire AGENTS.md file.
2. Check line count and structure.
3. Identify existing patterns and conventions.
4. Determine if changes should maintain hierarchy or simplify.
5. Note sections that should be preserved or updated.

Maintaining Hierarchical Consistency

When working with hierarchical AGENTS.md structures:

1. Root File: Keep general rules, commands, and boundaries.
2. Sub-files: Maintain domain-specific content.
3. Links: Use cross-references between files.
4. Avoid Duplication: Ensure information isn't repeated across files.
5. Size Limits: All files ≤150 lines (root and sub-files share the same limit).

Transition Guidelines

When converting between hierarchical and simple structures:

1. Hierarchical to Simple: Consolidate content from sub-files; remove redundancy; preserve critical sections.
2. Simple to Hierarchical: Identify logical domains; create sub-files; keep root file general.

Writing Style for AGENTS.md

• Be specific: "React 18 with TypeScript, Vite, Tailwind" not "React project".
• Show examples: Good code vs. bad code with concrete snippets.
• Put commands early: Setup and test commands before explanations.
• Think like onboarding: What would a new teammate need for their first PR?
• Iterate: Update when the agent makes the same mistake twice.

Common Mistakes

References

• references/ecosystem.md — Adoption, tool compatibility, parsing differences (Codex, Copilot, Cursor, Claude).
• references/patterns.md — Codex workflow patterns, GitHub agent best practices, prompt structure, maintenance.
• references/security.md — Security deep dive, scanning tools, CI/CD gates, deployment validation.
• references/template-minimal.md — Simple project template (~85 lines).
• references/template-comprehensive.md — Complex project template with tech patterns (~400 lines).

Quick Reference

AGENTS.md = Commands + Structure + Style + Testing + Git + Boundaries.
All files ≤150 lines. Commands first. Show examples. Never secrets.
Split when >150 lines or monorepo. Nearest file wins.