John Lancaster
143 lines
6.6 KiB
Markdown
143 lines
6.6 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?'
|
|
x-personal-mcp:
|
|
id: copilot-customization
|
|
version: 1.0.0
|
|
tags:
|
|
- copilot
|
|
- vscode
|
|
- customization
|
|
- instructions
|
|
- prompts
|
|
- agent-skills
|
|
- custom-agents
|
|
- hooks
|
|
- mcp
|
|
- personal-mcp
|
|
- skills
|
|
capabilities:
|
|
- resource://skills/copilot-customization/document
|
|
depends_on:
|
|
- 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](./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:
|
|
- 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.
|