From c73771c2f43e97f7245039ed8e2fb3b767a4a3fd Mon Sep 17 00:00:00 2001 From: John Lancaster <32917998+jsl12@users.noreply.github.com> Date: Sat, 20 Jun 2026 17:52:03 -0500 Subject: [PATCH] shim instructions --- docs/skills/copilot-customization/SKILL.md | 75 +++++++++++++++++----- 1 file changed, 60 insertions(+), 15 deletions(-) diff --git a/docs/skills/copilot-customization/SKILL.md b/docs/skills/copilot-customization/SKILL.md index b927531..014650e 100644 --- a/docs/skills/copilot-customization/SKILL.md +++ b/docs/skills/copilot-customization/SKILL.md @@ -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//document` + - `resource://skills//references/` +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.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//document` in `x-personal-mcp.capabilities`. -6. Declare references in `x-personal-mcp.references` as `ref-id -> references/.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: