John Lancaster
79 lines
4.8 KiB
Markdown
79 lines
4.8 KiB
Markdown
---
|
|
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.'
|
|
argument-hint: '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](./references/vscode-customization.md) 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.
|