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 the advanced file types — *.instructions.md, *.prompt.md, *.agent.md, and SKILL.md — that give teams scoped, reusable, and agent-discoverable customization. For the basics of .github/copilot-instructions.md, AGENTS.md, and CLAUDE.md, see Prompt Engineering → Workspace Instruction Files.

note

This page focuses on GitHub Copilot. For the Claude Code equivalents (CLAUDE.md, .claude/skills/, .claude/agents/, hooks), see Claude Code Customization.

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
AGENTS.mdRepo root (and subfolders)Global / per folderAlways includedTool-agnostic project instructions
*.instructions.md.github/instructions/ConditionalWhen matching files in contextFile-type-specific rules
*.prompt.md.github/prompts/On-demandUser-invoked via / commandReusable prompt templates
*.agent.md.github/agents/Session-wide or subagentUser selects in agent picker, or another agent delegatesCustom agent personas with constrained tools
SKILL.md.github/skills/<skill-name>/Agent-discoverableAgent loads when the description matches the taskPackaged workflows with supporting files

When to use which: Use global instructions (or AGENTS.md) for universal conventions. Use *.instructions.md for file-type-specific guidance that should activate automatically. Use *.prompt.md for simple templates the team invokes manually. Use *.agent.md for personas with their own tools and constraints. Use SKILL.md for multi-step capabilities the agent picks up on its own. For integrations with external systems, use MCP Servers.

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:

---
description: "Short description of what these instructions cover"
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. The reverse also applies: a broad pattern like "**" injects the file into every request and costs tokens every turn. Long, task-specific procedures belong in a skill instead.

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)
caution

VS Code is moving prompt files toward agent skills. Prompt files still work with the local agent, but newer agent session types don't load them, and VS Code offers a migration that converts prompts to skills. For new workflows, prefer a skill; check the VS Code prompt files docs for the current status.

Format​

Prompt files support optional YAML frontmatter:

---
agent: "agent"
tools: ["codebase", "githubRepo", "fetch"]
description: "Short description shown in the / menu"
---
  • agent: which agent runs the prompt — ask, agent, or the name of a custom agent. This field was previously called mode; rename it in older files.
  • tools: which tools the agent can use
  • 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
---
agent: "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
---
agent: "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
---
agent: "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."

Custom Agents (*.agent.md)​

Custom agents replace the older chat modes (.chatmode.md). Existing .chatmode.md files still load, and VS Code offers a Quick Fix that moves them to .github/agents/ with the new extension.

How They Work​

  • Location: .github/agents/ directory for the team (personal agents live in your VS Code user profile)
  • Appear in the agent picker in Copilot Chat, next to the built-in agents
  • Can also run as subagents: an agent with the agent tool can delegate a task to another custom agent, which runs in its own context window and returns a result
  • Each agent defines its own persona, tool set, and optionally a model

Format​

---
name: "Researcher"
description: "Gathers information from the web and existing docs"
tools: ["read", "search", "web"]
model: "<model name>"            # optional
user-invocable: false            # hide from the picker; still usable as a subagent
disable-model-invocation: false  # true = never used as a subagent
agents: ["Writer"]               # which agents this one may delegate to
---

Only description is needed in practice — name falls back to the file name. user-invocable and disable-model-invocation replace the deprecated infer property. Check the VS Code custom agents docs for the full field list, including handoffs for guided multi-step workflows.

The body describes how the agent should behave.

Example — Based on This Repository​

This repository's documentation pipeline is a set of custom agents in .github/agents/: a user-facing Documentation Team orchestrator that delegates to Researcher, Architect, and Writer subagents. A trimmed version of the Researcher:

.github/agents/researcher.agent.md
---
name: Researcher
description: Gathers information from the web and existing docs for documentation topics
user-invocable: false
tools: ["read", "search", "web", "todo"]
---

# Researcher Agent

You gather accurate, up-to-date information from the web and the existing docs.
You do NOT write docs yourself — you compile research that the Architect and
Writer agents will use.

1. Check existing docs in `web-hub-website/docs/` first.
2. Search authoritative sources — prefer primary documentation over blog posts.
3. Return a research brief: existing coverage, key findings with source URLs,
   recommended structure, and a numbered source list.

See Multi-Agent Orchestration for how the pieces fit together.

Custom Agents vs Prompt Files​

note

Custom agents define how the agent behaves for an entire session — persona, available tools, and constraints. Prompt files define a specific task to execute. A prompt file can target a custom agent through its agent field.

Agent Skills (SKILL.md)​

How They Work​

  • Location: .github/skills/<skill-name>/SKILL.md (Copilot also reads .claude/skills/, so one skill can serve both tools)
  • Agent Skills is an open standard supported by Copilot (VS Code, CLI, and coding agent), Claude Code, and other agents
  • Only the name and description are loaded up front. The agent reads the full SKILL.md — and any supporting files in the folder — only when the description matches the task. This keeps skills cheap until they're needed
  • A skill folder can include scripts, templates, and reference files alongside SKILL.md

Format​

SKILL.md must start with YAML frontmatter. Without name and description, the agent never discovers the skill:

---
name: deploy-preview
description: Creates a preview deployment for a pull request. Use when the user asks for a preview, staging deployment, or live URL for review.
---

Write the description for the agent, not for humans: say what the skill does and when to use it. It is the only thing the agent sees when deciding whether to load the skill.

Example​

.github/skills/deploy-preview/SKILL.md
---
name: deploy-preview
description: Creates a preview deployment for a pull request. Use when the user asks for a preview, staging deployment, or live URL for review.
---

# Deploy Preview

## 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 available via the project's pinned dev dependency
- Build must pass before deploying
- Terminal tool access required

Skills vs Prompt Files vs Instructions​

tip

Instructions are always (or glob-) loaded; prompt files are human-invoked; skills are loaded on demand when relevant. If a procedure is long and only matters for some tasks — generating images, deploying, running a release — make it a skill rather than an instruction file, so it doesn't cost tokens on every request.

caution

Skills from third-party collections run with your permissions and may include scripts. Read a skill's files before adding it to your repo — see Agent Security.

Copilot Extensions (Deprecated)​

GitHub App-based Copilot Extensions (custom @extension-name chat participants) were shut down on November 10, 2025. GitHub replaced them with MCP servers, which work in Copilot and in other MCP-compatible tools such as Claude Code and Cursor. If you find an old guide recommending a Copilot Extension, look for the vendor's MCP server instead.

Regular VS Code extensions and the built-in chat participants (@workspace, @terminal, @vscode) were not affected.

How They Work Together​

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

AGENTS.md                                  # Global, tool-agnostic: always active
.github/
├── copilot-instructions.md                # Global, Copilot-specific: 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/
│   ├── review-security.prompt.md          # User invokes: security check
│   └── create-migration.prompt.md         # User invokes: DB migration
├── agents/
│   ├── orchestrator.agent.md              # User picks: coordinates subagents
│   └── researcher.agent.md                # Subagent only
└── skills/
    └── deploy-preview/
        └── SKILL.md                       # Agent loads when relevant

The mental model:

  • Instructions shape how Copilot writes code (passive context, layered)
  • Prompts define what workflows to run (active templates, human-triggered)
  • Custom agents define how the agent behaves for a session or a delegated task (persona + tool constraints)
  • Skills define what the agent can do on its own (on-demand capabilities)
  • MCP servers add integrations with external systems
tip

Start with AGENTS.md or .github/copilot-instructions.md and a few scoped instruction files. Add skills as you identify workflows the team repeats. Custom agents and subagent pipelines are the most advanced — add them once you're comfortable with agentic workflows.

Configuration​

SettingPurposeDefault
github.copilot.chat.codeGeneration.useInstructionFilesUse .github/copilot-instructions.md and *.instructions.mdtrue
chat.useAgentsMdFileUse AGENTS.md filestrue

Setting names and defaults change often. If a file type isn't being picked up, check the VS Code customization docs for the current setting.

Resources​