Skip to main content

Copilot Customization Files

GitHub Copilot supports several file-based customization mechanisms beyond the global .github/copilot-instructions.md. This page covers advanced file types — *.instructions.md, *.prompt.md, SKILL.md, and *.chatmode.md — plus Copilot Extensions that give teams scoped, reusable, and agent-discoverable customization. For the basics of .github/copilot-instructions.md, .cursorrules, and CLAUDE.md, see Prompt Engineering → Workspace Instruction Files.

note

This page focuses on GitHub Copilot-specific files. Cursor and Claude Code have their own equivalents (linked in the Prompt Engineering page).

tip

Looking for a tool-agnostic instruction file that works across multiple AI agents (not just Copilot)? See AGENTS.md in the Prompt Engineering page.

Overview — Which File Does What?​

FileLocationScopeActivationPrimary Use
.github/copilot-instructions.md.github/GlobalAlways includedProject-wide conventions
*.instructions.md.github/instructions/ConditionalWhen matching files in contextFile-type-specific rules
*.prompt.md.github/prompts/On-demandUser-invoked via / commandReusable prompt templates
SKILL.md.github/skills/<skill-name>/Agent-discoverableAgent decides autonomouslyAutomation recipes
.chatmode.md.github/chatmodes/Session-wideUser selects in mode pickerCustom agent personas
ExtensionsGitHub MarketplacePer-installUser invokes via @nameExternal integrations

When to use which: Use global instructions for universal conventions. Use *.instructions.md for file-type-specific guidance that should activate automatically. Use *.prompt.md for reusable prompt templates the team invokes manually. Use SKILL.md for capabilities the agent discovers and uses on its own. Use .chatmode.md for custom agent personas with constrained tools. Use Extensions for integrations with external systems.

Scoped Instructions (*.instructions.md)​

How They Work​

  • Location: .github/instructions/ directory
  • Each file has YAML frontmatter with an applyTo glob pattern
  • Activates only when files matching the glob are part of the conversation context
  • Layers on top of global .github/copilot-instructions.md — they don't replace it, they add to it
  • Multiple instruction files can activate simultaneously
  • VS Code setting: github.copilot.chat.codeGeneration.useInstructionFiles (enabled by default)

Format​

The file starts with frontmatter specifying which files trigger it:

---
applyTo: "glob-pattern"
---

The body is plain Markdown with instructions for Copilot. You can use brace expansion for multiple patterns (e.g., "{**/*.ts,**/*.tsx}" to match both .ts and .tsx files).

Example — From This Repository​

This is the actual instruction file used in this repository:

.github/instructions/npm-supply-chain.instructions.md
---
applyTo: "{**/.npmrc,**/package.json,**/package-lock.json}"
---

# npm Supply-Chain Security

- Ensure `.npmrc` includes `min-release-age=7` to quarantine newly published package versions for 7 days before allowing resolution.
- Pin all npm dependencies to exact versions. Do not use version ranges (`^`, `~`, `>=`), mutable tags, or `latest`.
- Always generate, update, and commit `package-lock.json` alongside dependency changes.
- Use `npm ci` in CI/CD pipelines instead of `npm install` to enforce the lockfile.
- Do not add new dependencies without noting them in the PR description.

This file activates whenever Copilot is working with package.json, package-lock.json, or .npmrc files — for example, when the agent adds a dependency or when you ask about package configuration. The supply-chain security rules are injected as context so Copilot follows them without being reminded.

More Examples​

React/TypeScript component conventions:

.github/instructions/react-components.instructions.md
---
applyTo: "**/*.tsx"
---

# React Component Conventions

- Use named exports (no default exports)
- Props interfaces go in the same file, named `<ComponentName>Props`
- Use functional components with arrow functions
- Co-locate tests in `<ComponentName>.test.tsx`
- Use React Query for data fetching, never useEffect for async data

Test file conventions:

.github/instructions/testing.instructions.md
---
applyTo: "{**/*.test.ts,**/*.test.tsx,**/*.spec.ts}"
---

# Testing Conventions

- Use Vitest (`describe`, `it`, `expect`)
- Prefer `userEvent` over `fireEvent` for React Testing Library
- Name test files `<module>.test.ts` (unit) or `<module>.spec.ts` (integration)
- Use `vi.mock()` for module mocks, prefer dependency injection where possible
- Each `describe` block should test one public function or component behavior

Tips​

tip

Keep instruction files focused — one concern per file. They activate independently, so it's better to have react-components.instructions.md and testing.instructions.md separately rather than one giant file.

caution

Glob patterns are matched against files in the chat context, not the entire repository. If no matching file is referenced in the conversation, the instructions won't activate — even if matching files exist in the repo.

Reusable Prompts (*.prompt.md)​

How They Work​

  • Location: .github/prompts/ directory (and subdirectories)
  • Invoked by the user via / slash command picker in VS Code Copilot Chat
  • NOT auto-applied — explicitly user-triggered (this is the key difference from instructions)
  • Requires VS Code setting: "chat.promptFiles": true

Format​

Prompt files support optional YAML frontmatter:

---
mode: "agent"
tools: ["codebase", "githubRepo", "fetch"]
description: "Short description shown in the / menu"
---
  • mode: determines how Copilot processes the prompt. agent = full agent loop with tools; ask = conversational answer; edit = apply changes to specific files.
  • tools: which tools the agent can use (only relevant in agent mode)
  • description: what users see when browsing the / command menu

The body is Markdown with the actual prompt. Use #file:path/to/file to reference workspace files as additional context.

Examples​

Component scaffolding prompt:

.github/prompts/create-component.prompt.md
---
mode: "agent"
tools: ["codebase"]
description: "Scaffold a new React component with tests and types"
---

Create a new React component based on the user's description.

Follow the conventions in #file:.github/instructions/react-components.instructions.md

Use this component as a structural reference: #file:src/components/Button/Button.tsx

## Requirements
- Named export
- Props interface with JSDoc comments
- Co-located unit test file using Vitest + React Testing Library
- Co-located Storybook story (if the project uses Storybook)

Security review prompt:

.github/prompts/review-security.prompt.md
---
mode: "ask"
description: "Review selected code for common security vulnerabilities"
---

Review the code in context for security vulnerabilities. Check for:

1. SQL injection / NoSQL injection
2. XSS (unsanitized user input in HTML)
3. Missing input validation
4. Hardcoded secrets or credentials
5. Insecure deserialization
6. Path traversal vulnerabilities
7. Missing authentication/authorization checks

For each issue found, explain the risk and suggest a specific fix.
If no issues are found, confirm what you checked.

Migration generation prompt:

.github/prompts/create-migration.prompt.md
---
mode: "agent"
tools: ["codebase", "terminal"]
description: "Generate a database migration from schema changes"
---

Look at the current Prisma schema in #file:prisma/schema.prisma and generate a migration for the latest changes.

Steps:
1. Identify what changed since the last migration
2. Run `npx prisma migrate dev --name <descriptive-name> --create-only`
3. Review the generated SQL
4. Check for any destructive operations and flag them with a warning

When to Use Prompt Files vs Instructions​

note

Instructions are passive context — they shape how Copilot writes code whenever matching files are relevant. Prompt files are active templates — they define a specific workflow you invoke explicitly. Use instructions for "always do X when touching these files" and prompts for "run this specific workflow on demand."

Agent Skills (SKILL.md)​

How They Work​

  • Location: typically .github/skills/<skill-name>/SKILL.md
  • Discovered by Copilot agent mode when planning how to approach a task
  • NOT user-invoked — the agent autonomously decides to use a skill when it fits the task
  • Community convention (from github/awesome-copilot) — still evolving, not a formal VS Code extension API

Structure​

A SKILL.md typically includes:

  • Description: what the skill does
  • When to use: trigger conditions / when it's appropriate
  • Steps: step-by-step instructions the agent follows
  • Requirements: tools, files, or setup needed

Example​

.github/skills/deploy-preview/SKILL.md
# Deploy Preview

## Description
Creates a preview deployment of the application for a pull request.

## When to Use
- User asks to deploy a preview
- User asks to test changes in a staging environment
- PR is ready for review and needs a live preview URL

## Steps
1. Check that the current branch has no uncommitted changes
2. Run `npm run build` to verify the build succeeds
3. Run `npx vercel --prebuilt` to deploy to the preview environment
4. Return the preview URL to the user

## Requirements
- Vercel CLI must be installed (`npx vercel`)
- Build must pass before deploying
- Terminal tool access required

Skills vs Prompt Files​

tip

Prompt files are human-invoked; skills are agent-invoked. If you want a team member to explicitly trigger a workflow, make it a prompt file. If you want the agent to autonomously decide to run something when it's appropriate, make it a skill. In practice, skills are more useful for complex agent sessions where the agent needs to chain multiple capabilities.

Custom Chat Modes (.chatmode.md)​

How They Work​

  • Location: .github/chatmodes/ directory (or .vscode/chatmodes/ for personal modes)
  • Define custom interaction modes beyond the built-in Ask, Edit, and Agent modes
  • Activated via the mode picker dropdown in Copilot Chat (where you normally select Ask/Edit/Agent)
  • Useful for defining task-specific agent behaviors with constrained tool access

Format​

---
name: "Mode Name"
description: "What this mode does"
tools: ["codebase", "terminal", "fetch"]
---

The body describes how the agent should behave when this mode is active.

Example​

.github/chatmodes/docs-writer.chatmode.md
---
name: "Documentation Writer"
description: "Write and update project documentation"
tools: ["codebase", "fetch"]
---

You are a documentation writer. When given a topic:

1. Search the codebase for relevant source code and existing docs
2. Write clear, concise Markdown documentation
3. Follow the project's existing doc style and structure
4. Include code examples from the actual codebase where relevant

Do not modify source code files. Only create or edit Markdown files in the docs/ directory.

Chat Modes vs Prompt Files​

note

Chat modes define how the agent behaves for an entire session — they set the persona, available tools, and constraints. Prompt files define a specific task to execute. You can use a prompt file within a custom chat mode: select your mode, then invoke /your-prompt.

Copilot Extensions​

Copilot Extensions are GitHub-based plugins that add custom chat participants — invoked via @extension-name in Copilot Chat. They extend Copilot's capabilities beyond what file-based customization can achieve.

Built-in Participants​

These are always available in VS Code Copilot Chat:

ParticipantWhat it does
@workspaceSemantic search across workspace files
@terminalInclude terminal context (output, errors)
@vscodeVS Code settings, commands, and UI questions
@githubGitHub-specific operations (issues, PRs, repos)

Third-Party Extensions​

Additional participants can be installed from the GitHub Marketplace. These are GitHub Apps that register as Copilot chat participants — for example, an extension for your cloud provider, monitoring tool, or design system.

When to Use Extensions vs Other Customization​

tip

Extensions are for integrations with external systems — when Copilot needs to call an API, query a service, or access data that isn't in your workspace. For shaping how Copilot writes code within your project, stick with instruction files and prompt files. For giving agent mode access to external tools, use MCP Servers instead.

How They Work Together​

A well-configured project uses these file types in concert:

.github/
├── copilot-instructions.md               # Global: always active
├── instructions/
│   ├── react-components.instructions.md  # When editing .tsx files
│   ├── testing.instructions.md           # When editing test files
│   └── npm-supply-chain.instructions.md  # When editing package files
├── prompts/
│   ├── create-component.prompt.md   # User invokes: scaffold component
│   ├── review-security.prompt.md    # User invokes: security check
│   └── create-migration.prompt.md   # User invokes: DB migration
├── chatmodes/
│   └── docs-writer.chatmode.md      # Custom interaction mode
└── skills/
    └── deploy-preview/
        └── SKILL.md                 # Agent invokes: deploy preview

The mental model:

  • Instructions shape how Copilot writes code (passive context, layered)
  • Prompts define what workflows to run (active templates, human-triggered)
  • Chat Modes define how the agent behaves for an entire session (persona + tool constraints)
  • Skills define what the agent can do on its own (autonomous capabilities)
  • Extensions add integrations with external systems (via @participant chat commands)
tip

Start with global .github/copilot-instructions.md and a few scoped instruction files. Add prompt files as you identify workflows the team repeats. Skills are the most advanced — add them once you're comfortable with agentic workflows.

Configuration​

SettingPurposeDefault
github.copilot.chat.codeGeneration.useInstructionFilesEnable *.instructions.md filestrue
chat.promptFilesEnable *.prompt.md filesfalse (must enable)
chat.chatModesEnable custom .chatmode.md filestrue
caution

Prompt files require explicitly setting "chat.promptFiles": true in your VS Code settings (or workspace .vscode/settings.json). Without this, .prompt.md files in .github/prompts/ won't appear in the / menu.

Resources​