---
name: copilot-customization
description: 'Plan, create, review, and debug GitHub Copilot and VS Code agent customizations, including instructions, prompt files, skills, custom agents, hooks, MCP servers, and repo-specific personal-mcp skill integration.'
---

# Copilot Customization

Use this skill when a task is about changing how GitHub Copilot or VS Code agents behave through customization files or MCP-backed skill resources.

## When to Use

- Creating or updating:
    - `.github/copilot-instructions.md`
    - `AGENTS.md`
    - `CLAUDE.md`
    - `*.instructions.md` files
    - `*.prompt.md` files
- Creating prompt files, custom agents, hooks, or Agent Skills.
- Deciding whether behavior belongs in instructions, prompts, skills, agents, hooks, MCP servers, or agent plugins.
- Debugging why a customization is not discovered, loaded, or invoked.
- Adding a new documentation-backed skill to this `personal-mcp` repository.

## Start With The Decision

Choose the smallest customization that matches the desired behavior:

1. Use always-on instructions for project-wide coding standards, architecture decisions, security rules, and documentation standards that should apply to most requests.
2. Use file-based instructions for conventions that only apply to matching files, folders, languages, frameworks, or documentation types.
3. Use prompt files for reusable slash commands that package a single recurring prompt.
4. Use Agent Skills for portable, task-specific workflows that may include references, scripts, examples, or templates.
5. Use custom agents for specialized personas, tool restrictions, model choices, or role-specific workflows.
6. Use hooks when a deterministic lifecycle action must enforce a policy, run a command, or block unsafe behavior.
7. Use MCP servers when the agent needs live external tools, structured resources, or discoverable data beyond static instruction files.
8. Use agent plugins when several related customizations should ship together as an installable package.

If the request is ambiguous, ask only for the missing axis that changes the file type: scope, trigger, expected output, required tools, or whether it must be portable beyond VS Code.

## Research Map

Use [VS Code customization references](./references/vscode-customization.md) for official-source details about locations, frontmatter, discovery behavior, priority, and troubleshooting.

## Repo Shim Pattern For Personal MCP

Use a shim when you want another repository to consume this server as a preference and documentation source without duplicating methodology content.

### What the shim does

1. Tells the agent when to consult this MCP server.
2. Tells the agent how to retrieve relevant guidance.
3. Keeps repo-local behavior thin while canonical guidance stays in Personal MCP resources.

### Shim formats

Use either:

1. A repo instruction file (`*.instructions.md`) for always-on or file-scoped behavior.
2. A prompt file (`*.prompt.md`) for explicit, on-demand guidance retrieval.

### Retrieval strategies

Choose one of these patterns:

1. Direct URI strategy:
  - Read `skill://<skill-name>/SKILL.md` when the required skill is known.
  - Read `skill://<skill-name>/_manifest` only when supporting material may be useful.
  - Read selected supporting files at `skill://<skill-name>/<supporting-path>`.
2. Discovery-first strategy:
  - List resources, compare native main-resource names and descriptions, then load the best matching `SKILL.md`.
  - In tool-only clients, use only `list_resources` and `read_resource` for the same sequence.

### Authoring guidance for shims

1. Keep shim content short and procedural; avoid copying large guidance blocks from Personal MCP.
2. State trigger conditions clearly (for example: "when creating a new skill" or "when editing docs contracts").
3. Specify whether to use a direct native URI or resource listing for that repo's common workflows.
4. Prefer loading only the most relevant main file first; inspect its manifest only when needed.
5. For stable repeated workflows, use explicit URIs. For broader or ambiguous requests, use discovery-first.

### Minimal shim examples

Instruction-style shim intent:

1. "For markdown edits (`applyTo: '**/*.md'`), load `skill://zensical-docs/SKILL.md` and apply Zensical-native documentation conventions unless they conflict with expected MkDocs compatibility."

Prompt-style shim intent:

1. "For docs authoring tasks, consult `skill://zensical-docs/SKILL.md`, summarize the relevant authoring constraints, then propose the smallest markdown change for this repository."

### Validation for shim implementation

1. Confirm the shim triggers in expected contexts.
2. Confirm resource loading path is unambiguous (direct URI or discovery).
3. Confirm repo-local customization remains thin and references Personal MCP as source of truth.

## Workspace Customization Workflow

1. Identify the customization primitive and scope.
2. Check existing files before creating a new one.
3. Keep the description or frontmatter trigger specific and keyword-rich.
4. Keep instructions concise, focused, and self-contained.
5. Add examples only when they clarify a non-obvious convention.
6. For `*.instructions.md`, set `applyTo` only when automatic file matching is intended.
7. For skills, make the folder name match the `name` field exactly and reference any extra files from `SKILL.md` with relative links.
8. Validate placement, YAML frontmatter, discovery settings, and whether the customization should be workspace or user scoped.

## Quality Checks

Before finishing:

1. Confirm the customization file is in a supported location for its intended scope.
2. Confirm required frontmatter fields are present and valid.
3. Confirm names match directory names where VS Code requires it.
4. Confirm descriptions include the phrases users are likely to ask for.
5. Confirm extra skill resources are linked from `SKILL.md`.
6. Confirm native discovery exposes `skill://<skill-name>/SKILL.md`, `_manifest`, and supporting-file reads.
7. State any remaining ambiguity or user choice, such as personal vs workspace scope.

## Output Contract

Return the concrete customization created or changed, where it lives, how to invoke or trigger it, and any validation performed.