GitHub Copilot Custom Instructions: The Complete Guide

What are GitHub Copilot custom instructions?

GitHub Copilot custom instructions are markdown files that tell Copilot how to generate code for your project. They work like Cursor rules or CLAUDE.md — persistent context that shapes every AI suggestion.

Without custom instructions, Copilot relies entirely on the open file and its training data. With them, it knows your tech stack, naming conventions, error handling patterns, and preferred libraries before you type a single character.

The .github/copilot-instructions.md file

Copilot reads custom instructions from a single file:

.github/copilot-instructions.md

This file lives in your repository root, inside the .github directory — the same place you put issue templates and workflow files. It's committed to git and shared with your team.

Basic structure

# Project Instructions for Copilot

## Tech stack
- Framework: Next.js 15 (App Router)
- Language: TypeScript 5.7 (strict mode)
- Database: Drizzle ORM + PostgreSQL
- Styling: Tailwind CSS v4
- Testing: Vitest

## Conventions
- Use named exports for all React components
- Use kebab-case for file names
- API routes return { data: T } on success, { error: string } on failure
- Always validate request bodies with Zod schemas

Copilot includes these instructions in its context when generating suggestions, chat responses, and inline completions.

Where instructions apply

Repository-level instructions take precedence over organization and personal instructions when they conflict.

Writing effective Copilot instructions

Start with your tech stack

The most impactful thing you can do is declare your stack explicitly:

## Tech stack

- Runtime: Node.js 22
- Framework: Next.js 15 (App Router only — never Pages Router)
- Language: TypeScript 5.7 with strict mode enabled
- Package manager: pnpm (not npm or yarn)
- ORM: Drizzle with PostgreSQL
- CSS: Tailwind CSS v4 (no CSS modules, no styled-components)
- Testing: Vitest + React Testing Library

Without this, Copilot might suggest Pages Router patterns, npm commands, or CSS modules. With it, every suggestion aligns with your actual stack.

Include code examples

Copilot mirrors patterns it sees. Show it exactly what you want:

## API route pattern

Every API route follows this structure:

export async function POST(request: Request) {
  try {
    const body = await request.json();
    const validated = createUserSchema.parse(body);
    const result = await db.insert(users).values(validated);
    return Response.json({ data: result });
  } catch (error) {
    if (error instanceof ZodError) {
      return Response.json({ error: error.message }, { status: 400 });
    }
    return Response.json({ error: "Internal error" }, { status: 500 });
  }
}

Set explicit boundaries

Tell Copilot what NOT to do:

## Do NOT
- Do not use default exports (except page.tsx and layout.tsx)
- Do not use \`any\` as a TypeScript type
- Do not use console.log — use the logger utility from src/lib/logger
- Do not import from barrel files — import directly from the module
- Do not use CSS-in-JS or inline styles — Tailwind only
- Do not use the legacy Pages Router

Boundaries prevent Copilot from falling back to generic patterns that conflict with your project conventions.

Limitations of Copilot's instruction system

Copilot's custom instructions are powerful but have constraints compared to other tools:

Key limitations:

1. Single file only: Everything goes in one copilot-instructions.md. No way to split by topic.
2. No file targeting: You can't scope instructions to specific file patterns (e.g., only apply React rules when editing .tsx files).
3. No conditional loading: All instructions are always active — no way to toggle rules based on context.
4. Size constraints: Very long instruction files may not be fully included in Copilot's context window.

These limitations make it harder to manage complex rule sets. For large projects, consider supplementing Copilot with a shared skills registry that manages content across tools.

Advanced: workspace and organization instructions

Organization-level instructions

GitHub organization admins can set instructions that apply across all repositories:

1. Go to Organization Settings → Copilot → Custom Instructions
2. Add instructions in the text field
3. These apply to every member using Copilot in any org repo

This is useful for company-wide standards:

## Company standards
- All code must include error handling for network requests
- Use ISO 8601 date formats throughout
- Logging must use structured JSON format
- Never expose internal error details to end users
- All new API endpoints require OpenAPI documentation

Personal instructions

Individual developers can set personal instructions in their GitHub settings:

1. Go to Settings → Copilot → Custom Instructions
2. Add your personal preferences

These are great for editor-agnostic personal conventions:

## Personal preferences
- I prefer functional components over class components
- Use early returns to reduce nesting
- Add TypeScript types explicitly for function parameters
- Prefer const over let where possible

Precedence order

When instructions conflict, Copilot applies them in this order (highest priority first):

1. Repository .github/copilot-instructions.md
2. Organization-level instructions
3. Personal instructions

Sharing Copilot instructions with localskills.sh

The single-file limitation makes Copilot instructions harder to manage across multiple repositories. If your team has 10 repos, you need 10 copies of the same instructions file.

localskills.sh solves this with a central registry:

# Install the CLI
npm install -g @localskills/cli
localskills login

# Publish your Copilot instructions
localskills publish .github/copilot-instructions.md --team my-team --name api-conventions

# Install in any project
localskills install my-team/api-conventions --target copilot

The CLI places the content into .github/copilot-instructions.md in the correct format. When you update the skill, every project gets the latest version with localskills pull.

Making instructions work in Cursor and Claude Code

The biggest advantage of publishing to localskills.sh is cross-tool compatibility. The same skill installs into every AI coding tool:

# Install into Copilot, Cursor, and Claude Code at once
localskills install my-team/api-conventions --target copilot cursor claude

The CLI handles format differences automatically:

• Copilot: .github/copilot-instructions.md
• Cursor: .cursor/rules/api-conventions.mdc (with MDC frontmatter)
• Claude Code: .claude/skills/api-conventions.md
• Windsurf: .windsurf/rules/api-conventions.md

No manual file conversion. One source of truth, every tool updated.

Read the full tool comparison or learn about writing effective AI coding rules.

---

Share your Copilot instructions across tools and teams. Get started with localskills.sh.

npm install -g @localskills/cli
localskills login
localskills publish