prompts/docs/skills/copilot-customization/SKILL.md

name, description, argument-hint, x-personal-mcp

name	description	argument-hint	x-personal-mcp
copilot-customization	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.	What Copilot behavior are you customizing, and should it be workspace-scoped, personal, or exposed as an MCP skill resource?	id version tags capabilities depends_on copilot-customization 1.0.0 copilot vscode customization instructions prompts agent-skills custom-agents hooks mcp personal-mcp skills resource://skills/copilot-customization/document new-skill zensical-docs

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 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:

• Reference known resources directly, such as:
  • resource://catalog/skills_index
  • resource://catalog/skills/{skill_id}
  • resource://skills/<skill-id>/document
  • resource://skills/<skill-id>/references/<ref-id>

2. Discovery-first strategy:

• Start at catalog discovery (resource://catalog/skills_index), select the best skill match, then load the skill document and only the minimal references needed.

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 direct URIs or discovery for that repo's common workflows.
4. Prefer loading only the most relevant skill document first; expand to references 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 resource://skills/zensical-docs/document and apply Zensical-native documentation conventions unless they conflict with expected MkDocs compatibility."

Prompt-style shim intent:

1. "For docs authoring tasks, consult resource://skills/zensical-docs/document, 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 repo skill metadata exposes the correct resource://skills/<skill-id>/document capability.
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.