GitHub Copilot Customization Skill

Create and manage the full spectrum of GitHub Copilot customizations for VS Code (1.109+),
GitHub Copilot CLI, and Copilot coding agent.

Decision Tree — Which Primitive to Use

Before creating anything, determine the right customization type:

User request
│
├─ "Set up Copilot for this project" or "/init"
│   → Generate .github/copilot-instructions.md  (always-on instructions)
│   → See: references/instructions.md
│
├─ "Rules for specific file types" (e.g., "all .tsx files should...")
│   → Create .instructions.md with applyTo glob pattern
│   → See: references/instructions.md
│
├─ "Reusable task" (e.g., "scaffold a component", "generate tests")
│   → Create .prompt.md in .github/prompts/
│   → See: references/prompt-files.md
│
├─ "Specialized persona" (e.g., "code reviewer", "security auditor", "planner")
│   → Create .agent.md in .github/agents/
│   → See: references/custom-agents.md
│
├─ "Teach Copilot a complex capability with scripts/resources"
│   → Create skill folder in .github/skills/<name>/SKILL.md
│   → See: references/agent-skills.md
│
├─ "Run checks before/after agent actions" (lint, security, logging)
│   → Create hooks.json in .github/hooks/
│   → See: references/hooks.md
│
├─ "Connect external services" (databases, APIs, issue trackers)
│   → Configure MCP servers in .vscode/mcp.json or settings
│   → See: references/mcp-servers.md
│
└─ "Full project setup" or "enterprise customization"
    → Combine multiple primitives (see examples/enterprise-setup.md)

Quick Reference: File Locations

Quick Reference: Frontmatter Fields

Instructions (.instructions.md)

---
applyTo: '**/*.ts'        # Glob pattern — when to apply (omit for always-on)
---

Prompt Files (.prompt.md)

---
description: 'Short description shown in / menu'
agent: 'agent'            # Target agent: 'agent', 'ask', 'edit', or custom name
model: 'Claude Sonnet 4'  # Optional model override
tools: ['search/codebase', 'githubRepo', 'read', 'edit']  # Available tools
---

Custom Agents (.agent.md)

---
name: my-agent             # Display name
description: 'What this agent does and when to use it'
tools: ['search', 'read', 'edit', 'fetch', 'usages']
model: 'Claude Sonnet 4'  # Optional model
handoffs:                  # Optional workflow transitions
  - label: 'Next Step'
    agent: other-agent
    prompt: 'Continue with...'
    send: false            # true = auto-submit
---

Agent Skills (SKILL.md)

---
name: my-skill-name        # Lowercase, hyphens for spaces
description: >
  What the skill does and when Copilot should load it.
  Be specific about trigger phrases and use cases.
---

Hooks (hooks.json)

{
  "hooks": [
    {
      "type": "command",
      "event": "pre-tool-execution",
      "bash": "./scripts/my-hook.sh",
      "powershell": "./scripts/my-hook.ps1",
      "timeoutSec": 30
    }
  ]
}

Workflow: Creating Customizations

1. Identify the need — Use the decision tree above
2. Read the reference — Open the relevant file from references/
3. Copy the template — Start from the matching file in templates/
4. Customize — Follow the guidelines in the reference document
5. Test — Use the Chat Debug View (Ctrl+Shift+P → "Chat: Open Debug View")
6. Iterate — Refine based on actual agent behavior

Progressive Discovery

This skill uses progressive discovery — only load what you need:

• This file (SKILL.md): Decision tree + quick reference (always loaded first)
• references/: Deep-dive documentation per primitive (load on demand)
• templates/: Copy-paste starting points (load when scaffolding)
• examples/: Real-world configurations (load for inspiration)

When Copilot loads this skill, start here. Only read reference files when you need
detailed guidance on a specific primitive. Only read templates when you need to
generate files. Only read examples when the user wants a comprehensive setup.

Important Notes

• Agent Skills require the chat.useAgentSkills setting enabled (preview feature)
• Hooks work with Copilot coding agent and Copilot CLI (not local chat)
• Custom agents were previously called "chat modes" — .chatmode.md files still work
• Skills in .claude/skills/ directories are also recognized by Copilot
• The /init command auto-generates initial instructions from your project
• Use the Chat Debug View to verify which instructions/skills are loaded