Skip to content

Context Files (CLAUDE.md / AGENTS.md / DESIGN.md / SKILL.md)

Summary

Context files are a family of version-controlled Markdown documents that encode project-specific instructions, conventions, preferences, and knowledge for AI agents. Rather than requiring agents to infer intent from code or prompt the user for context repeatedly, context files provide structured, persistent, machine-readable specifications that agents read at session start. The family includes CLAUDE.md (Claude Code project context), AGENTS.md (OpenAI Codex / general agent context), DESIGN.md (Google Stitch design system rules), and SKILL.md (Claude Code reusable skill definitions). Together they form an emerging open convention for agent-readable project documentation.

Details

The Family of Context Files

File Owner/Origin Primary Purpose
CLAUDE.md Anthropic / Claude Code Project architecture, commands, conventions, workflows — auto-read by Claude Code at session start
AGENTS.md OpenAI / Codex team Agent instructions and codebase table of contents for navigation; progressive disclosure entry point
DESIGN.md Google / Stitch Design rules, preferences, and conventions for UI/UX; exportable/importable across projects
SKILL.md Anthropic / Claude Code Reusable agent capability definitions; invoked via /skill-name or auto-loaded when relevant

CLAUDE.md

CLAUDE.md is a special file that Claude Code automatically reads at the start of every session. It provides persistent project context without requiring users to re-explain their codebase each time. Recommended contents:

  • Project architecture and key components
  • Development commands (build, test, deploy)
  • Code style and conventions
  • Common workflows or tasks
  • Important constraints or context about the codebase

Example CLAUDE.md structure: 

# Project Overview
Brief description of what this project does.

## Architecture
- Frontend: React app in /client
- Backend: FastAPI in /server
- Database: PostgreSQL

## Development Commands
- Start dev server: `npm run dev`
- Run tests: `pytest tests/`

## Code Style
- Follow PEP 8 for Python
- Use TypeScript strict mode
- All functions need docstrings

CLAUDE.md files can be nested — a root-level file applies globally, while subdirectory files add context for specific modules. The file is the primary tool for establishing persistent agent context in Claude Code projects.

See also concepts/claude-code for full best practices around CLAUDE.md usage.

AGENTS.md

AGENTS.md is the OpenAI Codex team's equivalent context file, first described in their "Harness Engineering" article (March 2026). It functions as a progressive disclosure table of contents — agents start with the AGENTS.md summary and navigate deeper documentation only as needed. This prevents context-window overload in large codebases.

Key design principle: AGENTS.md is short by design. It points to other files rather than containing everything. See concepts/harness-engineering for the full progressive disclosure pattern.

DESIGN.md

DESIGN.md is Google Stitch's open-sourced file format for encoding design rules, preferences, and conventions. Announced April 21, 2026, it was open-sourced to enable use across any tool or platform.

Core capabilities: - Export — Pull design rules into a well-formatted, version-controlled file - Import — Transfer design rules to any new project or share with collaborators - Agent alignment — Give AI agents precise, structured instructions for coding style and UI conventions - Portability — Use across any tool or platform that supports DESIGN.md

Why it matters: Without DESIGN.md, agents must guess design intent from existing code, leading to inconsistent outputs. DESIGN.md makes design decisions explicit and machine-readable. It also simplifies code review by codifying decisions once and sharing them everywhere — reducing back-and-forth about style and preference.

DESIGN.md is platform-agnostic and not tied to any specific AI tool, positioning it as a potential open standard alongside CLAUDE.md and AGENTS.md.

See entities/google-stitch for the source entity.

SKILL.md

SKILL.md defines reusable agent capabilities that can be invoked on demand in Claude Code. Unlike the other context files (which provide static information), SKILL.md files define executable behaviors — the agent invokes the skill as a mini-program.

Key frontmatter fields: - context: — controls execution environment (default vs. fork for isolated subagent) - disable-model-invocation: — prevents auto-invocation when true

See concepts/claude-code-skills for the full SKILL.md reference.

The Emerging Standard

These files represent a convergence toward a common convention: put agent-readable context in version-controlled Markdown files at the root of the project. The benefits:

  1. Persistence — Context survives across sessions without relying on chat history
  2. Version control — Context files evolve with the codebase; git blame shows why conventions changed
  3. Shareability — Teams can share context files; onboarding new agents (or humans) is faster
  4. Portability — Increasingly, these files are designed to work across tools (DESIGN.md explicitly; SKILL.md via agentskills.io)
  5. Reduced hallucination — Explicit specifications reduce the need for agents to infer intent, lowering error rates

.claudeignore

Analogous to .gitignore, .claudeignore specifies files and directories that Claude Code should not read or process — useful for sensitive configuration files, secrets, and large binary assets. It is part of the broader context management toolkit alongside CLAUDE.md.

Key Claims & Data Points

  • CLAUDE.md is automatically read by Claude Code at the start of every session — [source: claude-code-best-practices-anthropic-2026.md]
  • DESIGN.md was open-sourced by Google Stitch on April 21, 2026, for use across any tool or platform — [source: stitchbygoogle-design-md-draft-spec-2026.md]
  • DESIGN.md eliminates agent guessing about design intent by making rules explicit and machine-readable — [source: stitchbygoogle-design-md-draft-spec-2026.md]
  • AGENTS.md functions as a progressive disclosure table of contents for agent navigation in large codebases — [source: harness_engineering.md (via concepts/harness-engineering)]
  • SKILL.md enables portable, reusable agent capabilities via the agentskills.io open standard — [source: Claude_Agent_Skills_Explained.md (via concepts/claude-code-skills)]
  • .claudeignore controls which files Claude Code can access, analogous to .gitignore — [source: claude-code-best-practices-anthropic-2026.md]

Open Questions

  • Is there coordination between Anthropic, OpenAI, and Google Stitch to formalize a common context-file standard, or is convergence happening organically?
  • How should projects handle conflicts between CLAUDE.md project context and DESIGN.md design rules — which takes precedence?
  • Will DESIGN.md adoption spread beyond Google Stitch to other AI-assisted development tools (Cursor, Copilot, etc.)?
  • How do context files evolve in very large repositories — is there a risk of context file bloat where the files themselves become unmanageable?
  • Should context files be LLM-generated and maintained (like this wiki), or human-authored?

Sources