Skip to main content

Copilot Context, Instructions, and Governance

What this page covers

Copilot quality depends heavily on context. This page explains how to teach Copilot your repository conventions, when to use AGENTS.md, where Spaces and MCP fit, and which governance details matter once a team moves beyond casual experimentation.

1. Start with repository instructions​

If Copilot does not know how your project is organized, how you test changes, or what "done" means, the model quality matters less than you think.

GitHub supports repository custom instructions so Copilot can pick up project-specific guidance automatically.

The main building blocks are:

  • .github/copilot-instructions.md for repository-wide guidance,
  • .github/instructions/*.instructions.md for path-specific guidance,
  • AGENTS.md for agent-oriented instructions close to the working directory,
  • personal and organization instructions for broader preferences.

GitHub's docs also note that Copilot can use CLAUDE.md or GEMINI.md at repository root as alternatives in some agent workflows, but AGENTS.md is the most portable choice if you want agent-facing instructions without tying the repo to one model vendor.

2. A practical copilot-instructions.md​

Keep repository instructions short, concrete, and operational. Good instructions answer:

  • how the repo is structured,
  • which commands build, test, lint, or validate changes,
  • what language, framework, and style conventions matter,
  • what should never be changed casually,
  • how to decide whether a task is complete.

Example:

# Project conventions

- Use Yarn for package management.
- Run `yarn build` before considering documentation changes complete.
- Write source docs in English.
- Keep MDX frontmatter concise and consistent with nearby pages.
- Prefer updating existing pages over creating near-duplicate content.

The goal is not to describe everything. The goal is to remove the mistakes Copilot would otherwise repeat.

3. Where AGENTS.md fits​

AGENTS.md is useful when you want instructions that are especially relevant to agentic work:

  • approval and editing rules,
  • validation expectations,
  • repository boundaries,
  • workflow preferences for autonomous changes.

It is especially valuable in larger monorepos because GitHub documents that the nearest AGENTS.md in the directory tree takes precedence when Copilot is working. That makes it a good fit for area-specific behavior.

Use AGENTS.md when:

  • subprojects have different rules,
  • agent behavior needs stronger control than a generic instructions file,
  • your team already shares conventions across multiple coding agents.

4. Copilot Spaces​

Copilot Spaces are the collaborative context layer. A space can include:

  • repositories,
  • code,
  • pull requests,
  • issues,
  • notes and transcripts,
  • images and uploads.

This makes Spaces useful for:

  • onboarding,
  • feature or incident context packs,
  • recurring team workflows,
  • cross-repository questions where normal chat history is too fragile.

Spaces are not a replacement for repository instructions. They solve a different problem:

  • instructions define stable project behavior,
  • Spaces collect task or domain context that people want to reuse and share.

5. MCP in Copilot​

MCP is where Copilot becomes meaningfully extensible.

GitHub documents MCP support across:

  • IDE clients,
  • Copilot CLI,
  • the GitHub Copilot app,
  • repository-level configuration for cloud agent and code review.

Two especially important operational details:

  • Copilot CLI supports both local and remote MCP servers.
  • For repository-level GitHub workflows, the GitHub MCP server and Playwright MCP server are enabled by default for cloud agent and code review.

This means Copilot can move beyond "answer based on repo text" into "use tools and external systems," but it also means access control matters a lot more.

For a deeper GitHub-specific MCP breakdown, see the GitHub MCP Server - Developer Guide.

6. Governance that actually matters​

Once Copilot is used by a team instead of one developer, the important questions shift.

You need to know:

  • which models are allowed,
  • who can use cloud agent,
  • whether code review is enabled,
  • whether MCP is allowed and from which registry,
  • how usage and AI credits are monitored,
  • which repositories are opted in or out.

This is where Copilot becomes less of a personal assistant and more of a platform capability.

7. Important caveats for real repositories​

Some details are easy to miss:

  • cloud agent and some advanced customization features depend on paid plans and policy configuration,
  • cloud agent uses both AI credits and GitHub Actions resources,
  • repository custom instructions can affect chat, code review, and agent sessions,
  • GitHub documents that cloud agent does not respect content exclusions in the same way other Copilot features do, so sensitive-repo rollout needs extra care.

That last point is especially important for enterprises. If you rely on exclusions for safety, verify feature-by-feature behavior before broad rollout.

8. A sane team rollout​

If you are introducing Copilot in a repository or organization, a low-drama rollout usually looks like this:

  1. Add repository instructions.
  2. Decide where AGENTS.md is needed.
  3. Pilot IDE chat or CLI on a small group.
  4. Enable cloud agent only for repositories with clear review discipline.
  5. Add MCP servers incrementally, not all at once.
  6. Review credits, auditability, and policy settings before scaling to the whole team.

Copilot gets noticeably better when the team treats context as infrastructure, not as optional decoration.