GitHub Copilot Instructions: copilot-instructions.md, AGENTS.md, MCP

Copilot reads .github/copilot-instructions.md, path-specific .github/instructions/**/*.instructions.md (with applyTo globs) and AGENTS.md. The Copilot cloud agent (formerly coding agent) also accepts a root CLAUDE.md or GEMINI.md, and the nearest AGENTS.md wins. In VS Code, MCP servers go in .vscode/mcp.json (or a portable .mcp.json) and terminal approvals in chat.tools.terminal.autoApprove; the cloud agent's MCP servers are set in the repository settings and its internet access is behind a firewall. Billing is your Copilot plan.

GitHub Copilot at a glance

Global instructions	✓ Yes Personal and organization instructions on GitHub.com; `~/.copilot/copilot-instructions.md` for Copilot Agent Host / CLI sessions
Project instructions	✓ Yes `.github/copilot-instructions.md`, `.github/instructions/*/.instructions.md` (`applyTo`), `AGENTS.md`; cloud agent also `CLAUDE.md` or `GEMINI.md` at root
Nested / subfolder	◐ Partial Cloud agent: AGENTS.md anywhere, nearest wins. VS Code: nested AGENTS.md is experimental (`chat.useNestedAgentsMdFiles`, off by default)
AGENTS.md	✓ Yes VS Code agent mode and cloud agent; toggle `chat.useAgentsMdFile` in VS Code
Skills (SKILL.md)	✓ Yes `.github/skills`, `.claude/skills`, `.agents/skills`; personal `~/.copilot/skills`, `~/.agents/skills` (cloud agent, CLI, VS Code)
MCP config	✓ Yes VS Code: `.vscode/mcp.json` (`servers`) or `.mcp.json` (`mcpServers`), plus user-profile mcp.json. Cloud agent: JSON in repository Settings (`mcpServers`)
Permissions / allowlist	✓ Yes VS Code permission levels and Autopilot; `chat.tools.terminal.autoApprove` (true / false / regex), `chat.tools.edits.autoApprove`, `chat.tools.urls.autoApprove`
Sandbox	✓ Yes VS Code agent sandboxing (Preview on macOS/Linux/WSL2, experimental on Windows). Cloud agent: ephemeral cloud environment + internet firewall
Hooks	✓ Yes `.github/hooks/.json` for cloud agent and Copilot CLI (personal `~/.copilot/hooks/.json`); VS Code also reads `.github/hooks/` (Preview)
Claude Pro/Max login	✕ No Not documented
ChatGPT Plus/Pro login	✕ No Not documented
API key / own plan	◐ Partial Copilot plan required; bring-your-own-key options not verified here

Exact file paths

Path	Scope	What it does
`.github/copilot-instructions.md`	Repository	Repo-wide instructions (Chat, cloud agent, code review)
`.github/instructions/NAME.instructions.md`	Repository	Path-specific instructions with `applyTo:` globs
`AGENTS.md`	Repository	Agent instructions; nearest file wins for the cloud agent
`CLAUDE.md / GEMINI.md (root)`	Repository	Accepted by the cloud agent
`~/.copilot/copilot-instructions.md`	User	Personal always-on instructions (Agent Host / CLI)
`.vscode/mcp.json or .mcp.json`	Workspace	MCP servers for VS Code agent mode
`Repo Settings → Copilot → MCP`	Repository	MCP servers for the cloud agent (JSON)
`.github/hooks/*.json`	Repository	Hooks for cloud agent, Copilot CLI and VS Code
`.github/skills/<name>/SKILL.md`	Repository	Agent skills (also .claude/skills, .agents/skills)

Using a shared AGENTS.md with GitHub Copilot

Native in VS Code (chat.useAgentsMdFile) and the cloud agent. Keep .github/copilot-instructions.md only for Copilot-specific notes. See one AGENTS.md for every agent, or generate one with the AGENTS.md generator.

Copy-paste examples

Path-specific instructions

File: .github/instructions/ts.instructions.md

---
applyTo: "**/*.ts,**/*.tsx"
---

- Use strict TypeScript; no `any`.
- Run `npm run typecheck` after edits.

VS Code MCP server

File: .vscode/mcp.json

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

Cloud agent / CLI hook

File: .github/hooks/security.json

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      { "type": "command", "bash": "./scripts/security-check.sh", "cwd": "scripts", "timeoutSec": 15 }
    ]
  }
}

Safe permissions preset

Safe VS Code settings for Copilot agent mode

File: .vscode/settings.json

{
  "chat.tools.terminal.enableAutoApprove": true,
  "chat.tools.terminal.autoApprove": {
    "/^git (status|diff|log)\\b/": true,
    "/^npm (test|run lint)\\b/": true,
    "rm": false,
    "sudo": false,
    "/git push.*(--force|-f\\b)/": false,
    "/DROP (TABLE|DATABASE)|drop (table|database)/": false,
    "/terraform destroy|kubectl delete/": false
  },
  "chat.tools.edits.autoApprove": {
    "**/.env*": false,
    "**/*.pem": false
  },
  "chat.tools.global.autoApprove": false
}

In VS Code a false rule means "always ask", it does not block. To block a command outright, use a PreToolUse hook that denies it, and turn on agent sandboxing. VS Code calls terminal auto-approval best-effort, not a security boundary.

Gotchas

Instruction support differs by surface: VS Code reads AGENTS.md, while the cloud agent also accepts CLAUDE.md / GEMINI.md. Check GitHub's support matrix before relying on one file.
Custom instructions are not used for inline completions as you type.
VS Code's .vscode/mcp.json uses a top-level servers key; the portable .mcp.json uses mcpServers. Copying between them is a common mistake.
chat.tools.global.autoApprove skips every confirmation in every workspace. Prefer a session-scoped permission level.
The cloud agent's firewall limits internet access by default; add hosts to its allowlist rather than disabling it.

FAQ

Where does GitHub Copilot read custom instructions from?

.github/copilot-instructions.md for repository-wide guidance, .github/instructions/**/*.instructions.md for path-specific rules, and AGENTS.md. The Copilot cloud agent also reads CLAUDE.md or GEMINI.md at the repository root.

Does GitHub Copilot support AGENTS.md?

Yes. VS Code agent mode reads AGENTS.md (setting chat.useAgentsMdFile), with nested files as an experimental option. The Copilot cloud agent reads AGENTS.md anywhere in the repo and uses the nearest one.

Where is the MCP config for Copilot in VS Code?

.vscode/mcp.json in the workspace (top-level servers object), a portable .mcp.json at the project root (mcpServers), or the user-profile mcp.json opened with MCP: Open User Configuration.

How do I stop Copilot agent mode from running dangerous terminal commands?

Add false entries for those commands to chat.tools.terminal.autoApprove so they always need approval, block them with a PreToolUse hook, and enable agent sandboxing.

Sources

Checked against these official pages on 2026-10-12. Cells marked "Not documented" mean we could not find the behaviour in these docs; it may still exist.

GitHub Copilot configuration guide: instruction files, MCP, permissions