AGENTS.md Authoring Guide (Mark)

Goal: Write effective, high-signal-to-noise AGENTS.md files that outperform skills-based approaches (100% vs 79% pass rate based on Vercel research).

When to Use This Skill

• •Creating a new AGENTS.md file
• •Updating an existing AGENTS.md
• •Optimizing agent context for better performance
• •Converting from skills-based approach to AGENTS.md
• •Setting up project documentation for AI agents
• •Monorepo with nested AGENTS.md files

When NOT to Use This Skill

• •Writing end-user documentation (use writing-docs-majo)
• •Creating a new skill (use skill-authoring-majo)
• •Small project with obvious conventions (AGENTS.md may be overkill)
• •Documentation for non-agent consumption

Process

1. •Check existing AGENTS.md - Read current file if it exists
2. •Measure current token count - Target root file ≤ 800 tokens
3. •Apply 6-Core-Areas Framework:
   • •Commands (~80 tokens) - Exact copy-paste commands
   • •Testing (~50 tokens) - Framework, location, coverage, run command
   • •Project Structure (~50 tokens) - Strategic hints only
   • •Code Style (~75 tokens) - One real example with positive & negative
   • •Git Workflow (~40 tokens) - Commit format, branch naming, PR requirements
   • •Boundaries (~50 tokens) - Always/Ask/Never three-tier system
4. •Use real code examples - From the actual project, not templates
5. •Apply progressive disclosure - Link to detailed docs, don't inline
6. •Add three-tier boundaries - ALWAYS/ASK FIRST/NEVER format
7. •Verify token count - Ensure root ≤ 800 tokens
8. •Test with real tasks - Run agents on actual work, observe mistakes
9. •Iterate - Update AGENTS.md after each agent mistake
10. •Update AGENTS.md - Document that AGENTS.md was modified

Constraints

• •ALWAYS keep root AGENTS.md ≤ 800 tokens - Maximize signal-to-noise
• •ALWAYS minimize root file - Strategic structure over exhaustive docs
• •ALWAYS use six-core-areas framework - Commands, Testing, Structure, Style, Git, Boundaries
• •ALWAYS use three-tier boundaries (Always/Ask/Never) - More effective than flat lists
• •NEVER include file structure documentation - Agents infer this; it drifts
• •NEVER duplicate README/docs - Link instead
• •NEVER use vague guidance - "Be careful" → "Never do X without..."
• •UPDATE immediately after agent mistakes - Track in git

Write effective AGENTS.md files that outperform skills-based approaches.

Core Principle

Minimize root file; maximize signal-to-noise ratio through strategic structure, not exhaustive documentation.

AGENTS.md is loaded on every agent request. Keep it concise but information-dense.

AGENTS.md vs Skills: When to Use Each

Key Finding (Vercel Research): AGENTS.md achieved 100% pass rate vs 79% with skills, even with explicit skill invocation instructions.

Why AGENTS.md Wins:

1. •No decision point - always loaded
2. •Consistent availability - in system prompt every turn
3. •No ordering issues - no "read docs first vs explore project first" dilemma

Use AGENTS.md for:

• •Domain concepts specific to your project
• •Non-obvious conventions agents can't infer
• •Executable commands with exact flags
• •Version-matched framework documentation
• •Project boundaries and gotchas

Use Skills for (see skill-authoring-majo):

• •Cross-project patterns
• •Large content requiring progressive disclosure
• •Workflows that don't fit in AGENTS.md
• •When context bloat is a concern

Six-Core-Areas Framework

Structure your AGENTS.md around six key areas (300-800 tokens total):

1. Commands (~80 tokens)

Exact, copy-paste-ready commands with flags.

## Build Commands

```bash
# Build the package
pnpm build

# Development mode
pnpm dev

# Run tests
pnpm test

**Why**: Agents reference repeatedly; vague instructions create clarification loops.

### 2. Testing (~50 tokens)

Framework, location, coverage minimum, run command.

```markdown
## Testing

Framework: Jest
Location: tests/
Coverage: 80% minimum
Run: pnpm test

Don't include philosophy or lengthy examples.

3. Project Structure (~50 tokens)

Strategic hints, not exhaustive paths.

## Project Structure

src/ — Application code (READ)
tests/ — Unit/integration tests
docs/ — Markdown (WRITE)

Agents discover files well; structure drifts. Skip detailed file listings.

4. Code Style (~75 tokens)

One real repo example showing BOTH positive and negative patterns.

## Code Style

```python
# GOOD: Use retry() for polling/waiting
from next_test_utils import retry
await retry(async () => {
    const text = await browser.elementByCss('p').text()
    expect(text).toBe('expected value')
})

# AVOID: Don't use setTimeout for waiting
await new Promise((resolve) => setTimeout(resolve, 1000))

One example > three paragraphs of description. Show the anti-pattern too.

### 5. Git Workflow (~40 tokens)

Commit format, branch naming, PR requirements.

```markdown
## Git Workflow

Commits: feat(scope): description (Conventional Commits)
Branches: feature/*, bugfix/*, docs/*
PRs: lint ✓, tests ✓, focused diff

6. Boundaries (~50 tokens)

Three-tier system: Always/Ask/Never (more effective than flat "don't" lists).

## Boundaries

ALWAYS: Run tests before commits; follow naming conventions
ASK FIRST: Before schema changes; before new dependencies; before CI/CD changes
NEVER: Commit secrets; edit node_modules; remove failing tests without approval

Why three tiers: Eliminates agent ambiguity better than flat lists.

Token Efficiency Techniques

Progressive Disclosure

Link to detailed docs instead of inlining:

Detailed patterns: [see docs/api.md §3.2]
Quick reference: Endpoints return { "data": {...}, "error": null }

Compression

Use pipe-delimited format for complex concepts. Vercel achieved 80% reduction (40KB → 8KB):

[Docs Index]|root: ./.docs
|01-getting-started:{installation.md,project-structure.md}
|02-api:{routing.md,caching.md}

Hierarchical Summarization

Extended TOC at top; full sections below. Keeps frequent tasks in focus.

What to Include vs Exclude

INCLUDE:

• •Domain concepts specific to your project ("Organization" vs "Workspace")
• •Non-obvious conventions agents can't infer ("Use composition over inheritance")
• •Executable commands with exact flags
• •Boundaries and gotchas from real experience ("This library has a memory leak in v3.2.1")
• •Real code examples from your repo (not templates)

EXCLUDE:

• •File structure documentation (agents infer this; it drifts)
• •Duplicates of README/docs (link instead)
• •Abstract best practices ("Write clean code")
• •Lengthy prose (every section = 10-second scan)
• •Vague guidance ("Be careful with X" → "Never do X without...")
• •Generic advice that overlaps across projects

Example AGENTS.md Structure

Based on Vercel's Next.js AGENTS.md:

# Project Development Guide

## Quick Start

```bash
# Install dependencies
pnpm install

# Start development
pnpm dev

# Run tests
pnpm test

Project Structure

src/ — Application code tests/ — Test files docs/ — Documentation

Build Commands

pnpm build      # Production build
pnpm dev        # Development server
pnpm test       # Run all tests
pnpm test:watch # Watch mode

Testing

Framework: Vitest Location: tests/ Coverage: 80% minimum

Writing Tests

// GOOD: Use retry() for polling
await retry(async () => {
    expect(await page.text()).toBe('done')
})

// AVOID: Don't use setTimeout
await new Promise(r => setTimeout(r, 1000))

Code Style

• •TypeScript strict mode
• •Prettier for formatting
• •ESLint for linting

Git Workflow

Commits: feat(scope): description Branches: feature/, bugfix/ PRs: tests pass, lint clean

Boundaries

ALWAYS: Run tests before push; update AGENTS.md after agent mistakes ASK FIRST: Before adding dependencies; before architectural changes NEVER: Commit .env files; modify generated code directly

Common Issues

• •Build fails after branch switch → Run pnpm build
• •Tests timeout → Check if dev server is running
• •Type errors → Run pnpm types to check

## Nested AGENTS.md (Monorepos)

For monorepos, use nested AGENTS.md files:

project/ ├── AGENTS.md # Global rules ├── packages/ │ ├── backend/ │ │ └── AGENTS.md # Backend-specific │ └── frontend/ │ └── AGENTS.md # Frontend-specific

Agents use the nearest AGENTS.md (like .gitignore). Keeps context tight and relevant.

## Iterative Refinement Process

1. **Start minimal**: Six-core-areas, ~400 tokens
2. **Run agents on real tasks**: Observe mistakes
3. **When agent misunderstands/fails**: Note it
4. **Add clarifying rule/example/boundary to AGENTS.md**
5. **Tell agent**: "I updated AGENTS.md. Given these new rules, refactor accordingly."
6. **Repeat**: Each iteration tightens spec, reduces future mistakes

**Example iterations**:
- Iteration 1: Agent uses old API → Add: "Use v2/users endpoint, not v1/users"
- Iteration 2: Agent skips validation → Add: "Always validate ID format"
- Iteration 3: Agent modifies tests when not asked → Add boundary: "Never modify tests unless explicitly asked"

## Anti-Patterns to Avoid

| Anti-Pattern | Problem | Fix |
|---|---|---|
| Vague rules | Agent asks clarifying questions (wasted tokens) | Be specific: "Never commit secrets" not "Be careful with secrets" |
| Outdated AGENTS.md | Agent ignores stale guidance or hallucinates | Update immediately after mistakes; track in git |
| Monolithic structure | Agent loads irrelevant context every task | Use nested AGENTS.md; progressive disclosure |
| Duplicate docs | Token waste; maintenance burden | Link instead of inlining |
| Abstract examples | Agents don't know how to apply guidance | Use real files: "copy DashForm.tsx" |
| Conflicting rules | Agent uncertain which rule applies | Use Always/Ask/Never tiers, not flat lists |

## Quick Checklist

- [ ] Root ≤ 800 tokens
- [ ] Six-core-areas framework present
- [ ] Three-tier boundaries (Always/Ask/Never)
- [ ] Real code examples (positive & negative)
- [ ] Links to external docs, not duplicates
- [ ] No file structure documentation
- [ ] No vague guidance
- [ ] Updated after every agent mistake
- [ ] Nested AGENTS.md for monorepos (if applicable)
- [ ] Progressive disclosure for large docs

## Testing Skills

- **Token count check**: Ensure root AGENTS.md ≤ 800 tokens (use wc or estimate)
- **Structure verification**: Confirm all 6 core areas are present
- **Boundary clarity**: Check Always/Ask/Never tiers are specific, not vague
- **Real examples test**: Verify code examples actually exist in the repo
- **Link validation**: Ensure linked docs exist and are accessible
- **Agent run test**: Perform a real task, verify agent follows AGENTS.md guidance
- **Iteration tracking**: Document each update and the mistake it fixed

## Integration with Other Skills

This skill extends `dev-standards-majo`. Always ensure `dev-standards-majo` is loaded for:
- AGENTS.md maintenance
- Universal code principles
- Documentation policies

Works alongside:
- `skill-authoring-majo` — For deciding when to use AGENTS.md vs create skills
- `task-planning-majo` — For planning AGENTS.md updates
- `git-majo` — For committing AGENTS.md changes
- `writing-docs-majo` — For writing documentation about AGENTS.md

## References

- Vercel Research: ["AGENTS.md outperforms skills in our agent evals"](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) (100% vs 79% pass rate)
- Next.js AGENTS.md: https://github.com/vercel/next.js/blob/canary/AGENTS.md
- agents.md specification: https://agents.md/