AGENTS.md Pattern

Persistent instructions for AI agents.

Instead of typing the same instructions every time, you can save them in a file. AI agents read this file automatically and follow your rules.

---

The Problem

You find yourself repeating instructions:

• "Don't change technical terms"
• "Use British spelling"
• "Format output as a table"
• "Preserve citation formats"

This is tedious and error-prone. What if you could write these once?

---

The Solution

Create a file called AGENTS.md (or CLAUDE.md) in your project root:

# Project Instructions

When proofreading documents in this project:

1. Fix grammar, spelling, and punctuation errors
2. Preserve the author's voice and style
3. Don't change technical terms or proper nouns
4. Use British spelling (colour, behaviour, etc.)
5. Keep citations in their original format

For detailed instructions on specific tasks, see:
- Grammar check: `.agents/skills/grammar-check.md`
- Entity extraction: `.agents/skills/entity-extraction.md`

When you start Claude Code in this folder, it automatically reads this file.

---

Hierarchical Organization

For complex projects, organize instructions in layers:

project/
├── AGENTS.md                 # General rules (always applied)
└── .agents/
    └── skills/
        ├── grammar-check.md  # Detailed grammar instructions
        ├── entity-extraction.md
        └── annotate-pdf.md

The main file sets general rules. Specialized files handle specific tasks.

---

Example: Grammar Check Skill

.agents/skills/grammar-check.md:

---
name: grammar-check
description: Check grammar, spelling, and phrasing.
---

## Instructions

When checking grammar:

1. Read the specified file
2. Identify errors:
   - Grammar mistakes
   - Spelling errors
   - Awkward phrasing
3. Present findings in a table:

| Line | Original | Suggested | Reason |
|------|----------|-----------|--------|

4. Wait for approval before making changes
5. Apply approved changes only

## Constraints

- Never change direct quotes
- Preserve technical terminology
- Maintain citation formats (Chicago, MLA, etc.)

---

Why This Works

Without AGENTS.md	With AGENTS.md
Repeat instructions every session	Set once, apply always
Inconsistent behavior	Consistent behavior
Prompts get lost	Instructions are version-controlled
Hard to share with collaborators	Just share the file

---

Tips

1. Start simple — Add rules as you discover needs
2. Be specific — Vague rules lead to vague behavior
3. Version control — Track changes to your instructions
4. Iterate — Refine based on what works

---

The Bigger Picture

This is the core insight of the new AI paradigm:

Writing prompts = writing software

Your AGENTS.md file is a program. It defines behavior that's:

• Repeatable
• Shareable
• Version-controlled
• Continuously improved

You're not just using AI. You're building AI-powered workflows.

---

Put this into practice: Try the Grammar Check task.