GitHub Copilot has grown from inline autocomplete into a family of AI features: chat and agent mode in your editor, a command-line agent, a cloud agent that takes an issue and opens a pull request, and automated code review. Because it lives inside GitHub, it can connect your issues, branches, pull requests and CI into one workflow.

This guide explains every file Copilot reads, how to configure each feature, and a practical, test-first process for building a web application with it.

The pieces of Copilot

  • Code completion – inline suggestions as you type.
  • Copilot Chat – ask questions about your code. In editors like VS Code it has modes, including an agent mode that can edit multiple files, run terminal commands and use tools.
  • Copilot CLI – an agent in your terminal.
  • Cloud agent – assign a GitHub issue to Copilot and it works in a cloud environment powered by GitHub Actions, then opens a pull request for you to review.
  • Code review – request Copilot as a reviewer on a pull request.

All of them get better when you give them project context through the files below.

The complete file map

text
my-web-app/
├─ AGENTS.md                               # Cross-tool agent instructions (nearest file wins)
├─ .github/
│  ├─ copilot-instructions.md              # Repository-wide instructions for Copilot
│  ├─ instructions/
│  │  ├─ frontend.instructions.md          # applyTo: "src/components/**/*.tsx"
│  │  └─ api.instructions.md               # applyTo: "src/app/api/**/*.ts"
│  ├─ prompts/
│  │  └─ new-feature.prompt.md             # Reusable prompt, run as /new-feature in chat
│  ├─ agents/
│  │  └─ test-specialist.agent.md          # Custom agent profile
│  └─ workflows/
│     ├─ ci.yml                            # Your normal checks
│     └─ copilot-setup-steps.yml           # Prepares the cloud agent's environment
├─ .vscode/
│  └─ mcp.json                             # MCP servers for VS Code agent mode
└─ src/ …

.github/copilot-instructions.md: repository-wide instructions

This Markdown file is added to Copilot's context for chat, agent and review requests in the repository. Write short, specific, verifiable statements about how your project works.

markdown
# Acme Tasks

Next.js 16 App Router, TypeScript, Postgres with Drizzle, Tailwind CSS. Package manager: pnpm.

## Build and test
- Install with `pnpm install`.
- Before finishing any change, run `pnpm lint`, `pnpm typecheck` and `pnpm test`.
- End-to-end tests use Playwright: `pnpm test:e2e`.

## Conventions
- Server components by default; use "use client" only for interactive components.
- Database access only through `src/db/queries/`.
- Validate API input with the zod schemas in `src/lib/schemas.ts`.
- Never hard-code secrets; read them from environment variables on the server.

## Pull requests
- Keep changes focused on one issue. Include tests for new behaviour.

Good instructions describe the project, the exact commands, the conventions and what "done" means. Avoid vague style advice and long essays; they cost context without changing behaviour.

Path-specific instructions: .github/instructions/*.instructions.md

For rules that only apply to part of the codebase, create files under .github/instructions/ with an applyTo glob in the frontmatter. They are added only when Copilot works on matching files.

markdown
---
applyTo: "src/app/api/**/*.ts"
---

- Validate the request body with zod before any other logic.
- Return errors as { error: { code, message } } with the correct HTTP status.
- Every route needs an integration test in tests/api/.

You can separate multiple patterns with commas, such as "**/*.ts,**/*.tsx". An optional excludeAgent field ("code-review" or "cloud-agent") keeps a file away from one of those features.

AGENTS.md: shared instructions across tools

Copilot also reads AGENTS.md files, the cross-tool standard used by Codex, Claude Code and others. When several exist, the nearest one in the directory tree takes precedence. If your team uses more than one AI tool, a practical split is:

  • `AGENTS.md` – shared rules for every agent: commands, architecture, testing and security.
  • `.github/copilot-instructions.md` – Copilot-specific additions only.

Prompt files: .github/prompts/*.prompt.md

Prompt files are reusable, parameterised prompts for common tasks. In supported IDEs you run them from chat by typing / and the file name. They are ideal for procedures you repeat: scaffolding a feature, writing tests for a file or preparing a release.

markdown
---
description: Scaffold a feature with route, UI, unit tests and an end-to-end test
agent: agent
tools: ["codebase", "editFiles", "runCommands"]
---

Create the feature described by the user.
Follow the structure of an existing feature in [src/features](../../src/features).
1. Write failing unit tests and one Playwright test first, then run them.
2. Implement until they pass without changing the tests.
3. Run lint and typecheck, then summarise the changes.

Prompt files can reference other files with Markdown links, so the agent reads your real patterns instead of guessing. Frontmatter options vary by editor version; the description, the agent or mode to run in, the model and the tools available are the common ones.

Custom agents: .github/agents/*.agent.md

A custom agent is a specialised version of Copilot with its own instructions, tools and optional MCP servers. It appears in the agent picker in your IDE and in the dropdown when you assign an issue to the cloud agent.

markdown
---
name: test-specialist
description: Improves test coverage and quality without modifying production code
tools: ["read", "edit", "search"]
---

You are a testing specialist. For the code in question:
- Identify untested behaviour and edge cases.
- Write clear unit and integration tests that follow the existing test style.
- Never change production code. If a bug is found, describe it instead of fixing it.

The description is required. tools restricts what the agent can use (leave it out to allow all tools), mcp-servers adds servers only this agent can reach, model picks a model in supported IDEs and target limits the agent to the IDE or to GitHub. Organisations can share custom agents across all repositories from their .github repository.

MCP servers

In VS Code, MCP servers for the workspace are configured in .vscode/mcp.json, under a top-level servers object. Each server needs a type (stdio, http or sse). The optional inputs array lets you prompt for secrets instead of committing them.

json
{
  "servers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

MCP tools are available in agent mode, not in plain ask or chat mode. The cloud agent has its own MCP configuration in the repository settings on GitHub, and custom agents can declare their own servers.

Preparing the cloud agent: copilot-setup-steps.yml

The cloud agent works in an ephemeral environment powered by GitHub Actions. If it cannot install your dependencies or run your tests, it cannot verify its work. Create .github/workflows/copilot-setup-steps.yml on your default branch with a single job named exactly `copilot-setup-steps`:

yaml
name: Copilot setup steps
on: workflow_dispatch
jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm exec playwright install --with-deps chromium

Only a limited set of job keys is honoured, including steps, permissions, runs-on, container, services and timeout-minutes. Services are useful for giving the agent a real Postgres or Redis to test against.

Step by step: building a web app with Copilot

Step 1: Create the repository and a clean baseline

Scaffold the app with your framework's generator, push it to GitHub and set up a CI workflow that runs lint, type checking and tests on every pull request.

Step 2: Add the instruction files

Write .github/copilot-instructions.md (or AGENTS.md plus a short Copilot file). Add path-specific instructions for areas with special rules, such as API routes or UI components. Copilot can also draft these for you from the chat; review the result.

Step 3: Build the test harness first

In agent mode, ask Copilot to configure unit tests (Vitest or Jest), component tests (Testing Library) and end-to-end tests (Playwright), and to add the scripts to package.json. Run each yourself once. These commands are how every Copilot feature verifies its work.

Step 4: Plan the work as issues

Break the application into small, well-described GitHub issues. Each should state the goal, acceptance criteria, relevant files and how to test it. Good issues are the single biggest factor in cloud agent quality.

markdown
## Goal
Users can set a due date on a task.

## Acceptance criteria
- Date picker on the task form; stored as UTC in the `tasks.due_at` column.
- Overdue tasks show a red badge in the list.
- Unit tests for the overdue helper; a Playwright test for setting a due date.

## Notes
Follow the pattern used for the `priority` field in src/features/tasks.

Step 5: Build interactively in agent mode

For work you want to steer closely, use agent mode in your editor. Reference files with # context, run your prompt files for repeatable tasks and ask for tests first. Review each change as it lands and keep the terminal commands visible.

Step 6: Delegate well-defined issues to the cloud agent

Assign an issue to Copilot, optionally choosing a custom agent. It works in its own branch using your setup steps and opens a pull request, which you can steer by leaving review comments. Use it for tasks with clear acceptance criteria: small features, bug fixes, test coverage and refactors.

Step 7: Review every pull request

Request Copilot code review for a first pass, then review it yourself. Check that tests were not weakened, that authorisation checks are present, that no unexpected dependencies were added and that the change stays in scope. CI must pass before merging.

Step 8: Iterate on the instructions

When Copilot repeats a mistake, add a specific rule to the relevant instruction file. Over time these files become a precise description of how your project works, for people and for agents.

Testing strategy with Copilot

  • Acceptance criteria become tests. Ask Copilot to turn each issue's criteria into tests before implementing.
  • Give the cloud agent real services. Use services in the setup steps for databases, so integration tests are meaningful.
  • Protect the tests. Watch for tests that were edited, skipped or loosened to make a pull request pass.
  • End-to-end tests for key journeys. Sign-up, checkout and core workflows deserve Playwright coverage that runs in CI.
  • Use a custom test agent. A test-specialist agent that cannot edit production code is a safe way to raise coverage.

Security checklist

  • Never commit secrets; use GitHub Actions secrets and environment variables.
  • Keep the permissions in copilot-setup-steps.yml minimal.
  • Review MCP servers before enabling them, and give them narrowly scoped tokens.
  • Treat content in issues and comments as untrusted input, since it can contain prompt injection.
  • Require review and passing CI before any agent-authored pull request merges, using branch protection.

Key takeaways

  • .github/copilot-instructions.md gives Copilot repository-wide context; .instructions.md files add rules for specific paths.
  • AGENTS.md shares instructions across AI tools; prompt files capture reusable tasks.
  • Custom agents in .github/agents/ create specialised assistants with limited tools.
  • The cloud agent turns well-written issues into pull requests; copilot-setup-steps.yml makes sure it can run your tests.
  • Tests, CI and human review remain the final authority on every change.