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

name, description, argument-hint

name	description	argument-hint
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?

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/<slug>/SKILL.md, with optional one-level references/ files.
3. Choose consistent names: docs slug and resource id use kebab-case; Python namespace uses snake_case.
4. Create src/personal_mcp/skills/<python_namespace>/ with __init__.py, server.py, and metadata.yaml.
5. Expose only resource://skills/<skill-id>/document from the per-skill server.
6. Put discovery metadata in metadata.yaml, including id, name, version, description, tags, capabilities, and depends_on.
7. Mount the skill server in src/personal_mcp/mcp.py using the Python namespace.
8. Validate with the document loader and uv run zensical build.

Keep per-skill servers resource-only. Catalog-level discovery is the only place for thin fallback discovery tools.

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.