Skip to content

GitHub Copilot custom instructions: copilot-instructions.md generator

GitHub Copilot reads repository-wide custom instructions from .github/copilot-instructions.md, and path-specific instructions from .github/instructions/NAME.instructions.md files whose applyTo frontmatter holds glob patterns. Copilot cloud agent, code review and Copilot CLI also read AGENTS.md.

Generate a Copilot instructions file

Where the file goes

How it works

Tips for a good Copilot instructions

Example: Node.js + Express + Prisma + Zod validation

.github/copilot-instructions.md
# Copilot instructions - this project

A Node.js + Express + Prisma + Zod validation project.

Stack: Node.js + Express, Prisma, Zod validation.

## Commands

- Dev server: `npm run dev`
- Build: `npm run build`
- Type-check: `npx tsc --noEmit`
- Create and apply migration (dev): `npx prisma migrate dev --name <change>`
- Regenerate client: `npx prisma generate`
- Apply migrations (prod): `npx prisma migrate deploy`

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
.github/instructions/express.instructions.md
---
applyTo: "src/**/*.ts"
---

# Node.js + Express

- Express 5 forwards rejected promises from async handlers to the error middleware; do not wrap every handler in try/catch.
- Have one central error-handling middleware that logs the error and returns a consistent JSON error shape.
- Validate every request body, query and param before using it.
- Use `helmet`, a strict CORS allow-list and rate limiting on public endpoints.
- Read config from env vars once at startup in a typed config module; fail fast if a required var is missing.
- Return correct HTTP status codes (400 validation, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict).
.github/instructions/prisma.instructions.md
---
applyTo: "prisma/**,**/*.prisma"
---

# Prisma

- Change the database only through `schema.prisma` + `prisma migrate dev`. Never edit an applied migration.
- Reuse a single PrismaClient instance (cache it on `globalThis` in dev to survive hot reload).
- Use `select` / `include` to fetch only the fields you need.
- Wrap multi-step writes in `prisma.$transaction`.
- Run `npx prisma generate` after schema changes before type-checking.
.github/instructions/zod.instructions.md
---
applyTo: "**/*.ts,**/*.tsx"
---

# Zod validation

- Validate all untrusted input (request bodies, form data, env vars, third-party API responses) with a Zod schema at the boundary.
- Derive TypeScript types from schemas with `z.infer<typeof schema>`; do not hand-write duplicate types.
- Use `safeParse` where you need to return validation errors to the user.

FAQ

Where do Copilot instructions go?

In .github/copilot-instructions.md in the repository, plus optional .github/instructions/*.instructions.md files.

Does Copilot read AGENTS.md?

Yes. GitHub calls AGENTS.md, CLAUDE.md and GEMINI.md "agent instructions". The Copilot cloud agent, code review and Copilot CLI read all three, and Copilot Chat in VS Code reads AGENTS.md.

Copilot instructions templates by stack

Official docs: GitHub Copilot custom instructionsCustom instructions supportCopilot CLI changelog. Last reviewed 2026-11-11.