Which config files are read by which AI coding tools — and what each one does. Tap i on any row to learn more.
The harness is everything the model touches that isn't the model itself — tools, permissions, state management, verification loops, agents, hooks, and guardrails. These config files are the harness.
| Config file | GitHub CopilotVS Code | GitHub CopilotCLI | GitHub CopilotCloud agent | Claude Codeall surfaces | OpenCodeall surfaces | Codexall surfaces | Gemini CLIall surfaces | CursorIDE | WindsurfIDE | AmpIDE + CLI |
|---|---|---|---|---|---|---|---|---|---|---|
| Always-on instructions guideiFeedforward — steers the agent before it acts | ||||||||||
AGENTS.mdroot of repo |
Yes | Yes | Yes | — | Yes | Yes | opt-in | Yes | Yes | Yes |
The broadest shared instructions format in this matrix. A markdown file at your repo root read at the start of every session by several tools. Think of it as a system prompt for your repo — stack declarations, naming conventions, architectural boundaries, "never do X" rules. Put your shared team contract here. Claude Code still relies on CLAUDE.md for native instructions. | ||||||||||
CLAUDE.mdroot + subdirectories |
Yes | — | Yes | Yes | Fallback | — | — | — | — | Fallback |
Claude Code's native config. Same purpose as AGENTS.md but Claude-specific. Standout feature: subdirectory scoping — drop a CLAUDE.md in /api and those rules only apply when working on API files. If you also have AGENTS.md, your CLAUDE.md can say See @AGENTS.md for base rules plus Claude-specific additions. Copilot VS Code natively scans for CLAUDE.md in workspace folders alongside AGENTS.md. Copilot cloud agent also reads it as agent instructions. CLI does not read it. | ||||||||||
GEMINI.mdroot of repo |
— | — | Yes | — | — | — | Yes | — | — | — |
Gemini CLI's native context file. Hierarchical like CLAUDE.md — global (~/.gemini/GEMINI.md), project root, and subdirectory scoping with just-in-time discovery. Copilot cloud agent can also use a root-level GEMINI.md as agent instructions. Gemini CLI can also be configured to look for alternative filenames, including AGENTS.md, via the context.fileName setting. | ||||||||||
copilot-instructions.md.github/ |
Yes | Yes | Yes | — | — | — | — | — | — | — |
Copilot's original repo-wide config. Lives at .github/copilot-instructions.md. Auto-injected into every Copilot request. Same purpose as AGENTS.md but Copilot-exclusive. If you already have AGENTS.md, this can hold Copilot-only overrides. Auto-generate one with /init. | ||||||||||
*.instructions.md.github/instructions/ (glob scoped) |
Yes | Yes | Yes | — | — | — | — | — | — | — |
Surgically scoped rules via glob patterns. Each file has an applyTo frontmatter property (e.g., "**/*.tsx") so rules only activate on matching files. Perfect for framework-specific conventions. Copilot auto-detects relevance. Claude Code's equivalent is .claude/rules/*.md with a paths property. | ||||||||||
.claude/rules/*.mdscoped via paths property |
— | — | — | Yes | — | — | — | — | — | — |
Claude Code's scoped instruction files. Equivalent of Copilot's *.instructions.md. Uses a paths array in frontmatter instead of applyTo. Defaults to ** (all files) when omitted. | ||||||||||
.cursor/rules/*.md.cursor/rules/ (frontmatter scoped) |
— | — | — | — | — | — | — | Yes | — | — |
Cursor's native scoped rules. Markdown files (or .mdc) in .cursor/rules/ with YAML frontmatter controlling activation. Four modes: alwaysApply (always-on), globs (file-pattern match), model-decision (agent picks based on description), and manual (@rule-name). Cursor's primary config mechanism — richer than AGENTS.md with per-rule activation control. | ||||||||||
.windsurf/rules/*.md.windsurf/rules/ (frontmatter scoped) |
— | — | — | — | — | — | — | — | Yes | — |
Windsurf's native scoped rules. Markdown files in .windsurf/rules/ with YAML frontmatter. Same four activation modes as Cursor: always-on, glob, model-decision, and manual. Global rules also available at ~/.codeium/windsurf/memories/global_rules.md. Enterprise teams can deploy system-level rules. | ||||||||||
| Custom agents (persona + tool restrictions) guideiFeedforward — steers the agent before it acts | ||||||||||
*.agent.md.github/agents/ |
Yes | Yes | Yes | — | — | — | — | — | — | — |
Specialized Copilot personas invoked by name. Each defines a role with tool access, model choice, and behavioral boundaries. Invoke via @agent-name. Examples: @reviewer (read-only), @test-writer (writes to /tests/ only). Can be used as subagents by other agents. | ||||||||||
.claude/agents/*.mdClaude subagents |
— | — | — | Yes | — | — | — | — | — | — |
Claude Code's subagent system. Specialized agents running in isolated context. Built-in: Explore (read-only research) and Plan (no file modifications). Skills can reference agents via the agent frontmatter field to run in a forked context. | ||||||||||
.opencode/agents/*.mdOpenCode agents |
— | — | — | — | Yes | — | — | — | — | — |
OpenCode's native agent definitions. Same concept — persona with description, model, tool permissions, and prompt. Ships with Build (full tools) and Plan (read-only). Switch with Tab. Can also be defined in opencode.json. | ||||||||||
.gemini/agents/*.mdGemini subagents |
— | — | — | — | — | — | Yes | — | — | — |
Gemini CLI's custom subagents. Markdown files with YAML frontmatter that define specialized local agents. Store them at project scope in .gemini/agents/ or user scope in ~/.gemini/agents/. Invoke them automatically or force them with @agent-name. | ||||||||||
| Skills (bundled capability folders with SKILL.md) guideiFeedforward — steers the agent before it acts | ||||||||||
.github/skills/*/SKILL.mdCopilot native path |
Yes | Yes | Yes | — | — | — | — | — | — | — |
Copilot's native skill path — Copilot-only. Skills are folders with a SKILL.md entrypoint plus optional scripts, templates, and assets. Progressive disclosure: only name + description loaded by default, full body on demand. Invoke via /skill-name or auto-detected. Claude Code does not read this path — use .claude/skills/ instead. | ||||||||||
.claude/skills/*/SKILL.mdClaude Code native path |
Yes | Yes | Yes | Yes | Fallback | — | — | Fallback | opt-in | Fallback |
Claude Code's native skill path. OpenCode also reads this directory as a fallback. Copilot natively scans .claude/skills/ as a default skill path alongside .github/skills/ — confirmed in the VS Code extension bundle. Claude Code supports auto-invocation, user-invocation (/skill-name), and forked subagent execution. | ||||||||||
.agents/skills/*/SKILL.mdcross-agent standard path |
— | — | — | — | Fallback | Yes | Fallback | Yes | Fallback | Yes |
The broadest cross-agent skill path available today. Codex's primary skill path — scans .agents/skills from your working directory up to the repo root. Also read natively by Cursor and Amp, and as a fallback by OpenCode, Windsurf, and Gemini CLI. Based on the open Agent Skills specification. | ||||||||||
.gemini/skills/*/SKILL.mdGemini CLI native path |
— | — | — | — | — | — | Yes | — | — | — |
Gemini CLI's native skill path. Skills live under .gemini/skills/<name>/SKILL.md and are activated on demand via the activate_skill tool. Gemini also reads .agents/skills/ as a fallback, which makes that path the better portability choice when you want cross-tool reuse. | ||||||||||
.opencode/skills/*/SKILL.mdOpenCode native path |
— | — | — | — | Yes | — | — | — | — | — |
OpenCode's own skill directory. Same SKILL.md format. OpenCode also reads .claude/skills/ and .agents/skills/ as fallbacks, so you rarely need this unless you want OpenCode-exclusive skills. | ||||||||||
.cursor/skills/*/SKILL.mdCursor native path |
— | — | — | — | — | — | — | Yes | — | — |
Cursor’s native skill path. Skills at .cursor/skills/<name>/SKILL.md with YAML frontmatter (name, description). Supports progressive disclosure — only metadata loaded until invoked. Invoke via /skill-name. Cursor also reads .agents/skills/ natively and .claude/skills/ as a fallback for cross-tool compatibility. | ||||||||||
.windsurf/skills/*/SKILL.mdWindsurf native path |
— | — | — | — | — | — | — | — | Yes | — |
Windsurf’s native skill path. Skills at .windsurf/skills/<name>/SKILL.md with YAML frontmatter. Also available globally at ~/.codeium/windsurf/skills/. Windsurf reads .agents/skills/ as a fallback and .claude/skills/ when Claude Code config reading is enabled. | ||||||||||
| Prompt files (manual /slash-command invocation) guideiFeedforward — steers the agent before it acts | ||||||||||
*.prompt.md.github/prompts/ |
Yes | — | — | — | — | — | — | — | — | — |
Lightweight reusable prompt templates — Copilot IDE only. Invoke via /prompt-name in chat. No persona, no tool restrictions, no bundled assets. Best for tasks you repeat: /new-component, /spell-check, /prep-pr. Available in Copilot IDE integrations such as VS Code, Visual Studio, and JetBrains — not in Copilot CLI or cloud agent. | ||||||||||
.claude/commands/*.mdmerged into skills system |
— | — | — | Yes | — | — | — | — | — | — |
Claude Code's original slash commands — now merged into skills. A command at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work identically. Existing files keep working. Skills add supporting files, auto-invocation, and subagent execution. | ||||||||||
.opencode/commands/*.mdOpenCode native commands |
— | — | — | — | Yes | — | — | — | — | — |
OpenCode's native custom command format. Markdown files in .opencode/commands/ define reusable slash commands. The file body becomes the prompt template, and frontmatter can choose an agent or model for execution. | ||||||||||
.gemini/commands/*.tomlGemini custom commands |
— | — | — | — | — | — | Yes | — | — | — |
Gemini CLI's native custom command format. TOML files in .gemini/commands/ define reusable slash commands. Project commands override user commands, support argument injection, and can embed shell output or file content into the final prompt. | ||||||||||
.windsurf/workflows/*.mdWindsurf workflows |
— | — | — | — | — | — | — | — | Yes | — |
Windsurf's reusable prompt templates. Markdown files in .windsurf/workflows/ invoked via /workflow-name in Cascade. Equivalent to Copilot's *.prompt.md files. Also available globally at ~/.codeium/windsurf/global_workflows/. 12,000 character limit per file. | ||||||||||
| Automation (lifecycle hooks) sensoriFeedback — observes after the agent acts | ||||||||||
.github/hooks/hooks.json |
Yes | Yes | — | — | — | — | — | — | — | — |
Copilot lifecycle hooks. Automated workflows at agent events — run a formatter after edits, validate branch names, enforce lint. preToolUse hooks can deny or modify tool calls. Think git hooks for the AI loop. VS Code and CLI only — not Cloud agent. | ||||||||||
.claude/hooks/settings.json hooks |
— | — | — | Yes | — | — | — | — | — | — |
Claude Code's hook system. 14+ trigger points: SessionStart, PreToolUse, PostToolUse, PermissionRequest. Run custom scripts at every stage — linting, logging, approval gates. More granular than Copilot hooks with before/after triggers for tool execution. | ||||||||||
.codex/hooks.jsonrepo or ~/.codex/ |
— | — | — | — | — | Yes | — | — | — | — |
Codex's lifecycle hook system. Experimental. Five trigger points: SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop. Hooks receive JSON on stdin and can block commands, inject context, or continue stopped turns. Loaded from both user (~/.codex/hooks.json) and repo (.codex/hooks.json) locations. Requires codex_hooks = true in config.toml features. | ||||||||||
.windsurf/hooks.json.windsurf/ (system/user/workspace) |
— | — | — | — | — | — | — | — | Yes | — |
Windsurf’s lifecycle hook system. 12 hook events including pre/post_read_code, pre/post_write_code, pre/post_run_command, pre/post_mcp_tool_use, pre_user_prompt, and post_cascade_response. Pre-hooks can block actions via exit code 2. Three config tiers merged together: system (/Library/Application Support/Windsurf/hooks.json), user (~/.codeium/windsurf/hooks.json), and workspace (.windsurf/hooks.json). Enterprise teams can deploy via cloud dashboard or MDM. | ||||||||||
| MCP server configuration (project-scoped) guideiFeedforward — steers the agent before it acts | ||||||||||
.vscode/mcp.jsonVS Code workspace |
Yes | — | — | — | — | — | — | — | — | — |
Copilot's MCP config for VS Code. Defines MCP servers available in the workspace. Supports stdio and HTTP servers with environment variables, auth, and sandboxing. Committable to git for team sharing. Can also configure MCP in settings.json (workspace or user), install from the MCP server gallery, or add via devcontainer.json. User-level config available via MCP: Open User Configuration. | ||||||||||
.mcp.jsonrepo root |
— | — | — | Yes | — | — | — | — | — | — |
Claude Code's project-scoped MCP config. Defines MCP servers for all collaborators on this repository. Supports stdio, SSE, and HTTP servers. Committable to git. User-scoped servers go in ~/.claude.json instead. | ||||||||||
opencode.jsonrepo root (mcp key) |
— | — | — | — | Yes | — | — | — | — | — |
OpenCode's MCP config. MCP servers are defined under the mcp key in opencode.json at the repo root. Supports local (stdio) and remote (HTTP) servers with OAuth support. Committable to git. | ||||||||||
.codex/config.tomlrepo root (mcp_servers) |
— | — | — | — | — | Yes | — | — | — | — |
Codex's project-scoped MCP config. MCP servers defined under [mcp_servers.<name>] tables in TOML format. Supports stdio and streamable HTTP servers with bearer token auth and OAuth. Shared by CLI and IDE extension. User-level config at ~/.codex/config.toml. | ||||||||||
.gemini/settings.jsonmcpServers key |
— | — | — | — | — | — | Yes | — | — | — |
Gemini CLI's MCP config. MCP servers defined under the mcpServers key in .gemini/settings.json. Supports stdio, SSE, and streamable HTTP with tool allowlists/excludelists. User-level config at ~/.gemini/settings.json. Invoke MCP tools via @server-name in prompts. | ||||||||||
.cursor/mcp.json.cursor/ (project + global) |
— | — | — | — | — | — | — | Yes | — | — |
Cursor's MCP config. Project-scoped at .cursor/mcp.json, user-scoped at ~/.cursor/mcp.json. Supports stdio, SSE, and streamable HTTP transports. Committable to git for team sharing. | ||||||||||
mcp_config.json~/.codeium/windsurf/ (user-level) |
— | — | — | — | — | — | — | — | Yes | — |
Windsurf's MCP config — user-level only. Configured at ~/.codeium/windsurf/mcp_config.json or via the MCP Marketplace in Cascade settings. Supports stdio, streamable HTTP, and SSE transports with OAuth. Notable gap: no project-scoped committable MCP config — all MCP setup is per-user. Supports variable interpolation (${env:VAR}, ${file:path}) for secrets. | ||||||||||
.amp/settings.jsonworkspace (amp.mcpServers) |
— | — | — | — | — | — | — | — | — | Yes |
Amp's MCP config. MCP servers defined under amp.mcpServers in .amp/settings.json (workspace) or ~/.config/amp/settings.json (user). Skills can also bundle their own MCP servers via an mcp.json file in the skill directory. Supports --mcp-config CLI flag and amp mcp add command. | ||||||||||
AGENTS.md has the broadest reach of any instructions file shown here — natively read by Copilot, Codex, OpenCode, Cursor, Windsurf, and Amp, with opt-in support from Gemini CLI. Claude Code still relies on CLAUDE.md; Amp falls back to it when no AGENTS.md exists.
.agents/skills/ is now the broadest cross-tool skill path — read natively by Codex, Cursor, and Amp, with fallback support from OpenCode, Windsurf, and Gemini CLI.
Cursor and Windsurf both mirror the four-mode scoped rules pattern (.cursor/rules/ and .windsurf/rules/) with always-on, glob, model-decision, and manual activation — the most granular instructions controls in the matrix.
Windsurf has the most complete hooks system: 12 event types with pre/post triggers for file reads, writes, commands, and MCP calls, plus three-tier config merging (system → user → workspace).
MCP server config remains fully fragmented — every tool uses a different file and format. Windsurf's MCP config is notably user-level only with no project-scoped committable file.