What is the difference between Copilot instructions and prompt files?

Instructions files are applied automatically to every request, or to every request about matching files. Prompt files are run on purpose, by typing a slash and the prompt name, and cost nothing until then. VS Code now recommends agent skills for new reusable tasks, because prompt files are not loaded in Agent Host sessions.

Are custom agents the same as chat modes?

Yes. VS Code renamed custom chat modes to custom agents. They combine instructions, a list of allowed tools and an optional model into one reusable role, stored as .agent.md files in .github/agents.

How do I check which context Copilot used?

Expand the References list at the top of a chat response. It shows the instructions files and other context that were applied to that request.

How do I stop Copilot finding generated or vendored files?

Exclude them with .gitignore or the files.exclude setting. VS Code leaves those files out of text search and the semantic workspace index.

Context Engineering With GitHub Copilot: Every Lever, and When to Use It

GitHub Copilot decides what the model sees from instructions files, prompt files, custom agents, skills, #-references, MCP servers and the workspace index. Here is what each one does, where it lives, and which to reach for.

27 September 2026Updated 28 September 20267 min read

Context engineering with GitHub Copilot means choosing, for each piece of information, which of Copilot’s mechanisms carries it. Rules that always apply go in an instructions file. Rules for some files go in a path-specific instructions file. Repeatable tasks go in a prompt file or a skill, loaded only when used. A role with its own tools goes in a custom agent. What a single request needs comes from #-references and the workspace index. Live data from other systems comes through MCP servers. The state of the work belongs outside the chat altogether. The rest of this page takes each lever in turn, as GitHub’s and VS Code’s documentation describe them today.

For the underlying idea, curating what the model sees rather than rewording one prompt, start with context engineering for AI agents. The examples below use Copilot in VS Code, where most of these levers appear first; other editors and GitHub.com support a subset.

Always-on instructions

Three files are read automatically with every request in the places that support them: .github/copilot-instructions.md, AGENTS.md and CLAUDE.md. GitHub’s guide to repository custom instructions (opens in a new tab) says the first applies to all requests made in the context of the repository. Which Copilot surface reads which of these differs, and that question has its own answer in does GitHub Copilot support AGENTS.md.

In VS Code, chat now runs each session through an agent harness: Local, Copilot, Claude or Codex, or a Cloud target. Which instruction files load depends on the harness you pick, and the chat.* instruction settings apply to the Local agent. VS Code’s custom instructions page (opens in a new tab) says the Local agent reads CLAUDE.md when chat.useClaudeMdFile is on, while GitHub’s support table lists only AGENTS.md for Copilot Chat in VS Code.

For context engineering, what matters is the cost. Everything in these files is sent with every request, whether it is relevant or not. Keep them to what a newcomer would need on day one: what the project is, how to build and test it, where things live, which checks must pass. GitHub’s own sample prompt for generating the file asks for no more than two pages and nothing task-specific, which is a good ceiling for your own.

To see whether a file was used, expand References at the top of a chat response. If your instructions file is not listed there, Copilot did not see it.

Instructions that apply to some files

A *.instructions.md file in .github/instructions/ carries an applyTo glob and is used only when Copilot works on matching files. It is the main way to keep the always-on file short: test conventions, migration rules and a component library’s patterns can each move into their own file and stop costing context on unrelated work.

.github/instructions/migrations.instructions.md

---
applyTo: "db/migrations/**/*.sql"
description: "Rules for database migrations"
---
- Never edit a migration that has shipped; add a new one.
- Every migration needs a matching rollback file.

Prompt files: a task you run on purpose

A prompt file is a Markdown file ending .prompt.md, kept in .github/prompts/ for the workspace or in your profile for yourself. You run it by typing / and its name in chat. Its frontmatter can set the agent to use, the model and the tools, so a “write release notes” prompt can run with only read tools switched on. Unlike instructions, a prompt file costs nothing until you call it.

One caution from the VS Code prompt files page (opens in a new tab): prompt files are deprecated for Agent Host sessions and are not loaded there. They still work with the Local agent, and the page recommends moving existing prompts to agent skills. If you are starting fresh, write a skill.

Skills: procedures that load in stages

A skill is a folder with a SKILL.md file, kept in .github/skills/ or .claude/skills/ in the project, or ~/.copilot/skills/ for yourself. Copilot reads only its name and description at first, loads the body when the skill is relevant, and opens any extra files in the folder only when the instructions refer to them. That makes a skill the right place for a long procedure with scripts or examples attached. You can also call one directly with / and its name, adding context after it.

Custom agents: a role with its own tools

Custom agents were previously called custom chat modes; the VS Code custom agents page (opens in a new tab) describes them as instructions, tools and an optional model combined into a reusable configuration for one role. They are .agent.md files in .github/agents/. The tools list is a context lever as much as a safety one: every tool offered is a description the model must read, so a planning agent with read-only tools has less to consider and less it can break. handoffs suggest the next agent in a sequence, such as plan, then implement, then review.

.github/agents/planner.agent.md

---
description: "Plans a change without editing files"
tools: ['search/codebase', 'search/usages', 'web/fetch']
handoffs:
  - label: Start implementation
    agent: agent
    prompt: Implement the plan above.
---
Read the relevant code, then write a numbered plan with the files to change,
the tests to add, and the risks. Do not edit anything.

On GitHub, Copilot cloud agent reads custom agent profiles from .github/agents/ in the repository too, and organisations can share them from a .github or .github-private repository. Tool names differ between environments, so check the ones your editor offers before copying a profile across.

#-references: context for this request only

Everything above is set once. #-references are per request. VS Code’s guide to adding context to chat (opens in a new tab) lists what you can mention by typing #: files, folders and symbols, #codebase for the whole codebase, #fetch with a URL for a web page, tools by name, and terminal output. The active editor is included by default, and you can drag files in from the Explorer or paste a GitHub issue or pull request URL.

Name the two files that matter rather than asking about “the payment code”. A precise reference beats a search the model has to guess at.
Use #codebase when you genuinely do not know where something is, not by habit.
Use #fetch for the one page of external documentation the task depends on, instead of pasting it.
Mention a tool by name when you want that tool used. It removes a decision the model would otherwise make.

The workspace index

When you do not name files, Copilot finds them. The workspace context reference (opens in a new tab) explains that a semantic index lets it search code by meaning rather than keywords. For repositories on GitHub the index is built remotely and is often available at once; for other workspaces Copilot builds one locally and keeps it up to date. Local indexing is on for personal accounts but off by default for organisation and enterprise users. Files matched by .gitignore or the files.exclude setting are left out of search and the index, which is the lever to use when generated code or vendored folders keep turning up in answers. The status appears in the Copilot status dashboard in the Status Bar.

MCP servers: context from outside the repository

An MCP server gives Copilot tools, and sometimes resources, from another system: an issue tracker, a database, a browser. In VS Code they are configured in .vscode/mcp.json under servers, or in your user configuration. The Configure Tools button in the chat input lets you switch individual tools off, and resources a server offers can be attached through Add Context. Each tool you leave on is another description in the model’s context, so switch off what a task does not need.

Outside VS Code, GitHub’s MCP overview for Copilot (opens in a new tab) says the CLI supports local and remote servers and that cloud agent and code review use servers configured at the repository level. For Copilot Business and Enterprise, an organisation policy, “MCP servers in Copilot”, controls whether MCP can be used at all, and it is off by default.

Keep the state of the work outside the chat

None of these levers is a good home for what is in progress, what was decided, or what the last session could not finish. Instructions are for rules that rarely change; chat history ends with the session. Put the work on a board and let every session read it. fenbs connects to Copilot as an MCP server, and one line in your instructions file (“before starting, call fenbs_get_context and list In Progress; when you finish, comment on the task and move it”) turns the board into shared, current context for Copilot and for whichever assistant works on the repository next. Every change it makes is recorded with its name, so you can check what it did afterwards. GitHub Copilot agent mode best practices covers the working habits around that.

Add fenbs to .vscode/mcp.json with the snippet on the GitHub Copilot integration page. The MCP docs list every tool and include one prompt that writes the working rules into .github/copilot-instructions.md and AGENTS.md for you, and AI context explains the notes assistants read before they start.