# VS Code Copilot Customization References

Use these notes as a source map before creating or debugging Copilot customizations.

## Official Sources

!!! info "Official sources"
    - [Customization overview](https://code.visualstudio.com/docs/copilot/customization/overview)
    - [Custom instructions](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)
    - [Agent skills](https://code.visualstudio.com/docs/copilot/customization/agent-skills)
    - [Prompt files](https://code.visualstudio.com/docs/copilot/customization/prompt-files)
    - [Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)
    - [MCP servers](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
    - [Hooks](https://code.visualstudio.com/docs/copilot/customization/hooks)

## Customization Types

- Instructions describe standards and conventions that apply to every request or to matching files.
- Prompt files save reusable slash-command prompts for recurring tasks.
- Agent Skills package reusable workflows, scripts, examples, and resources that load on demand.
- Custom agents define specialized personas, tool access, model choices, and role-specific workflows.
- MCP servers connect the agent to external tools, resources, and data.
- Hooks run deterministic actions at defined lifecycle points.
- Agent plugins bundle related customization types into an installable package.

## Instructions

Use `.github/copilot-instructions.md` for workspace-wide rules that should be included in every chat request. Use `AGENTS.md` when multiple agents should share the same repository guidance, or when nested agent guidance is useful. Use `CLAUDE.md` for Claude-compatible instruction sharing.

Use `.github/instructions/**/*.instructions.md` for file-based or task-specific rules. Supported frontmatter fields include:

```yaml
---
name: Documentation Standards
description: Rules for documentation writing tasks
applyTo: '**/*.md'
---
```

`applyTo` is a workspace-relative glob. If it is omitted, the instruction file can still be manually attached but does not automatically apply by file match.

## Agent Skills

Skills live in a directory whose name must match the `name` field in `SKILL.md`. VS Code supports project skills in `.github/skills/`, `.claude/skills/`, and `.agents/skills/`, and personal skills under user-level skill folders.

Required skill frontmatter:

```yaml
---
name: skill-name
description: Description of what the skill does and when to use it.
---
```

Useful optional fields:

- `argument-hint`: shown when invoking the skill as a slash command.
- `user-invocable`: controls whether it appears in the slash menu.
- `disable-model-invocation`: controls whether the model can auto-load it.
- `context`: can use `fork` for a separate subagent context when supported.

Skills load progressively: discovery reads frontmatter, instruction loading reads `SKILL.md`, and extra resources load only when linked from the skill document.

## Priority And Discovery

When multiple instruction sources apply, personal instructions have higher priority than repository instructions, and repository instructions have higher priority than organization instructions. If multiple instruction files exist, VS Code combines them; do not rely on ordering between instruction files.

For monorepos, `chat.useCustomizationsInParentRepositories` can enable discovery from a trusted parent repository root. Skill locations can also be configured with `chat.agentSkillsLocations`, and instruction locations with `chat.instructionsFilesLocations`.

## Troubleshooting

If a customization is not applied:

1. Confirm the file is in a supported location.
2. Confirm frontmatter is valid YAML.
3. Confirm skill `name` matches the parent directory.
4. Confirm `applyTo` matches the file path when using `*.instructions.md`.
5. Confirm relevant settings are enabled, such as instruction inclusion, referenced instruction inclusion, or AGENTS/CLAUDE support.
6. Use the Chat customization diagnostics view or Agent Debug Logs to inspect what VS Code loaded.

## Writing Effective Instructions

Keep instructions short, self-contained, and focused on non-obvious rules. Include the reason for a rule when it helps with edge cases. Prefer concrete examples over abstract preferences. Split unrelated rules into separate targeted files when they have different triggers.