VS Code Copilot Customization

Decision Matrix

Use this matrix to recommend the right customization type. Always start here.

Quick decision flow

Do you want it ON automatically for every request?
├─ YES → Instructions (.instructions.md / copilot-instructions.md / AGENTS.md)
└─ NO, I invoke it manually →
       Does it need persistent persona, tool restrictions, or model choice?
       ├─ YES → Custom Agent (.agent.md)
       └─ NO →
              Is it a reusable multi-agent portable capability?
              ├─ YES → Agent Skill (SKILL.md)
              └─ NO → Prompt File (.prompt.md)

Do you want to run shell commands around agent actions?
└─ YES → Hook (hooks/*.json)

Do you want to bundle everything for distribution?
└─ YES → Agent Plugin (plugin.json)

1. Custom Instructions

Always-on context and rules. Stored in .github/copilot-instructions.md (workspace-wide), AGENTS.md (multi-agent), or *.instructions.md (file-scoped via applyTo glob).

Read references/instructions.md when asked to create, write, or configure custom instructions.

2. Prompt Files

Reusable task templates invoked manually via / slash command. Stored in .github/prompts/*.prompt.md.

Read references/prompt-files.md when asked to create a prompt file or reusable chat task.

3. Custom Agents

Specialized Copilot persona with tool whitelist, model choice, and optional handoffs. Stored in .github/agents/*.agent.md.

Read references/custom-agents.md when asked to create a custom agent or chat mode.

4. Agent Skills

Portable, progressive-loading capabilities that work across VS Code, Copilot CLI, and cloud agents. Stored in .github/skills/<name>/SKILL.md.

Read references/agent-skills.md when asked to create a skill or when the user asks about SKILL.md format, frontmatter fields, or skill best practices.

5. Hooks

Shell commands triggered at agent lifecycle events (PostToolUse, Stop, etc.). Stored in .github/hooks/*.json.

Read references/hooks.md when asked to create a hook, set up auto-formatting, or run commands around agent actions.

6. Agent Plugins

Bundle skills, agents, hooks, and MCP servers for distribution. Defined in plugin.json.

Read references/plugins.md when asked to create, publish, or install an agent plugin.

File Locations Reference

AI Generation Commands

/init                  → workspace-wide copilot-instructions.md
/create-instruction    → targeted .instructions.md
/create-prompt         → .prompt.md file
/create-agent          → .agent.md file
/create-skill          → agent skill directory
/create-hook           → hook JSON file

Open the Chat Customizations editor for a visual overview:

Command Palette → "Chat: Open Chat Customizations"

Reference files

• references/instructions.md – Custom instructions templates and settings
• references/prompt-files.md – Prompt file templates and input variables
• references/custom-agents.md – Agent templates and handoff configuration
• references/agent-skills.md – Skill format, progressive loading, official docs
• references/hooks.md – Hook templates, events, naming convention
• references/plugins.md – Plugin structure and distribution
• references/frontmatter-reference.md – Complete frontmatter field reference for all types
• references/examples.md – Real-world examples organized by use case

Source: danielsitek/skills — distributed by TomeVault.