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 before starting any task.

Skills

Load these for detailed context on specific topics:

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

Skills

Creating a Skill

• Create .github/skills/<topic>/SKILL.md

• Add YAML frontmatter with name and description

• 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

• Token budget: Root files stay small; details go in skills

• Load on demand: Skills are only read when relevant to the task

• Living docs: Update when patterns change — stale docs are worse than none

• Cross-platform: AGENTS.md

• .github/skills/ is the shared convention; CLAUDE.md bridges Claude Code which doesn't load AGENTS.md natively