GitHub Copilot: Complete Engineering Guide

“Copilot” names a family of products that share a brand, a subscription and a customisation layer, and otherwise differ substantially in where they run, what they can do, and which configuration they read.

This article is the map. It is deliberately built around what each surface is for rather than around interface details, because the interfaces change and the shape does not.

Before you start

• The AI + Git cluster — the habit of supplying real repository state
• Pull requests — where most Copilot output arrives

The surfaces

Surface	Runs	Supervision	Typical output
Code completion	Editor, inline	Every keystroke	A line or a block
Copilot Chat	Editor or github.com	Conversational	Explanation, a snippet
Agent mode	Your local workspace	Approve each action	Multi-file edits
Copilot CLI	Your terminal	Approve each action	Edits, commands, Git operations
Copilot code review	Pull requests	Asynchronous	Review comments
Copilot cloud agent	GitHub-hosted environment	None during	A branch and a pull request

The distinction that matters most, and the one this pillar keeps insisting on:

Agent mode makes autonomous edits in your local development environment. The cloud agent works autonomously in a GitHub-hosted, Actions-powered environment on tasks assigned through issues or chat.

GitHub’s own documentation states these are distinct features. Treating them as interchangeable produces confusion about where code appears, what credentials are in play, and who is watching.

Code completion

The original surface, and still the most-used. Inline suggestions as you type, from the current file and related context the editor supplies.

Its characteristic is narrow context and high frequency. It is excellent at finishing a line you have started, implementing an obvious function body, and writing the repetitive parts of a test. It is unreliable for anything whose correctness depends on code it cannot see — which is most things.

The verification cost is low because the unit is small: you read the suggestion before accepting it, and a wrong one is obvious in the moment.

Copilot Chat

Conversation, in the editor or on github.com. Covered in full in Copilot Chat.

The engineering-relevant property is that chat quality is a function of attached context rather than of phrasing. A question about a function, asked with the file attached, produces a different class of answer than the same question asked cold.

Agent mode

Copilot determines which files to change, proposes edits and terminal commands, and iterates until the task is done — in your workspace, with your approval at each step. Agent mode covers it properly.

The step change from chat is that it acts and observes: it can run your tests, read the failure, and adjust. That loop is what makes multi-file work possible and is also what makes supervision matter.

Copilot CLI

The terminal surface, with an explicit permission model, custom agents, skills, hooks and MCP. It is substantial enough to have its own cluster.

Copilot code review

Reviews pull requests and suggests fixes. Requested manually or configured to run automatically. See the code review cluster.

Copilot cloud agent

Delegated work. Tasks start from the agents panel on github.com, from an issue, from VS Code, or by mentioning @copilot in a pull request comment. It works in an ephemeral GitHub-hosted environment powered by GitHub Actions, on a branch, and opens a pull request.

Documented constraints worth knowing: it works on one branch per session and can open one pull request per task, it can only change the repository the task started in, and sessions have a hard 59-minute limit. See Copilot Cloud Agent.

The customisation layer

The part that is common across surfaces, and the reason this cluster exists. Each mechanism differs in when it is loaded, which is the property that determines what it is for.

Mechanism	Loaded	Location
Repository instructions	Always	.github/copilot-instructions.md
Path-specific instructions	When matching files are in scope	.github/instructions/**/*.instructions.md
Agent instructions	Always, by agent surfaces	AGENTS.md, CLAUDE.md, GEMINI.md
Prompt files	When you invoke one	.github/prompts/*.prompt.md
Agent skills	When the agent judges them relevant	.github/skills/<name>/SKILL.md
Custom agents	When selected	.github/agents/NAME.md
MCP servers	When configured	mcp.json, repository settings, agent config
Hooks	At lifecycle events	.github/hooks/*.json
Plugins	When installed	A directory with plugin.json

Three of these are constantly confused, and the difference is worth stating precisely:

Instructions are always on. Every line costs context on every request. This is why a long instructions file makes results worse.

Prompt files are invoked. You choose to run one.

Skills are loaded when relevant. The agent decides, from the skill’s description. That makes the description the most important field in the file.

Support is not uniform across surfaces

The most common Copilot customisation problem is a mechanism that works in one place and not another.

Prompt files are the clearest example: available in VS Code, Visual Studio and JetBrains IDEs, and not on github.com or in Copilot CLI. Hooks, skills and the various instruction types each have their own matrix, and those matrices change as features ship.

Every page in this pillar states the position for the surface it covers. GitHub publishes a support matrix, and that is the artefact to check rather than any page here.

Availability

Copilot capabilities vary by plan — Copilot Free, Pro, Pro+, Business and Enterprise — and several are governed by organisation or enterprise policy. Some features are in public preview. Availability also differs by IDE. Confirm the current position in the GitHub Copilot documentation.

Plans and policy, without a pricing table

Plan names are stable enough to state; entitlements are not, and a table of them here would be wrong within months.

The current plans are Copilot Free, Copilot Pro, Copilot Pro+, Copilot Business and Copilot Enterprise.

What matters architecturally is not the price but the control surface:

Individual plans are configured by the individual. Fine for a personal repository, and it means your organisation has no view of usage or policy.

Business and Enterprise add organisation-level policy: which features are enabled, whether the cloud agent is available, content exclusion, and — for the review cluster — whether Copilot approvals can satisfy required reviews. Administrators must enable the cloud agent for Business and Enterprise users; it is not on by default.

The practical consequence for a team: “can I use this feature” is frequently an organisation policy question rather than a plan question. Check the policy before concluding a feature is unavailable.

Plugins and extensions

Two mechanisms for extending Copilot beyond what it ships with, worth distinguishing.

Plugins are installable packages that bundle capabilities. A plugin directory contains at minimum a plugin.json manifest at its root, and can provide agents, skills, hooks and MCP or language-server configuration together. In Copilot CLI they can be installed imperatively with copilot plugin install or declaratively through configuration, and marketplaces — defined by a marketplace.json — make them discoverable. Copilot ships with default marketplaces registered.

Extensions for Copilot CLI add tools and slash commands to the terminal surface specifically.

The engineering point is not the mechanics but the trust question. A plugin can contain hooks, MCP server configuration and agents — which is to say it can add shell commands that run at lifecycle points and tools the agent can call. Installing one is closer to installing a dependency than to changing a setting, and it deserves the scrutiny of dependency security: who publishes it, what it contains, and what it can reach.

For an organisation, enterprise plugin standards exist precisely so this is a policy decision rather than an individual one.

Enabling and configuring

The order that avoids the common frustrations.

1. Confirm your entitlement. Which plan, and — on Business or Enterprise — which features your administrator has enabled. The cloud agent in particular is off by default for those plans.

2. Install for your editor, and sign in. Completions and chat should work immediately.

3. Check organisation policy if something is missing. Content exclusion, feature toggles and model restrictions all present as “the feature is not there”.

4. Add repository instructions before doing anything else substantial. This is the highest-value configuration and it improves every surface at once.

5. Try agent mode on something small and reversible — a disposable branch, a well-covered module.

6. Add path-specific instructions where review or generation criteria genuinely differ.

7. Consider the CLI if terminal work is a large part of your day.

8. Leave skills, custom agents, MCP and hooks until you have a specific need. Each is useful and each is configuration to maintain.

Step 4 before step 5 is deliberate. Agent mode without instructions produces generically-reasonable code that does not match your codebase, and the experience of correcting it repeatedly is what makes people conclude the tool is not useful.

Content exclusion and what leaves your environment

Worth understanding before adopting Copilot broadly, and frequently the first question from anyone responsible for the codebase.

Content exclusion lets administrators specify paths that Copilot should not use as context. Typical candidates: directories containing customer data fixtures, generated secrets, or code under a contractual restriction.

Two honest caveats about it.

It is a context control, not an access control. It shapes what Copilot reads. It is not a substitute for the files not containing secrets in the first place — that is Pillar 5’s territory.

Exclusion is not universal across surfaces, and its effect on an agent that can run shell commands is different from its effect on completions. An agent that can cat a file is in a different position from a completion engine that was told not to index it.

The broader point for a team: what reaches a model is a function of what you attach, what the tool indexes, and what an agent can reach with its tools. Those are three different questions, and only the first is under the individual developer’s control.

Model selection

Copilot exposes a choice of models on several surfaces. Two durable things can be said, and a third cannot.

Capability, latency and cost trade off. A larger model reasons better over a complex multi-file change and is slower. A faster one is better for iterative work where you are in the loop.

Availability depends on plan and policy. Model lists differ by subscription and can be restricted by an organisation.

What is not durable is any ranking of specific models. Names and capabilities change on a timescale of months, and a page maintaining a league table is a page that is wrong. The useful habit is to know that the choice exists, that /model in the CLI and equivalent controls elsewhere expose it, and to pick by the trade-off rather than by reputation.

Copilot Memory

Copilot can retain facts about a repository and coding preferences across sessions, rather than starting fresh each time.

The engineering considerations are the same as for any persistent inferred state.

It is inferred, not declared. A memory is Copilot’s conclusion from observing your work. That is useful and means it can be wrong — a convention you abandoned may persist as a remembered preference.

Review it. Whatever interface your surface provides for inspecting and removing memories is worth using periodically, particularly after a significant change of direction.

It is not a substitute for instructions. A memory is inferred and per-context; repository instructions are explicit, reviewed, versioned and shared with the team. Anything that matters belongs in instructions, where it is in the repository and in review.

Consider what it implies for privacy. Persisted observations about a codebase are data, and organisations with content restrictions may have a position.

Support varies by surface — this is not a capability to assume is present everywhere.

Copilot Spaces

A mechanism for organising and sharing context for a particular task or area — collecting the repositories, files and notes relevant to a piece of work so that Copilot has them without you attaching them every time.

The useful framing: it addresses the context problem from the pillar hub at a level above individual requests. Where instructions carry conventions and skills carry task knowledge, a Space carries the material for a body of work.

Choosing a surface for a task

The practical question, answered as a decision rather than a feature list.

Task	Surface	Why
Finishing a line, an obvious block	Completion	Fastest, and you see it before accepting
Understanding unfamiliar code	Chat, with the file attached	The context is the whole answer
A change spanning several files	Agent mode	It can read what it needs and iterate
Anything where the loop is run-read-adjust	Agent mode or CLI	The observe step is what helps
Terminal-heavy work: Git, Docker, infrastructure	Copilot CLI	The context is already there
A well-specified task you do not want to watch	Cloud agent	Delegation, returning a PR
Reviewing somebody else’s change	Copilot code review	Runs where review happens
Reviewing your own before pushing	CLI /review, or chat with the diff	Cheapest layer

Two patterns worth naming.

Escalate rather than start big. Chat first; if the answer requires acting, move to agent mode; if it requires no supervision and is well specified, delegate it. Starting with delegation on a task you have not thought through produces a confident pull request solving the wrong problem.

Match the supervision to the reversibility. A local branch you can delete tolerates a supervised agent making a mess. A shared environment does not, which is why the CLI cluster spends so long on permissions.

AI-generated code, and the verification chain

The same chain from the pillar hub, stated once here in full because every subsequent article refers to it.

AI output  →  Compile / validate  →  Tests  →  Static analysis  →  Security scan  →  Human review

The failure modes that make each step necessary:

Hallucinated APIs. A method that does not exist on a class that does. The compiler catches it, which is why building is a real check.

Obsolete patterns. Idioms from an older major version of a library, which compile and behave subtly differently.

Plausible wrong dependencies. A package name that sounds right and is somebody else’s. Dependency review is the layer for this, and it is worth reading the added dependencies in any AI-assisted change manually.

Hidden assumptions. Code correct under an assumption about your system that nobody stated. Tests catch this only if they encode the assumption.

Security patterns that look right. Escaping for the wrong context, a validation checking the wrong property. Code scanning catches some; review catches more.

Licensing. Generated code resembling something under an incompatible licence. The control is your existing provenance process rather than anything Copilot-specific, and it is a real consideration for anything you redistribute.

None of these is a reason not to use the tool. They are the reason the chain exists, and the reason that the time saved writing is partly spent verifying.

What Copilot does not change

Worth stating in the cornerstone article, because it is the thread through the whole pillar.

Your merge policy. Rulesets apply to Copilot output as to anything else. The cloud agent is subject to them — and notably, a rule restricting commit authors can prevent it from creating or updating pull requests unless administrators add Copilot as a bypass actor, which is a decision worth making deliberately.

Your review requirements. Copilot reviews do not count toward required approvals by default.

Your CI. Tests run on the pull request regardless of who wrote the code.

Your security scanning. Code scanning and dependency review evaluate the diff, not the author.

Accountability. Somebody merges; that person answers for it.

Rolling it out across a team

Individual adoption is a setting. Team adoption is a change to how code gets written and reviewed, and the parts that go wrong are organisational.

Agree the customisation before the tooling. A repository with good instructions gives every developer the same baseline. Without them, each person corrects the same things individually and concludes different things about whether the tool works.

Decide the review position explicitly. Does AI-assisted code get reviewed differently? The correct answer is no — and it needs saying, because the alternative is that it drifts lighter without anyone deciding.

Expect the disclosure question. Whether contributors should mark AI-assisted changes is a policy question with reasonable answers on both sides. What matters is having one, particularly for repositories accepting outside contributions.

Watch the review queue. More code produced per developer means more code to review by the same reviewers. That arithmetic is the practical limit on how much any of this helps, and it bites before any technical limit does.

Measure something real. Not lines generated or suggestions accepted — those measure usage. Time-to-merge, review round trips, and defect escape rate measure whether the process improved. If none of them moved, usage numbers are not evidence of anything.

The failure pattern worth watching for: velocity increases, review depth decreases, and the second one is invisible until an incident. Guard against it by keeping the review layers explicit, which is what the code review cluster is about.

Common mistakes

Using “agent mode” and “cloud agent” interchangeably. Different environments, different supervision, different output.

Assuming customisation works everywhere. Check the surface.

Writing enormous instructions files. Always-on context is charged per request.

Expecting instructions to be enforcement. They shape a probabilistic process. Rulesets and hooks enforce.

Concluding a feature is unavailable without checking policy. On Business and Enterprise it is frequently an administrator setting.

Treating memory as configuration. It is inferred and per-context; instructions are declared and shared.

Optimising the model choice before the context. Attaching the right file improves output more than changing models does.

Keeping this page’s claims current

Copilot changes faster than anything else this site documents, so it is worth being explicit about which parts of this article age and which do not.

Durable: the distinction between surfaces, the fact that customisation mechanisms differ in when they load, the verification chain, and the observation that merge policy is unchanged by authorship.

Ages quickly: exact feature availability per surface, which capabilities are in preview, model lists, and the precise contents of the support matrix.

Ages silently: feature names. “Coding agent” became “cloud agent”; a page using the old name still reads fluently while describing something by a name GitHub no longer uses. That is the failure mode this pillar works hardest to avoid, and the reason every page states what was checked and when.

The practical advice: treat any specific claim about availability here as a prompt to check, and GitHub’s own documentation as the answer. This page is a map of the territory, not a snapshot of the feature list.

Mental model

Copilot is one subscription over several surfaces that differ in where they run and how closely you watch. The customisation layer is what makes them behave like your codebase rather than an average one — and what varies between them is when each piece of configuration gets loaded.

What you learned

• Six surfaces: completion, chat, agent mode, CLI, code review, cloud agent
• Agent mode is local and supervised; the cloud agent is GitHub-hosted and delegated
• The cloud agent works on one branch per session, one PR per task, in one repository, capped at 59 minutes
• Instructions are always on, prompt files are invoked, skills load when judged relevant
• Customisation support differs by surface, and prompt files are the clearest example
• Plans are Free, Pro, Pro+, Business and Enterprise; feature availability is often policy rather than plan
• Model choice is a latency/capability trade-off, not a ranking worth memorising
• Memory is inferred and reviewable; instructions are declared, versioned and shared
• Rulesets, CI, security scanning and accountability are unchanged by who wrote the code

Exercise

Use a disposable repository.

1. List which Copilot surfaces you actually have access to. Predict: is anything missing because of plan, or because of organisation policy?

2. Add a .github/copilot-instructions.md with three specific conventions. Ask chat a question that would violate one. Predict: does the instruction hold?

3. Try the same in a second surface — the CLI, or github.com. Predict: does the instruction apply there?

4. Create a prompt file. Predict: which surfaces can invoke it?

5. Ask the same question with and without the relevant file attached. Compare.

6. If you have model selection, run the same multi-file task with two models and compare quality against time.

7. Delete the repository.

Related lessons

Copilot agent modeThe local agentic surface, in full.

Custom instructionsThe always-on customisation layer.

Repository instructions for AI agentsChoosing between the mechanisms.

Copilot cloud agentThe delegated surface, and how it differs.