shim instructions

.github/prompts/skill-bootstrap.prompt.md

@@ -0,0 +1,12 @@
+---
+name: New Skill Bootstrap
+description: Create and fully implement a new docs-first skill in this repository.
+argument-hint: skill-id and goal for the new skill
+agent: agent
+---
+
+# New Skill Bootstrap
+
+Use the canonical bootstrap guidance in [docs/skills/new-skill/SKILL.md](../../docs/skills/new-skill/SKILL.md).
+
+If the request is to create or implement a new skill, load that skill document and follow it as the source of truth.

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/<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:

docs/skills/new-skill/SKILL.md

@@ -21,6 +21,23 @@ x-personal-mcp:
 
 Use this skill to bootstrap a new skill in the docs-first architecture. Try to use the `/create-skill` where possible to structure the output, but place it alongside the other skills in this repo.
 
+## Inputs
+
+1. New skill id (lowercase kebab-case)
+2. One-sentence capability statement (what it does and when to use it)
+3. Optional list of references to include under `references/`
+
+## Source of Truth and Required References
+
+1. Use this file as the baseline template for new skill authoring.
+2. Read and follow these docs before implementing a new skill:
+  - [docs/architecture.md](../../architecture.md)
+  - [docs/content.md](../../content.md)
+  - [docs/frontmatter.md](../../frontmatter.md)
+  - [docs/mcp_layout.md](../../mcp_layout.md)
+  - [docs/uris.md](../../uris.md)
+  - [docs/new_skill.md](../../new_skill.md)
+
 ## Scope
 
 1. Create docs under docs/skills/<skill-id>/.
@@ -39,7 +56,23 @@ Use this skill to bootstrap a new skill in the docs-first architecture. Try to u
 6. For each top-level `references/<name>.md`, expect `resource://skills/<skill-id>/references/<name>` (normalized to lowercase kebab-case).
 7. Add explicit `x-personal-mcp.references` entries only for nested paths or metadata overrides.
 
+## Required Outcomes
+
+1. Create `docs/skills/<skill-id>/SKILL.md` with valid frontmatter and a practical skill body.
+2. Create and populate `docs/skills/<skill-id>/references/` with any needed markdown references.
+3. Ensure frontmatter follows repository contract, including `x-personal-mcp` fields and canonical capabilities.
+4. Keep URI and reference mapping consistent with repository conventions.
+5. Reconcile all updates with repository implementation and avoid introducing parallel metadata systems.
+
 ## Validation
 
 1. uv run zensical build
 2. uv run pytest -q
+
+## Output Contract
+
+Return:
+
+1. Files created or updated
+2. Validation results
+3. Follow-up suggestions for improving the skill