Copilot Review Init

Generate a complete set of GitHub Copilot code review instruction files tailored to a specific repository.

What This Produces

GitHub Copilot code review reads instruction files from a PR's repository to guide its analysis. This skill generates:

.github/copilot-instructions.md — Repository-wide review standards applied to every file
Multiple .github/instructions/*.instructions.md — Focused micro-files, each scoped to specific file types via applyTo frontmatter

Why Micro-Files

The micro-file architecture is the core design philosophy. Instead of cramming everything into one file:

Each file stays within Copilot's 4,000-character processing window (content beyond this is silently ignored)
Language-specific rules never bleed into unrelated files
Teams can own and iterate on their relevant instruction files independently
Adding a new concern means adding a new file, not editing a monolith

A well-configured repository typically produces 5-12 instruction files.

Workflow

Phase 1: Explore the Repository

Before writing a single instruction, map the codebase.

Structure

Monorepo vs single-service
Directory layout, package boundaries
Build output directories to ignore

Tech Stack — Scan config files:

package.json, tsconfig.json → TypeScript/JavaScript ecosystem
requirements.txt, pyproject.toml → Python ecosystem
Cargo.toml → Rust; tauri.conf.json → Tauri desktop
go.mod → Go; *.csproj → C#/.NET
docker-compose.yml, .github/workflows/ → Infrastructure/CI

Existing Instruction Files — Check for:

.github/copilot-instructions.md and .github/instructions/*.instructions.md
.cursorrules, .windsurfrules, CLAUDE.md, AGENTS.md, REVIEW.md
CONTRIBUTING.md

If instruction files already exist, read them. The goal is to complement and improve, not overwrite blindly.

Existing Linting & Formatting — This is critical:

ESLint, Prettier, Biome → Skip formatting and style rules
Black, Ruff, isort → Skip Python formatting
rustfmt, clippy → Skip Rust formatting
golangci-lint → Skip Go style rules

Never write instructions for things linters already enforce. Copilot's value is in semantic rules that require understanding intent — not syntactic rules a linter handles better.

Pain Points

Recent PRs and issues for recurring themes
Git history for common bug patterns
TODO/FIXME/HACK comments indicating tech debt

Phase 2: Plan Instruction Architecture

Decide which files to generate based on what you found.

Always generate:

File	Purpose
`.github/copilot-instructions.md`	Universal rules for all files: security, quality, cross-cutting concerns

Generate per language detected:

Stack	File	`applyTo`
TypeScript/JS	`typescript.instructions.md`	`*/.{ts,tsx,js,jsx}`
Python	`python.instructions.md`	`*/.py`
Rust	`rust.instructions.md`	`*/.rs`
Go	`go.instructions.md`	`*/.go`
C#	`csharp.instructions.md`	`*/.cs`

Generate per framework/domain detected:

Concern	File	`applyTo`
React components	`react.instructions.md`	`*/.{tsx,jsx}`
Next.js App Router	`nextjs.instructions.md`	`/app//*.{ts,tsx}`
API routes	`api.instructions.md`	`/api//.{ts,js}` or `/routes//.py`
Database/ORM	`database.instructions.md`	Scoped to model/migration dirs
Tauri commands	`tauri.instructions.md`	`/src-tauri//*.rs`
MCP server	`mcp.instructions.md`	`/src//*.ts`
Tests	`testing.instructions.md`	`*/.{test,spec}.{ts,tsx,js,jsx}`
Docker/infra	`docker.instructions.md`	`*/Dockerfile`
CI/CD	`ci.instructions.md`	`/.github/workflows//*.yml`
Security-critical paths	`security.instructions.md`	Scoped to auth/payment/admin dirs
Accessibility	`a11y.instructions.md`	`*/.{tsx,jsx,html}`

Monorepo strategy: Create package-scoped files when packages have meaningfully different review needs:

packages-api.instructions.md with applyTo: "packages/api/**/*"
packages-web.instructions.md with applyTo: "packages/web/**/*"

Character budget: Aim for 2,500–3,500 characters per file. If a concern needs more, split into two files with narrower scopes rather than exceeding 4,000 characters.

Phase 3: Write Instruction Files

Rule Quality — Every rule must be:

Specific — "All API endpoints must validate request bodies with Zod" not "validate inputs"
Measurable — Unambiguous pass/fail when reviewing code
Actionable — Developer knows exactly what to fix
Semantic — Requires understanding intent, not just pattern matching

Section Ordering — Content near the top of each file carries more weight:

Security-critical rules
Architecture/structural requirements
Error handling patterns
Code quality conventions
Performance considerations
Testing expectations

Code Examples — Include before/after using the repo's actual patterns:

```typescript
// Avoid
const result = await db.query(userInput);

// Prefer
const result = await prisma.user.findUnique({ where: { id: validated.id } });
```

Writing copilot-instructions.md: Include ONLY rules that genuinely apply to ALL code:

Security fundamentals (no hardcoded secrets, input validation)
Cross-cutting quality (error handling philosophy, logging conventions)
Universal naming conventions (if consistent across languages)
Performance red flags (N+1 queries, missing pagination)
Testing philosophy

Do NOT put language-specific rules here.

Writing *.instructions.md micro-files:

Valid YAML frontmatter with applyTo glob string (required)
Under 4,000 characters (aim for 2,500–3,500)
H2 headers for sections, bullet points for rules
1-2 code examples per file
Highest-priority rules first

Frontmatter format:

---
applyTo: "**/*.{ts,tsx}"
---

Phase 4: Validate

Run through this checklist before outputting:

Phase 5: Output

Present generated files as:

File tree — Complete .github/ structure
Each file — Full content in fenced code block with path as heading
Reasoning — Brief note per micro-file explaining what it targets and why

.github/
├── copilot-instructions.md
└── instructions/
    ├── typescript.instructions.md
    ├── react.instructions.md
    ├── api.instructions.md
    ├── database.instructions.md
    ├── security.instructions.md
    └── testing.instructions.md

Reference Files

references/instruction-spec.md — Complete format specification: frontmatter syntax, glob patterns, character limits, what Copilot supports and doesn't. Read when you need format details.
references/anti-patterns.md — Common mistakes and how to avoid them. Includes a debugging sequence for when rules aren't followed. Read before validation.
references/scenarios.md — 8 complete example instruction sets for different tech stacks (TS API, Next.js Dashboard, Django, Go, Tauri, MCP Server, Monorepo, Marketing site). Each shows the full file tree and all generated files. Read the relevant scenario when working with a matching stack.
references/micro-library.md — Comprehensive library of 20+ individual *.instructions.md files organized by language, framework, and domain. Use as adaptation references — match to the actual codebase, don't copy verbatim.

Key Gotchas

Copilot reads only the first 4,000 characters of any instruction file — the rest is silently ignored
*.instructions.md files must live in .github/instructions/ directory
copilot-instructions.md must be in .github/ root
applyTo is a single glob string, not an array — use {ts,tsx} syntax for multiple extensions
Copilot cannot follow external links — inline all content
Instructions cannot change comment format, PR overview, or merge behavior
Non-deterministic behavior is normal — Copilot won't follow every instruction every time
Missing or empty applyTo on a *.instructions.md means the file applies to nothing
Start with 10–20 focused rules across files and iterate based on real PR results

copilot-review-init