|
|
|
@@ -30,7 +30,12 @@ Use this skill when a task is about changing how GitHub Copilot or VS Code agent
|
|
|
|
|
|
|
|
|
|
## When to Use
|
|
|
|
|
|
|
|
|
|
- Creating or updating `.github/copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md`, or `*.instructions.md` files.
|
|
|
|
|
- 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.
|
|
|
|
@@ -55,6 +60,60 @@ If the request is ambiguous, ask only for the missing axis that changes the file
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
@@ -66,20 +125,6 @@ Use [VS Code customization references](./references/vscode-customization.md) for
|
|
|
|
|
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:
|
|
|
|
|
John Lancaster