# GitHub Copilot Customization Surfaces

This is the reference for every place GitHub Copilot reads customization in a VS Code project. `harness-copilot` generates and maintains files at each of these surfaces.

## Why It Matters

GitHub Copilot's behavior is shaped by a small, well-defined set of files. The team that wires them well gets dramatically better suggestions; the team that doesn't wonders why Copilot "doesn't get" their codebase. The files are below.

## The Six Surfaces

| Surface | File | When loaded |
|---------|------|-------------|
| Repository instructions | `.github/copilot-instructions.md` | Every Copilot Chat request in the repo |
| Scoped instructions | `.github/instructions/<name>.instructions.md` | When a file matching `applyTo` is in context |
| Reusable prompts | `.github/prompts/<name>.prompt.md` | Invoked explicitly as `/<name>` |
| Custom agents | `.github/agents/<name>.md` | Picked from the agent picker (Coding Agent, Copilot CLI, VS Code) |
| Universal agent config | `AGENTS.md` | Read by Copilot Coding Agent and most others |
| MCP wiring | `.vscode/mcp.json` | When MCP servers are configured |

## 1. `.github/copilot-instructions.md`

The repo-wide context file. Loaded automatically on every Copilot Chat request in the workspace. **The single highest-leverage Copilot customization.**

- **Target length:** 80–150 lines.
- **Tone:** machine-legible facts. Imperative voice.
- **Anti-patterns:** anything you say twice; long lists of preferences; stale references to files that no longer exist.

### Skeleton

```markdown
# Copilot Instructions for <Project>

Loaded automatically by GitHub Copilot Chat on every request in this repo.

## What This Project Is
…

## Tech Stack
…

## Build & Test Commands
…

## Architecture
…

## Conventions
…

## Verification Checklist
…

## When You Need More Context
…
```

Generate or refresh with `/harness-copilot-instructions`.

Upstream docs: [Adding repository custom instructions for GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot).

## 2. `.github/instructions/<name>.instructions.md`

Scoped rules activated by file-pattern globs. The repo-wide file says "we're a TypeScript monorepo"; a scoped file says "in `src/api/**/*.ts`, every handler returns `Result<Response, Error>`."

### Frontmatter

```markdown
---
applyTo: "src/api/**/*.ts,src/api/**/*.tsx"
description: "API handler conventions"
---

# API Handler Conventions
…
```

- **`applyTo`** is a comma-separated glob list. Copilot loads the file when at least one matching file is in chat context.
- **Multiple narrow files** beat one broad file. Make each one focused.
- **Avoid `applyTo: "**"`** — that belongs in `.github/copilot-instructions.md`.

Generate with `/harness-instructions`.

## 3. `.github/prompts/<name>.prompt.md`

Reusable, parameterizable prompts you invoke as a slash command. Filename minus `.prompt.md` becomes the command — `code-review.prompt.md` → `/code-review`.

### Frontmatter

```markdown
---
description: "Run a code review on the current changes"
mode: agent
---

# Code Review

Steps:
1. Read `git --no-pager diff --staged`.
2. …
```

- **`description`** surfaces in the slash menu.
- **`mode`** is `ask`, `edit`, or `agent`. Use `agent` when the prompt needs to run tools.
- **`tools`** (optional) restricts which Copilot tools the prompt may call.

Generate with `/harness-prompts`. `harness-copilot` itself ships 16 prompts as `.github/prompts/harness-*.prompt.md`.

## 4. `.github/agents/<name>.md`

A specialized Copilot agent persona — a system prompt plus optional tool allowlist and optional MCP server wiring — picked from the agent picker. Persists across the whole conversation or task, unlike a prompt that fires once. Works across the Copilot Coding Agent on GitHub, the Copilot CLI, and VS Code Copilot Chat.

### Frontmatter

```markdown
---
name: planner
description: "Plans changes and writes specs. Never writes application code."
tools: ["read", "search"]
---

You are operating as the **planner** agent. Your job is to design the change, not implement it.

## You Do
- Read relevant source files.
- Ask up to five clarifying questions.
- Produce a numbered plan with verification steps.

## You Never
- Edit application source files.
- Run mutating shell commands.

## Output Format
…
```

- **The `tools` allowlist is the highest-leverage thing a custom agent can do.** A planner agent without write tools literally cannot accidentally implement.
- **Explicit negatives matter more than positives.** "You never write code" prevents the most common persona-violation.
- Optional `mcp-servers` field scopes MCP servers to a single agent.
- Repo-level location is `.github/agents/`. For org-wide agents, place at `agents/<name>.md` inside the org's `.github` or `.github-private` repo.

Generate with `/harness-agents`. Not to be confused with `/harness-agents-md` which generates the universal `AGENTS.md` file (Section 5).

## 5. `AGENTS.md`

The universal agent config file. Read by GitHub Copilot Coding Agent and most other coding agents. Lives at the repo root. **Different from `.github/copilot-instructions.md`** — `AGENTS.md` is tool-neutral and slightly longer-form; `copilot-instructions.md` is Copilot-Chat-specific and shorter.

Keep around 100–120 lines. Cover: build/run commands, structure, architecture, code style, testing, common patterns, key docs, verification, agent-specific notes.

Generate with `/harness-agents-md`.

## 6. `.vscode/mcp.json`

Wires Model Context Protocol servers into Copilot Chat. MCP gives Copilot access to external tools (filesystem, GitHub, databases, search engines) via a standardized protocol.

### Minimal example

```json
{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]
    }
  }
}
```

- Workspace variables: `${workspaceFolder}`, `${env:VAR_NAME}`, `${input:NAME}`.
- Each server can declare `command`, `args`, `env`.
- Keep server scopes minimal — every server expands Copilot's blast radius.

Upstream docs: [Model Context Protocol — VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).

## How They Compose

A typical Copilot harness uses **all six** surfaces together:

```
.github/copilot-instructions.md       Repo-wide map, ~100 lines
.github/instructions/typescript.instructions.md
.github/instructions/tests.instructions.md
.github/instructions/migrations.instructions.md
.github/prompts/code-review.prompt.md
.github/prompts/write-spec.prompt.md
.github/prompts/draft-pr.prompt.md
.github/agents/planner.md
.github/agents/reviewer.md
AGENTS.md                             Tool-neutral, ~120 lines
.vscode/mcp.json                      Tool wiring, ~30 lines
```

Together they encode the team's conventions, workflows, and personas. Each piece has a single job, surfaces at the right moment, and stays under a maintainable line count.

## Activation Priority

Copilot Chat composes context in roughly this order on any given request:

1. `.github/copilot-instructions.md` (always)
2. Matching `.github/instructions/*.instructions.md` (when `applyTo` matches)
3. The currently active prompt file (if a `/<name>` was invoked)
4. The currently active custom agent (if one is selected)
5. `AGENTS.md` (when the Copilot Coding Agent is the one running)

Plus any open files in the editor and the user's message. Treat the total as a budget — concise high-signal files beat verbose ones.

## Maintaining the Surfaces

Customization files rot faster than code. After any PR that touches architecture, dependencies, build/deploy, or conventions, run `/harness-maintain` to refresh `.github/copilot-instructions.md`, `AGENTS.md`, and `ARCHITECTURE.md`. The harness-maintain skill produces surgical edits, not full rewrites.

Pair that with `/harness-entropy` to schedule monthly **instruction-rot detection** — scan the customization files for references to files, functions, and commands that no longer exist.

## Further Reading

- [docs/principles.md](principles.md) — what makes a Copilot harness work.
- [docs/anti-patterns.md](anti-patterns.md) — what to avoid.
- [docs/context-engineering.md](context-engineering.md) — the pillar that governs these files.
- [GitHub Copilot Customization Docs](https://docs.github.com/en/copilot/customizing-copilot).
- [VS Code Copilot Chat Docs](https://code.visualstudio.com/docs/copilot/chat).