How to write copilot-instructions.md for GitHub Copilot

What are the types of Copilot custom instructions?

When more than one applies, GitHub sends all of them. Where they conflict, personal instructions win, then repository, then organization.

How do you write copilot-instructions.md?

GitHub'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.

# Payments service

TypeScript, Node 22, Postgres through Prisma. Tests: npm test.

- Webhook handlers must be idempotent. Key on the provider's event id.
- Retries go through src/lib/retry.ts. Five attempts, then dead-letter.
  Why: docs/decisions/0012-webhook-retries.md
- Never edit a migration that has been merged. Write a new one.

The 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.

How do path-specific .instructions.md files work?

A path-specific file lives in .github/instructions/, ends in .instructions.md, and opens with frontmatter naming the paths it covers:

---
applyTo: "src/payments/**/*.ts"
---

Use the shared backoff in src/lib/retry.ts. Do not add a retry loop.

An 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.

Which Copilot features read which instruction files?

Not every surface reads every file. From GitHub's support matrix, for the surfaces most teams use:

The 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.

AGENTS.md vs copilot-instructions.md: which should you use?

If 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.

How do you know Copilot used your instructions?

In 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.

What is Copilot Memory, and does it replace instructions?

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.

It 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.

Where Harbor fits

An 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.

Copilot'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.