A cross-tool reference for AGENTS.md, CLAUDE.md,
copilot-instructions.md, GEMINI.md, and every other
file that tells your AI coding agents how to work.
Which files each AI coding tool reads natively. ✓ = native support, ~ = via symlink, — = not supported.
| File | Claude Code | GitHub Copilot | OpenAI Codex | Gemini CLI | Cursor | Windsurf | Scope |
|---|---|---|---|---|---|---|---|
|
AGENTS.md
repo root or subdirs
|
~ | ✓ | ✓ | ✓ | ✓ | ✓ | Universal |
|
CLAUDE.md
root / ~/.claude / subdirs
|
✓ | ✓ | — | — | ~ | ~ | Claude |
|
.github/copilot-instructions.md
.github/ folder
|
— | ✓ | — | — | — | — | Copilot only |
|
*.instructions.md
.github/instructions/
|
— | ✓ | — | — | — | — | Copilot only |
|
*.agent.md
.github/agents/
|
— | ✓ | — | — | — | — | Copilot only |
|
*.prompt.md
.github/prompts/
|
— | ✓ | — | — | — | — | Copilot only |
|
GEMINI.md
repo root
|
— | ✓ | — | ✓ | ~ | ~ | Gemini |
|
SKILL.md
.github/skills/ · .claude/skills/ · .windsurf/skills/ · ~/.copilot/skills/ · Microsoft Agent Framework (✓ native)
|
✓ | ✓ | — | — | — | ✓ | Shared |
|
.claude/agents/*.md
project or ~/.claude/agents/
|
✓ | — | — | — | — | — | Claude only |
|
.claude/commands/*.md
project or ~/.claude/commands/
|
✓ | — | — | — | — | — | Claude only |
|
.cursor/rules/*.mdc
.cursor/rules/
|
— | — | — | — | ✓ | — | Cursor only |
|
openai-codex/setup.sh
repo root
|
— | — | ✓ | — | — | — | Codex only |
Since tools read different filenames, use symlinks to keep a single source of truth. Most tools respect the nearest file in the directory tree.
# Write your instructions in AGENTS.md, then symlink for tool-specific filenames ln -s AGENTS.md CLAUDE.md ln -s AGENTS.md GEMINI.md # Or start from CLAUDE.md if you're Claude Code-first ln -s CLAUDE.md AGENTS.md
What each file does, where it lives, and a starter template you can copy.
The open standard. A README for agents. Supported by Copilot, Codex, Gemini CLI, Cursor, Windsurf, Zed, and more. Most-nested file takes precedence. Plain Markdown — no required schema.
# AGENTS.md ## Project Next.js 14 app with TypeScript + Postgres. ## Commands - Install: `pnpm install` - Dev: `pnpm dev` - Test: `pnpm test` - Lint: `pnpm lint:fix` ## Standards - Named exports only - Zod for all validation - Tests required on all PRs
Claude Code's primary memory file. Loaded every session. Hierarchy: enterprise → user global (~/.claude/CLAUDE.md) → project root → subdirectory. More specific overrides broader. Target: under 300 lines.
# CLAUDE.md # Keep under 300 lines. Point to # other files for specific topics. ## What this project is One sentence overview. ## How to run things Exact commands only. No vague hints. ## What NOT to do NEVER modify /migrations directly. ## More context See agent_docs/ for detailed guides.
Global instructions for all GitHub Copilot chat and the coding agent. Applied automatically to every request in the repo. One file, repo-wide scope only.
# Applied to all Copilot requests We use Bazel for Java deps, not Maven. JS uses double quotes + tab indentation. We use Jira for issue tracking. Run `npm test` before any PR. All API routes live in /src/api/.
Path-specific instructions for Copilot. Uses YAML frontmatter with glob patterns to apply rules only to matching files. Multiple files, granular control. Use excludeAgent to exclude specific Copilot agents.
--- applyTo: "src/models/**/*.ts" excludeAgent: "code-review" --- All models extend BaseModel. Use Zod schemas for validation. Export both type and schema.
Gemini CLI's equivalent of CLAUDE.md. Also read by GitHub Copilot when Gemini model is active. Same structure as AGENTS.md — plain Markdown, no required schema.
# GEMINI.md # Same structure as AGENTS.md. # Symlink if content is identical: ln -s AGENTS.md GEMINI.md # Only create separately if you need # Gemini-specific instructions.
Reusable skill bundles loaded on demand — not at every session start. A skill is a folder containing SKILL.md plus any helper scripts or resource files. Portable across Claude Code and GitHub Copilot (Copilot CLI, coding agent, VS Code agent mode). Each tool uses the YAML frontmatter description field to decide when to load the skill. Copilot also supports manual invocation via /skill-name in chat. Project skills are repo-scoped; personal skills (in ~/.copilot/skills/ or ~/.claude/skills/) apply across all projects.
--- name: api-tests description: Write and run API integration tests. Use when asked to create or fix API tests. --- # Step-by-step instructions go here. # Include helper scripts and examples # in the same folder alongside SKILL.md.
Custom subagents for Claude Code with isolated context. Defined via YAML frontmatter. Project agents (.claude/agents/) are version-controlled and team-shared. User agents (~/.claude/agents/) are personal and available in all projects.
--- name: code-reviewer description: Reviews PRs for bugs model: claude-sonnet-4 tools: [read_file, bash] --- You are a principal-level code reviewer. Focus on bugs, security, and performance. Be specific — cite file and line number.
Cursor's rule system with four loading modes: Always (every context), Auto Attached (glob-matched files), Agent Requested (AI decides), Manual (explicit only). More granular than AGENTS.md for Cursor power users.
--- description: DynamoDB model patterns globs: "src/models/**/*.py" alwaysApply: false --- Use PynamoDB for all DynamoDB models. Hash key must be named `pk`, range `sk`.
Tools and collections that extend, distribute, or orchestrate AI agent instruction files. Verified details only — compatibility marked explicitly.
Think package.json but for AI agent configuration. APM introduces an apm.yml manifest that declares the skills, prompts, instructions, and agents your project needs. Run apm install and every developer gets an identical agent setup. Resolves transitive dependencies, compiles to AGENTS.md and CLAUDE.md automatically, and installs from GitHub, GitHub Enterprise, and Azure DevOps — no registry required.
pip install apm-cli
An AI team framework built on top of GitHub Copilot. You describe what you're building and Squad proposes a named team of specialist agents — each with a defined role, its own memory, and shared decision logs. Agents persist across sessions as files in your repo, learning your codebase over time. Integrates with GitHub Issues via labels: tag an issue squad and the lead agent triages and assigns it automatically. Can include @copilot as a team member for autonomous coding tasks. TypeScript SDK-first mode available via squad.config.ts. Featured on the GitHub Blog (March 2026).
npm install -g @bradygaster/squad-cli
Docs: bradygaster.github.io/squad
Anthropic's official skill library — the canonical reference for the SKILL.md format. Contains 50+ production-quality skills across document processing (Word, PDF, PowerPoint, Excel), development tools, design, and enterprise workflows. The docx, pdf, pptx, and xlsx skills are the same ones powering Claude's document capabilities in production. Installable as a Claude Code plugin via /plugin install.
/plugin install document-skills@anthropic-agent-skills
GitHub's official community-contributed collection of Copilot customizations. Includes instructions files, agent personas, hooks (event-driven automations triggered by Copilot coding agent sessions), agentic workflows for GitHub Actions, plugins, and skills. A practical starting point for teams looking to adopt instruction files — most entries are production-tested and cover a wide range of languages, frameworks, and roles.
The canonical specification repository for the AGENTS.md open standard. Released by OpenAI in August 2025 and donated to the Linux Foundation / Agentic AI Foundation in December 2025. Includes the formal spec, examples, and a companion site at agents.md. This is the authoritative source for how the standard should behave across tools — read this before writing your first AGENTS.md.
Embeds the same agentic execution loop that powers Copilot CLI directly into your application. Instead of building your own orchestration layer, you define agent behavior — tools, instructions, permissions — and Copilot handles planning, tool invocation, file edits, multi-turn memory, and model routing. Supports BYOK (Bring Your Own Key) so you can substitute OpenAI, Azure AI Foundry, or Anthropic models without a Copilot subscription. Available in Python, TypeScript, Go, and .NET. Launched January 2026; currently in technical preview.
pip install copilot-sdk / npm install @github/copilot-sdk
A portable, open-source trust policy and guardrail specification for agentic systems. Defines agent behavior boundaries — what actions are permitted, denied, or require human approval — in a single bouncer.md file that any agent runtime can read. Designed to be composable alongside AGENTS.md and CLAUDE.md: instruction files tell agents what to do, bouncer-md defines the guardrails within which they operate. Currently v0.5 with a full repo structure, test suite, and examples. Maintained independently of any tool vendor to preserve community credibility.
Distilled from real-world usage and analysis of thousands of repos.
Every line in your memory file competes with actual work for context window. Target under 300 lines for CLAUDE.md. Under 200 lines before splitting into subdirectory files for AGENTS.md.
Reference other files instead of inlining content. Keep task-specific docs in agent_docs/ and list them in your root file. Agents read what's relevant; unused context is wasted tokens.
Don't put linting rules or formatting preferences in instruction files. Use ESLint, Prettier, or your formatter. LLMs are slow and expensive compared to deterministic tools. Reserve instructions for what only a human can explain.
Write the exact command (pnpm test --run --no-color), not a description of what it does. Include flags. Agents use these literally — vague wording causes hallucinated flags.
Place additional AGENTS.md files in subdirectories. The nearest file in the directory tree wins. OpenAI's own repo uses 88 AGENTS.md files. Don't try to cover everything from the root.
Update instruction files in the same PR as the process change. Review them in code review. Audit quarterly. Outdated instructions actively hurt agent performance — worse than no instructions at all.
Tell agents what NOT to do as explicitly as what to do. Include a "never do" section. Tell agents when to ask for human review rather than proceeding. Agents that know their limits are more reliable.
These files go into your system prompt and are version-controlled. Never include API keys, passwords, connection strings, or security vulnerability details. Treat the file as public documentation.
Major changes to the ecosystem. This space moves fast — bookmark and check back.
FileAgentSkillsProvider — same progressive disclosure pattern as Claude Code and Copilot. AGENTS.md read natively for project instructions. Semantic Kernel and AutoGen enter maintenance mode.
Announcement ↗
GitHub ↗
/memory slash command provides quick access to manage instruction files. Copilot auto-discovers and loads instruction files into context during agent workflows.
Changelog ↗
bouncer.md file composable alongside existing instruction files. Runtime-agnostic by design, maintained independently of any tool vendor. Ships with a full repo structure, test suite, and examples.
GitHub ↗
Docs ↗
create-next-app now scaffolds both files by default. AGENTS.md directs agents to version-matched docs bundled inside node_modules/next/dist/docs/ — no stale training data. CLAUDE.md uses the @ import syntax to reference AGENTS.md without duplication. Vercel reports 100% pass rate on internal evals with this context in place.
Blog Post ↗
Docs ↗
.windsurf/skills/, expanding the compatibility matrix. Also adds system-level skill definitions via MDM-managed configs for Enterprise deployments.
Changelog ↗
SKILL.md natively — the same format as Claude Code skills. Store project skills in .github/skills/ or .claude/skills/; personal skills in ~/.copilot/skills/. Invoke with /skill-name in chat or let Copilot auto-load based on the description frontmatter field.
Changelog ↗
Docs ↗