copilot-plugin

Copilot CLI Plugin Developer

Build and maintain GitHub Copilot CLI plugins. This skill has authoritative specs, templates, and validation for all Copilot plugin components.

CRITICAL: Copilot CLI != Claude Code

These are different ecosystems with different conventions. Read the relevant spec in reference/ before creating or modifying any component.

Aspect	Copilot CLI Plugin	Claude Code
Skill frontmatter	Only name, description, license	Also allowed-tools, metadata, etc.
Instructions file	AGENTS.md (primary)	CLAUDE.md
Agent file extension	.agent.md	.md in agents/
Agent naming	Lowercase kebab-case required	More flexible
Skill naming	Must match directory name	Convention only
Tool restrictions	Via tools in agent frontmatter	Via allowed-tools in skill
Installation	copilot plugin install ./path	Plugin marketplace

Do NOT use Claude Code patterns when building Copilot plugin components.

Workflow

Step 1: Understand what's needed

Before creating anything, understand the user's intent:

1. What problem? — What should Copilot do differently?
2. When should it apply? — Always? Specific files? On demand?
3. What type? — Use the decision guide below

What do you need?
│
├─ Broad guidance for ALL interactions → Custom Instructions (.github/copilot-instructions.md)
├─ Guidance for SPECIFIC file types    → Path-specific (.github/instructions/*.instructions.md)
├─ A specialized AI persona            → Custom Agent (.github/agents/*.agent.md)
├─ A reusable prompt template          → Prompt File (.github/prompts/*.prompt.md)
├─ Complex task-specific guidance      → Skill (.github/skills/{name}/SKILL.md)
└─ Primary identity + routing          → AGENTS.md (root)

For detailed comparison, read reference/comparison-matrix.md.

Step 2: Read the spec

Before writing any file, read the relevant spec:

Task	Read first
Creating/modifying a skill	skills-spec.md
Creating/modifying an agent	agents-spec.md
Changing plugin.json or structure	plugin-spec.md
Adding/changing MCP servers	mcp-spec.md
Adding hooks	hooks-spec.md
Changing AGENTS.md or instructions	instructions-spec.md

Step 3: Create the component

Use the appropriate template from templates/:

Type	Template	Output Location
Custom Instructions	templates/custom-instructions.md	.github/copilot-instructions.md
Path-specific	templates/path-instructions.md	.github/instructions/{name}.instructions.md
Custom Agent	templates/agent.md	.github/agents/{name}.agent.md
Prompt File	templates/prompt.md	.github/prompts/{name}.prompt.md
Skill	templates/skill.md	.github/skills/{name}/SKILL.md

Step 4: Validate

Run the validation script to catch format issues:

python scripts/validate.py <path-to-file-or-directory>

Step 5: Test and iterate

For skills, create trigger evals to test description accuracy:

1. Create tests/evals/triggers/{name}.json with 8+ positive and 8+ negative queries
2. Queries must be realistic, specific, and varied
3. Negative queries should be near-misses, not obviously irrelevant

For the eval format, read reference/eval-schemas.md.

Writing Effective Customizations

Read reference/writing-guide.md for detailed guidance. Key principles:

• Explain the why — LLMs respond better to reasoning than rigid rules. Instead of "ALWAYS use named exports", explain why named exports matter.
• Be specific — "Use React Query for server state" beats "use good state management"
• Show, don't tell — One good example communicates what paragraphs cannot
• Keep it lean — Every instruction has a context cost. Cut what doesn't add value.
• Constrain scope — An agent that does everything well does nothing well
• Generalize, don't overfit — Address patterns, not individual cases

Quick Reference: Plugin Structure

my-plugin/
├── plugin.json                    # Manifest (name, version, paths)
├── AGENTS.md                      # Primary instructions + routing
├── .mcp.json                      # MCP server config
├── hooks.json                     # Hook definitions
├── agents/
│   └── {name}.agent.md            # Custom agents (lowercase kebab-case)
├── skills/
│   └── {name}/
│       ├── SKILL.md               # Skill definition
│       ├── scripts/               # Helper scripts
│       ├── reference/             # Docs loaded on demand
│       └── templates/             # Output templates
└── extensions/
    └── {name}/
        └── server.py              # MCP server implementation

Adding Skills

1. Read skills-spec.md
2. Create skills/{name}/SKILL.md with only name, description, license in frontmatter
3. Directory name must match the name field exactly
4. Description explains WHAT and WHEN (this is the auto-trigger)
5. Validate: python scripts/validate.py skills/{name}/
6. Add to AGENTS.md routing table
7. Create trigger evals (8+ positive, 8+ negative queries)

Adding Agents

1. Read agents-spec.md
2. Create agents/{name}.agent.md with name, description, optional tools
3. Lowercase kebab-case names, filename must match
4. Define clear boundaries (what it does AND does not do)
5. Validate: python scripts/validate.py agents/
6. Add routing entries in AGENTS.md

Reference Documentation

All specs are in reference/:

• plugin-spec.md — plugin.json manifest and structure
• skills-spec.md — SKILL.md format, naming, activation
• agents-spec.md — agent files, tool access, invocation
• instructions-spec.md — AGENTS.md, custom instructions
• mcp-spec.md — MCP server configuration
• hooks-spec.md — hook types and configuration
• eval-schemas.md — JSON schemas for trigger evals, grading, benchmarks
• comparison-matrix.md — When to use which customization type
• writing-guide.md — How to write effective instructions