copilot-instructions.md Examples: 7 Copilot Files to Copy

Published 2026-10-24 · 6 min read · by AgentKit Co

GitHub Copilot reads a plain Markdown file at .github/copilot-instructions.md and adds it to every chat, cloud agent and code review request in that repository. A good one saves you from repeating "we use pnpm, run the tests, don't touch the generated folder" in every prompt.

This page gives you seven files to copy, explains the path-specific .instructions.md format with applyTo, and lists the fixes for when Copilot seems to ignore you. Everything here was checked on 2026-10-24 against GitHub's repository custom instructions docs, VS Code's custom instructions docs and the June 12, 2026 code review changelog. Copilot changes often, so re-check anything you rely on.

Which file goes where

If a path-specific file matches and a repository-wide file also exists, Copilot uses both. Personal instructions have the highest priority, then repository, then organization, but all relevant sets are sent, so the real fix for a conflict is to remove it rather than rely on order.

1. The minimum useful file

Start here. Four lines that fix the most common agent mistakes:

# Project instructions

- This is a Next.js 15 app using TypeScript and pnpm. Never use npm or yarn.
- Run `pnpm test` and `pnpm lint` after every change and fix failures before you finish.
- Do not edit anything in `src/generated/`; it is rebuilt by `pnpm codegen`.
- Ask before adding a new dependency.

Whitespace between instructions is ignored, so one instruction per line keeps it readable.

2. Next.js + TypeScript

# Project instructions

## Stack
- Next.js App Router, TypeScript strict mode, Tailwind, Prisma, pnpm.

## Architecture
- Server components by default. Add `"use client"` only for state, effects or browser APIs.
- Database access lives in `src/server/db/`. Route handlers call those functions, never Prisma directly.
- Validate every request body with Zod schemas in `src/schemas/`.

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test` (Vitest). Lint: `pnpm lint`. Types: `pnpm typecheck`.

## Don't
- Don't put secrets or API keys in client components or `NEXT_PUBLIC_` variables.
- Don't edit `prisma/migrations/` by hand; run `pnpm prisma migrate dev --name <change>`.

3. Python (FastAPI)

# Project instructions

- Python 3.12, FastAPI, SQLAlchemy 2.0, managed with uv.
- Install with `uv sync`. Run tests with `uv run pytest -q`. Lint with `uv run ruff check .`.
- Routers go in `app/api/`, business logic in `app/services/`, models in `app/models/`.
- Every new endpoint needs a Pydantic request and response model and at least one test in `tests/api/`.
- Use type hints everywhere. Prefer `pathlib` over `os.path`.
- Never print secrets or full request bodies in logs.

4. Go service

# Project instructions

- Go 1.23 module. Build with `go build ./...`, test with `go test ./...`, lint with `golangci-lint run`.
- Return errors, don't panic. Wrap with `fmt.Errorf("doing X: %w", err)`.
- Handlers live in `internal/http/`, storage in `internal/store/`. `cmd/` only wires things together.
- Use the standard library `log/slog` for logging; don't add another logger.
- Table-driven tests in the same package, named `TestThing_Condition`.

5. Code review rules

Copilot code review reads .github/copilot-instructions.md too. Phrase review rules so they only fire during reviews:

## Code review

- When performing a code review, flag any SQL built with string concatenation.
- When performing a code review, flag new dependencies and ask why they are needed.
- When performing a code review, check that every behavior change has a test.
- When performing a code review, don't comment on formatting; the linter handles it.

Two details that older guides get wrong. GitHub removed the 4,000-character limit for code review on June 12, 2026, so long files are no longer cut off. And current docs say code review reads the instructions from the head branch of the pull request, so you can test a change to the file in the same PR.

6. Path-specific instructions with applyTo

Create .github/instructions/tests.instructions.md. The file name must end in .instructions.md, and the frontmatter needs an applyTo glob:

---
applyTo: "**/*.test.ts,**/*.test.tsx"
---

- Use Vitest and Testing Library. Don't use Enzyme.
- Query by role or label, not by test id, unless no accessible name exists.
- One behavior per test. Name tests "does X when Y".

Separate several globs with commas. **/*.py matches Python files in every folder; src/*.py matches only files directly in src/. On GitHub.com, path-specific files are used by Copilot cloud agent and code review; in VS Code they attach automatically when the agent creates or modifies a matching file.

7. Agent-only or review-only files

Add excludeAgent to keep a file away from one of them. This one is read by the cloud agent but not by code review:

---
applyTo: "**"
excludeAgent: "code-review"
---

- Before opening a pull request, run `pnpm test` and paste the summary line into the PR description.
- Keep pull requests under 400 changed lines; split bigger work into stacked PRs.

Use "cloud-agent" instead to make a file review-only.

Why Copilot ignores your instructions

• Wrong place or name. It must be .github/copilot-instructions.md at the repo root, or .github/instructions/<name>.instructions.md. A file named copilot-instruction.md or placed in docs/ is never read.
• You expect it in inline suggestions. VS Code doesn't use custom instructions for the ghost-text completions you get while typing; they apply to chat and agents.
• The applyTo glob doesn't match. *.ts only matches the folder the file is in. Use **/*.ts for the whole repo.
• Conflicting files. A personal rule, an AGENTS.md and copilot-instructions.md that disagree all get sent. Delete the contradiction.
• You can't tell if it loaded. In Copilot Chat, expand the references list at the top of a response and check that .github/copilot-instructions.md is listed. In VS Code, run Chat: Open Customizations to see which files the agent found.
• Vague rules. "Write clean code" changes nothing. "Run pnpm lint before finishing" does. Include the reason for unusual rules so Copilot handles edge cases.

FAQ

Do I need copilot-instructions.md if I already have AGENTS.md? Not always. Copilot reads AGENTS.md, and GitHub also accepts a single CLAUDE.md or GEMINI.md at the root. Keep copilot-instructions.md for Copilot-specific rules such as code review, or generate both from the same source so they can't drift. Our AGENTS.md vs CLAUDE.md vs Cursor rules guide compares them.

How long should the file be? GitHub's own generation prompt caps it at two pages and says not to make it task-specific. Shorter files with exact commands work better than long style essays.

Can Copilot write the file for me? Yes. GitHub's docs include a prompt for Copilot cloud agent that onboards a repo by writing .github/copilot-instructions.md as a draft pull request. Check every command it writes by running it.

Get the matching files for every tool

The free AGENTS.md generator builds a starting copilot-instructions.md plus matching AGENTS.md, CLAUDE.md, Cursor, GEMINI.md and Kiro files in your browser. The AI Coding Agent Config Kit adds 12 stack templates, 3 Copilot instruction files, 8 Cursor rules and 12 prompts that audit and test them.

Keep reading