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, or *.instructions.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.

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.

Repo Integration Workflow

When adding a new skill to this personal-mcp repo, follow the resource-first pattern:

1. Search the catalog for new skill and load resource://skills/new-skill/document.
2. Create authored docs under docs/skills/<skill-id>/SKILL.md, with optional nested references/ markdown files.
3. Keep skill-id stable and consistent across directory name, name, and x-personal-mcp.id.
4. Put discovery metadata in SKILL.md frontmatter under x-personal-mcp.
5. Declare resource://skills/<skill-id>/document in x-personal-mcp.capabilities.
6. Declare references in x-personal-mcp.references as ref-id -> references/<file>.md mappings.
7. Validate with the registry loader and uv run zensical build.

Keep runtime implementation registry-driven in src/personal_mcp/mcp.py; do not add per-skill Python server modules.

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.