{"slug": "how-to-write-copilot-instructions-md-for-github-copilot", "title": "How to write copilot-instructions.md for GitHub Copilot", "summary": "GitHub Copilot reads `.github/copilot-instructions.md` on every request in a repository, but the file should stay under two pages and avoid task-specific rules, according to GitHub's custom instructions documentation checked on 2026-09-23. Path-specific rules belong in `.github/instructions/*.instructions.md` files with an `applyTo` glob, and Copilot agents also read `AGENTS.md`, `CLAUDE.md` or `GEMINI.md`, with the nearest file in the directory tree taking precedence. GitHub's support matrix shows `copilot-instructions.md` is the only instruction file every Copilot surface reads, while a rule living only in `AGENTS.md` reaches the cloud agent, Copilot CLI and VS Code chat but misses GitHub.com chat and JetBrains chat.", "body_md": "Blog\n\n# How to write copilot-instructions.md for GitHub Copilot\n\nPublished: September 23, 2026\n\n`.github/copilot-instructions.md` is the repository-wide instruction file GitHub Copilot adds to every request in that repo. Keep it under two pages and not task specific. Put rules for one part of the codebase in `.github/instructions/*.instructions.md` with an `applyTo` glob. Copilot's agents also read `AGENTS.md`.\n\nEvery fact below was checked against [GitHub's custom instructions docs](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions) and its [support matrix](https://docs.github.com/en/copilot/reference/custom-instructions-support) on 2026-09-23. Which Copilot surface reads which file differs more than most guides admit, so the matrix is the part worth bookmarking.\n\n## What are the types of Copilot custom instructions?\n\n| Type | File | Applies to | \n|---|---|---|\n| Repository-wide | `.github/copilot-instructions.md` | Every request in the repository | \n| Path-specific | `.github/instructions/NAME.instructions.md` | Files matching its `applyTo` glob, on top of the repository-wide file | \n| Agent instructions | `AGENTS.md` ,`CLAUDE.md` or`GEMINI.md` , anywhere in the repo | Copilot agents. The nearest file in the directory tree takes precedence | \n| Personal | Your GitHub settings | You, on the surfaces that support it | \n| Organization | Org settings | Everyone in the org, on the surfaces that support it | \n\nWhen more than one applies, GitHub sends all of them. Where they conflict, personal instructions win, then repository, then organization.\n\n## How do you write copilot-instructions.md?\n\nGitHub's guidance is that the repository-wide file should be no longer than two pages and should not be task specific. Treat it as the short list of things a new engineer would get wrong in their first week, not as the onboarding doc.\n\n```\n# Payments service\n\nTypeScript, Node 22, Postgres through Prisma. Tests: npm test.\n\n- Webhook handlers must be idempotent. Key on the provider's event id.\n- Retries go through src/lib/retry.ts. Five attempts, then dead-letter.\n  Why: docs/decisions/0012-webhook-retries.md\n- Never edit a migration that has been merged. Write a new one.\n```\n\nThe same rules of thumb apply as for any instruction file. Write down what the model cannot infer from the code, give the reason next to the rule, and point at files instead of pasting them. The research on whether these files help at all is summarised in [is AGENTS.md useful](https://gethrbr.com/blog/is-agents-md-useful).\n\n## How do path-specific .instructions.md files work?\n\nA path-specific file lives in `.github/instructions/`, ends in `.instructions.md`, and opens with frontmatter naming the paths it covers:\n\n```\n---\napplyTo: \"src/payments/**/*.ts\"\n---\n\nUse the shared backoff in src/lib/retry.ts. Do not add a retry loop.\n```\n\nAn optional `excludeAgent` key keeps a file away from either code review or the cloud agent. When Copilot works on a matching file, the path-specific instructions are combined with the repository-wide ones. This is the cheapest way to keep a rule about payments out of a request about CSS.\n\n## Which Copilot features read which instruction files?\n\nNot every surface reads every file. From GitHub's support matrix, for the surfaces most teams use:\n\n| Surface | copilot-instructions.md | .instructions.md | AGENTS.md / CLAUDE.md | \n|---|---|---|---|\n| GitHub.com chat | Yes | No | No | \n| Cloud agent (GitHub.com) | Yes | Yes | Yes | \n| Code review (GitHub.com) | Yes | Yes | AGENTS.md only | \n| VS Code chat | Yes | Yes | AGENTS.md only | \n| VS Code code review | Yes | No | No | \n| JetBrains chat | Yes | Yes | No | \n| Visual Studio chat | Yes | Yes | No | \n| Copilot CLI | Yes | Yes | Yes | \n\nThe practical reading: `copilot-instructions.md` is the only file every surface reads. A rule that lives only in `AGENTS.md` reaches the cloud agent, the CLI and VS Code chat, and misses GitHub.com chat and JetBrains chat.\n\n## AGENTS.md vs copilot-instructions.md: which should you use?\n\nIf everyone uses Copilot, `copilot-instructions.md` reaches the most surfaces. If the team is mixed, and most are, the rules end up needing to be in both: `AGENTS.md` for Codex, Cursor and Claude Code, and `copilot-instructions.md` for the Copilot surfaces that do not read `AGENTS.md`. The usual answer is to keep one canonical file and make the other a short pointer to it, then check that the pointer is actually followed on each surface. The tool-by-tool view is in [AGENTS.md vs CLAUDE.md: which tools read which](https://gethrbr.com/blog/agents-md-vs-claude-md).\n\n## How do you know Copilot used your instructions?\n\nIn Copilot Chat, expand the References list at the top of a response. If `.github/copilot-instructions.md` is listed, the file was sent with that request. That tells you the file was included. It does not tell you which line of it shaped the answer, and on a two-page file that is the question that matters when you are deciding what to cut.\n\n## What is Copilot Memory, and does it replace instructions?\n\n[Copilot Memory](https://docs.github.com/en/copilot/concepts/agents/copilot-memory) is in public preview. It stores repository-level facts with citations to the code that supports them, checks those citations against the current branch before using a fact, and deletes facts that go unused for 28 days. The cloud agent, code review and the CLI use it. Repository owners can review and delete what it stored.\n\nIt does not replace instructions, and it is not built to. It learns from the code and from work in that one repository. The decision your team made in a Slack thread last month, which is in no code yet, is not something it can learn. How it compares with Claude Code, Codex and Cursor is in [Claude Code memory vs Codex, Cursor and Copilot](https://gethrbr.com/blog/claude-code-memory-vs-codex-cursor-copilot).\n\n## Where Harbor fits\n\nAn instruction file is a copy of decisions made somewhere else: a pull request review, a thread in `#eng-payments`, a design doc. Somebody has to notice, write it down, and write it down again for each tool's file. Harbor reads those places, a person approves what becomes a fact (or a policy you set approves the routine ones), and every agent is served only the facts that apply to its task.\n\nCopilot's agent mode in VS Code can add a remote MCP server, and Harbor is one: any client that speaks MCP can search your team's approved facts at `https://mcp.gethrbr.com/mcp`. That is a pull-only connection. `harbor init` installs the fuller setup, with facts served at session start and write-back through review, for Claude Code, Codex and Cursor, not for Copilot. Answers cite the facts they used as `[#1]`, and Harbor counts, per fact, served against cited. A cite is evidence, not proof, and that count is the one the References list cannot give you. See [served vs cited](https://gethrbr.com/blog/served-vs-cited).\n\n## Questions\n\n### Where does copilot-instructions.md go?\n\nIn the .github folder at the root of the repository: .github/copilot-instructions.md. Copilot adds it to every request made in the context of that repository.\n\n### How long should copilot-instructions.md be?\n\nGitHub says repository-wide instructions should be no longer than two pages and should not be task specific. Move rules for one area of the code into path-specific .instructions.md files.\n\n### Does GitHub Copilot read AGENTS.md?\n\nPartly. The Copilot cloud agent and Copilot CLI read AGENTS.md, CLAUDE.md and GEMINI.md, and VS Code chat and GitHub.com code review read AGENTS.md. GitHub.com chat and JetBrains chat do not.\n\n### What is the difference between copilot-instructions.md and .instructions.md files?\n\ncopilot-instructions.md applies to every request in the repository. A .instructions.md file in .github/instructions/ applies only to files matching its applyTo glob, and is combined with the repository-wide file.\n\n### How do I check that Copilot used my instructions?\n\nIn Copilot Chat, expand the References list at the top of a response. If .github/copilot-instructions.md is listed, the file was sent with that request.", "url": "https://wpnews.pro/news/how-to-write-copilot-instructions-md-for-github-copilot", "canonical_source": "https://gethrbr.com/blog/copilot-instructions-md", "published_at": "2026-09-23 00:00:00+00:00", "updated_at": "2026-09-27 16:00:13.289012+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents", "agent-protocols"], "entities": ["GitHub", "GitHub Copilot", "VS Code", "JetBrains"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/how-to-write-copilot-instructions-md-for-github-copilot", "markdown": "https://wpnews.pro/news/how-to-write-copilot-instructions-md-for-github-copilot.md", "text": "https://wpnews.pro/news/how-to-write-copilot-instructions-md-for-github-copilot.txt", "jsonld": "https://wpnews.pro/news/how-to-write-copilot-instructions-md-for-github-copilot.jsonld"}}