AI Context Documentation

How to write and maintain the structured documentation that AI coding assistants consume.

File Hierarchy

AGENTS.md                            # Root context — always loaded by agents
CLAUDE.md                            # Required for Claude Code (loads AGENTS.md)
.github/skills/<topic>/SKILL.md      # On-demand detailed context
packages/<name>/AGENTS.md            # Package-specific context
<any-folder>/AGENTS.md               # Folder-specific context

Root Files

AGENTS.md

Always loaded on every interaction. Keep it minimal to save tokens.

Must contain:

• One-line project description
• Essential commands (run, test, build)
• Repository structure overview (top-level dirs only)
• Skills index table linking to each SKILL.md
• Key entry points for common tasks

Must not contain:

• Detailed explanations (put those in skills)
• Code examples longer than one line
• Duplicated content from skills

CLAUDE.md

Required because Claude Code doesn't load AGENTS.md natively. It bridges Claude Code into the same context system. Contents:

Read [AGENTS.md](AGENTS.md) before starting any task.

## Skills

Load these for detailed context on specific topics:

| Skill | When to use |
|-------|-------------|
| [<name>](.github/skills/<name>/SKILL.md) | <description> |

Keep in sync with the skills table in AGENTS.md.

Skills

Creating a Skill

1. Create .github/skills/<topic>/SKILL.md
2. Add YAML frontmatter with name and description
3. Add an entry to the skills table in both AGENTS.md and CLAUDE.md

SKILL.md Format

---
name: <topic>
description: <when an agent should load this — be specific about triggers>
---

# <Title>

<One-line summary.>

## <Sections organized by task>

Writing Guidelines

• Frontmatter description: Write it as a trigger — what task or question should cause an agent to load this skill
• Be concise: Use tables over prose, code snippets over explanations
• Be specific: File paths, command names, function signatures — not vague descriptions
• No duplication: If info exists in another skill, reference it instead of repeating
• Actionable structure: Organize by what the agent needs to do, not by architecture

Package & Folder Context

Add AGENTS.md inside a package or folder when:

• The directory has non-obvious conventions agents keep getting wrong
• There are local commands, patterns, or gotchas not covered by root docs

Keep these files very short — a few lines of context is often enough.

When to Update

Trigger	Action
Agent repeatedly asks about a topic	Create a new skill
Agent gets something wrong despite docs	Refine the relevant skill
New package/directory with unique patterns	Add a local AGENTS.md
Architecture or tooling changes	Update affected skills
Skill grows too large	Split into multiple skills
Skills table changes	Update both AGENTS.md and CLAUDE.md

Principles

1. Token budget: Root files stay small; details go in skills
2. Load on demand: Skills are only read when relevant to the task
3. Living docs: Update when patterns change — stale docs are worse than none
4. Cross-platform: AGENTS.md + .github/skills/ is the shared convention; CLAUDE.md bridges Claude Code which doesn't load AGENTS.md natively