How to Migrate from Copilot Instructions to Agent Skills

What are Copilot custom instructions?

GitHub Copilot supports custom instructions through a .github/copilot-instructions.md file in your repository. This file tells Copilot about your coding conventions, preferred patterns, tech stack, and things to avoid.

A typical copilot-instructions.md might look like this:

## General

- Use TypeScript for all new files
- Prefer functional programming patterns
- Always handle errors explicitly — no silent catches

## React

- Use functional components with hooks, never class components
- Use Tailwind CSS for styling
- Prefer server components in Next.js when possible

## Testing

- Write tests with Vitest and React Testing Library
- Follow the Arrange-Act-Assert pattern
- Mock external services, not internal modules

## API Routes

- Validate all input with Zod schemas
- Return consistent error response format: { error: string, code: string }
- Use proper HTTP status codes

This works well inside VS Code with Copilot. But those instructions don't transfer to Claude Code, Cursor, Windsurf, or other AI tools. They're Copilot-specific.

What are Agent Skills?

Agent Skills are portable agent definitions that work across 40+ AI tools. Each agent is a Markdown file with YAML frontmatter for metadata and a Markdown body for instructions.

The key differences from copilot-instructions.md:

• Portable. Agent skills work in Copilot, Claude Code, Cursor, Windsurf, and dozens of other tools.
• Versioned. Each agent has a semantic version number so you can track changes.
• Focused. Instead of one file with all your rules, each agent handles one responsibility.
• Shareable. Publish agents to registries like Agent Shelf and share them across teams and projects.
• Discoverable. Other developers can find and install your agents.

Why migrate?

Your team uses different AI tools. Copilot instructions only work with Copilot. Agent skills give everyone the same instructions regardless of their tool.

Your instructions are growing. A long copilot-instructions.md file mixes concerns — coding standards, testing conventions, API design rules. Splitting into focused agents makes each one easier to maintain.

You want to reuse across projects. Your React patterns and testing conventions apply to multiple repos. As agent skills, you install them once and reuse them everywhere.

Copilot already supports Agent Skills. Since VS Code supports the Agent Skills spec, your migrated agents will work in Copilot too — plus every other compatible tool.

Step-by-step migration

Step 1: Audit your instructions file

Read through your copilot-instructions.md and group the instructions by topic. Most files contain a mix of:

• Project context — tech stack, architecture, frameworks
• Coding standards — naming conventions, patterns, anti-patterns
• Task-specific workflows — how to review code, write tests, generate docs
• Tool-specific rules — things about how to use specific libraries

Mark each group. Project context stays as general configuration. Task-specific workflows become individual agents.

Step 2: Separate project context from agent expertise

Project context is information that applies to every interaction: "This project uses Next.js 16, React 19, TypeScript, and Tailwind CSS." This belongs in a project-level file, not in an agent. Keep it in copilot-instructions.md (for Copilot), or move it to AGENTS.md in your project root (portable across tools).

Agent expertise is specialized knowledge for a specific task: "When reviewing code, check for security vulnerabilities using the OWASP Top 10 checklist." This becomes an agent definition.

Here's how to split a typical instructions file:

Stays in project context (AGENTS.md):

# Project Context

This is a Next.js 16 application with React 19 and TypeScript.

## Stack
- Styling: Tailwind CSS v4
- Database: PostgreSQL with Prisma ORM
- Testing: Vitest + React Testing Library
- Auth: NextAuth v5

## Conventions
- Use functional components, never class components
- Named exports only, no default exports
- Prefer server components when possible

Becomes an agent (test-writer.md):

---
id: "test-writer"
name: "Test Writer"
description: "Writes tests that match this project's patterns using Vitest and React Testing Library."
version: "1.0.0"
category: "coding"
tags: ["testing", "vitest", "react-testing-library"]
---

# Test Writer

You write thorough tests for this project using Vitest and React Testing Library.

## Workflow

1. Read existing test files to understand patterns and conventions
2. Understand the code to be tested — read the implementation
3. Write tests following the Arrange-Act-Assert pattern

## Rules

- Use `describe` blocks to group related tests
- Use `it` (not `test`) for test names
- Mock external services with `vi.mock`, not internal modules
- Use factories from `tests/factories/` for test data
- Assert behavior, not implementation details

Step 3: Create the agent files

For each task-specific group, create a Markdown file with YAML frontmatter:

1. Create the .agents/agents/ directory in your project root
2. Create one .md file per agent
3. Add frontmatter with id, name, description, version, and category
4. Move the relevant instructions into the Markdown body

Directory structure after migration:

your-project/
├── .github/
│   └── copilot-instructions.md    ← keep for Copilot-specific context (optional)
├── AGENTS.md                       ← portable project context
├── .agents/
│   └── agents/
│       ├── code-reviewer.md        ← code review process
│       ├── test-writer.md          ← testing workflow
│       └── api-designer.md         ← API design conventions

Step 4: Enhance the agents

Your original instructions were written as flat rules. Agent definitions support richer structure. Take this opportunity to add:

Persona. Instead of "Check for security issues," write: "You are a senior security engineer performing a thorough code review. You think like an attacker."

Workflow. Turn bullet points into numbered steps that define a process: "1. Read the full diff. 2. Identify the purpose of the change. 3. Check each file for issues. 4. Produce a structured report."

Output format. Define what the output should look like: severity levels, structured findings, specific sections.

Examples. Show what good output looks like so the AI understands the expected quality level.

Step 5: Test both systems

During the transition, you can run both systems side by side:

• Keep copilot-instructions.md for project context (Copilot reads it automatically)
• Place agent definitions in .agents/agents/ (all compatible tools discover them)

Copilot will use both: the custom instructions for general context and agent definitions for specialized tasks. Other tools will pick up the agents from .agents/.

Step 6: Share and publish (optional)

If your agents aren't project-specific — they encode general expertise like code review methodology or test writing best practices — consider publishing them to Agent Shelf. Other developers can then discover and use them.

Remove any project-specific details (file paths, library versions, internal conventions) before publishing. Keep the agent focused on transferable expertise.

Migration reference

Here's how Copilot instruction patterns map to agent definition features:

| Copilot instructions | Agent definitions | |---------------------|-------------------| | "Always use TypeScript" | Project context in AGENTS.md | | "When reviewing code, check for..." | Dedicated code review agent with structured workflow | | "Write tests using Vitest" | Dedicated test writer agent with format and rules | | "API routes should validate with Zod" | Dedicated API designer agent or project context | | "Follow the Arrange-Act-Assert pattern" | Rule inside the test writer agent | | "Return errors in { error, code } format" | Rule inside the API designer agent |

General rule: Static facts about the project → project context. Dynamic processes and workflows → agent definitions.

What about the .github/copilot-instructions.md file?

You don't have to delete it. Copilot reads both custom instructions and agent definitions. During migration, keep the custom instructions file as a fallback. Once your agents are working well, you can gradually reduce the instructions file to project context only, or remove it entirely if AGENTS.md covers everything.

Learn more

• The Agent Skills Specification, Explained — how the standard works
• Best Agents for GitHub Copilot — what agents work well with Copilot
• Migrating from .cursorrules — similar guide for Cursor users
• Migrating from Custom GPTs — guide for ChatGPT users
• Agent Definition Templates — ready-to-use starter templates