john/prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

copilot instructions

Browse Source
This commit is contained in:
John Lancaster
2026-06-19 01:15:27 -05:00
parent be9551c76e
commit ef3255544f
8 changed files with 345 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/skills/copilot-customization/SKILL.md
+78
View File
@@ -0,0 +1,78 @@
---
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.
docs/skills/copilot-customization/references/vscode-customization.md
+82
View File
@@ -0,0 +1,82 @@
# VS Code Copilot Customization References
Use these notes as a source map before creating or debugging Copilot customizations.
## Official Sources
- Customization overview: https://code.visualstudio.com/docs/copilot/customization/overview
- Custom instructions: https://code.visualstudio.com/docs/copilot/customization/custom-instructions
- Agent skills: https://code.visualstudio.com/docs/copilot/customization/agent-skills
- Prompt files: https://code.visualstudio.com/docs/copilot/customization/prompt-files
- Custom agents: https://code.visualstudio.com/docs/copilot/customization/custom-agents
- MCP servers: https://code.visualstudio.com/docs/copilot/customization/mcp-servers
- Hooks: https://code.visualstudio.com/docs/copilot/customization/hooks
## Customization Types
- Instructions describe standards and conventions that apply to every request or to matching files.
- Prompt files save reusable slash-command prompts for recurring tasks.
- Agent Skills package reusable workflows, scripts, examples, and resources that load on demand.
- Custom agents define specialized personas, tool access, model choices, and role-specific workflows.
- MCP servers connect the agent to external tools, resources, and data.
- Hooks run deterministic actions at defined lifecycle points.
- Agent plugins bundle related customization types into an installable package.
## Instructions
Use `.github/copilot-instructions.md` for workspace-wide rules that should be included in every chat request. Use `AGENTS.md` when multiple agents should share the same repository guidance, or when nested agent guidance is useful. Use `CLAUDE.md` for Claude-compatible instruction sharing.
Use `.github/instructions/**/*.instructions.md` for file-based or task-specific rules. Supported frontmatter fields include:
```yaml
---
name: Documentation Standards
description: Rules for documentation writing tasks
applyTo: '**/*.md'
---
```
`applyTo` is a workspace-relative glob. If it is omitted, the instruction file can still be manually attached but does not automatically apply by file match.
## Agent Skills
Skills live in a directory whose name must match the `name` field in `SKILL.md`. VS Code supports project skills in `.github/skills/`, `.claude/skills/`, and `.agents/skills/`, and personal skills under user-level skill folders.
Required skill frontmatter:
```yaml
---
name: skill-name
description: Description of what the skill does and when to use it.
---
```
Useful optional fields:
- `argument-hint`: shown when invoking the skill as a slash command.
- `user-invocable`: controls whether it appears in the slash menu.
- `disable-model-invocation`: controls whether the model can auto-load it.
- `context`: can use `fork` for a separate subagent context when supported.
Skills load progressively: discovery reads frontmatter, instruction loading reads `SKILL.md`, and extra resources load only when linked from the skill document.
## Priority And Discovery
When multiple instruction sources apply, personal instructions have higher priority than repository instructions, and repository instructions have higher priority than organization instructions. If multiple instruction files exist, VS Code combines them; do not rely on ordering between instruction files.
For monorepos, `chat.useCustomizationsInParentRepositories` can enable discovery from a trusted parent repository root. Skill locations can also be configured with `chat.agentSkillsLocations`, and instruction locations with `chat.instructionsFilesLocations`.
## Troubleshooting
If a customization is not applied:
1. Confirm the file is in a supported location.
2. Confirm frontmatter is valid YAML.
3. Confirm skill `name` matches the parent directory.
4. Confirm `applyTo` matches the file path when using `*.instructions.md`.
5. Confirm relevant settings are enabled, such as instruction inclusion, referenced instruction inclusion, or AGENTS/CLAUDE support.
6. Use the Chat customization diagnostics view or Agent Debug Logs to inspect what VS Code loaded.
## Writing Effective Instructions
Keep instructions short, self-contained, and focused on non-obvious rules. Include the reason for a rule when it helps with edge cases. Prefer concrete examples over abstract preferences. Split unrelated rules into separate targeted files when they have different triggers.