From 1cfe9c8e400367f755aed953213d0a82524aae34 Mon Sep 17 00:00:00 2001 From: John Lancaster <32917998+jsl12@users.noreply.github.com> Date: Mon, 22 Jun 2026 08:26:47 -0500 Subject: [PATCH] docs --- docs/authoring.md | 75 +++++++++++++++++++++++- docs/usage.md | 144 +++++++++++++++++++++------------------------- 2 files changed, 139 insertions(+), 80 deletions(-) diff --git a/docs/authoring.md b/docs/authoring.md index 9326526..1c888f2 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -89,7 +89,78 @@ Source examples: - [FastMCP docs](https://gofastmcp.com/getting-started/welcome) - [Zensical docs](https://zensical.org/docs/) -## Navigation And Frontmatter +## Authoring for GitHub Copilot + +For resource selection or tool-based matching to work well, each skill should have: + +1. precise `description` +2. focused `tags` +3. explicit `capabilities` +4. stable `id` and slug naming + +Weak metadata reduces Copilot match quality and increases wrong context injection. + +### Copilot Instruction Authoring Pattern + +If you want Copilot to use `personal-mcp` skill content more reliably, instruction files should describe three things clearly: + +1. when MCP-backed skill guidance is relevant +2. which retrieval path Copilot should prefer first +3. how much skill context it should load before answering + +Instructions strongly steer discovery behavior, but they do not force VS Code to auto-attach MCP resources. Keep wording explicit about preferred path and fallback path. + +Repository policy: + +1. start from catalog discovery +2. prefer MCP resources when the current chat surface exposes resource attachment +3. fall back to catalog tools when resource attachment is unavailable +4. keep loaded skill context bounded + +Suggested instruction text: + +```md +When a task may match a documented implementation pattern from `personal-mcp`: + +1. Start with catalog-first discovery. +2. Prefer MCP resources when the chat surface exposes resource attachment. +3. If MCP resource attachment is unavailable, use `list_resources`/`read_resource` first, then thin catalog tools if needed. +4. Load only the most relevant skill document, or at most 2 skill documents. +5. Reconcile loaded skill guidance with the actual repository code before making changes. + +Preferred resource order: + +1. `resource://catalog/skills_index` +2. `resource://catalog/skills/{skill_id}` +3. `resource://skills//document` +4. `resource://skills//references/` when needed + +Preferred tool fallback order: + +1. `list_resources` +2. `read_resource` +3. `search_patterns` +4. `get_pattern_by_id` +5. `get_skill_document_by_id` + +Compatibility aliases for clients that use `catalog_*` naming are also available: + +1. `catalog_search_patterns` +2. `catalog_get_pattern_by_id` +3. `catalog_get_skill_document_by_id` +4. `catalog_search_prompts` +5. `catalog_get_prompt_by_id` + +Use canonical names first; aliases exist only to preserve interoperability when a client emits non-canonical names. + +If confidence is low after discovery, ask one clarifying question before loading more context. +``` + +This is guidance, not a guarantee. It defines a reliable policy while preserving the resource-first architecture. + +Thin shim path binding guidance for MCP consumers is covered in [Skill Usage Mechanics](./usage.md). + +## Zensical Details When adding or restructuring pages: @@ -116,6 +187,8 @@ uv run ty check uv run pytest ``` +Address any errors or warnings that result. + If a change only affects docs content, `uv run zensical build` is still required. ## Quick Authoring Checklist diff --git a/docs/usage.md b/docs/usage.md index cae6c9f..c7f0aa0 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -138,16 +138,9 @@ flowchart TD H --> I ``` -## Authoring Requirements For Reliable Matching +## Authoring Requirements -For resource selection or tool-based matching to work well, each skill should have: - -1. precise `description` -2. focused `tags` -3. explicit `capabilities` -4. stable `id` and slug naming - -Weak metadata reduces Copilot match quality and increases wrong context injection. +Authoring rules for metadata quality and instruction patterns are maintained in [Authoring Guide](./authoring.md). ## Practical Guidelines @@ -175,64 +168,6 @@ Behavior: 2. `bm25` uses ranked natural-language matching. 3. `list_resources` and `read_resource` stay visible so resource-backed fallback remains primary. -## Copilot Instruction Pattern - -If you want Copilot to use `personal-mcp` skill content more reliably, the instruction file should describe three things clearly: - -1. when MCP-backed skill guidance is relevant -2. which retrieval path Copilot should prefer first -3. how much skill context it should load before answering - -That matters because instructions can strongly steer discovery behavior, but they do not force VS Code to auto-attach MCP resources. A good instruction tells Copilot to prefer the canonical MCP content path while remaining accurate about the fallback path. - -In this repository, the right policy is: - -1. start from catalog discovery -2. prefer MCP resources when the current chat surface exposes resource attachment -3. fall back to catalog tools when resource attachment is unavailable -4. keep loaded skill context bounded - -Suggested instruction text: - -```md -When a task may match a documented implementation pattern from `personal-mcp`: - -1. Start with catalog-first discovery. -2. Prefer MCP resources when the chat surface exposes resource attachment. -3. If MCP resource attachment is unavailable, use `list_resources`/`read_resource` first, then thin catalog tools if needed. -4. Load only the most relevant skill document, or at most 2 skill documents. -5. Reconcile loaded skill guidance with the actual repository code before making changes. - -Preferred resource order: - -1. `resource://catalog/skills_index` -2. `resource://catalog/skills/{skill_id}` -3. `resource://skills//document` -4. `resource://skills//references/` when needed - -Preferred tool fallback order: - -1. `list_resources` -2. `read_resource` -3. `search_patterns` -4. `get_pattern_by_id` -5. `get_skill_document_by_id` - -Compatibility aliases for clients that use `catalog_*` naming are also available: - -1. `catalog_search_patterns` -2. `catalog_get_pattern_by_id` -3. `catalog_get_skill_document_by_id` -4. `catalog_search_prompts` -5. `catalog_get_prompt_by_id` - -Use canonical names first; aliases exist only to preserve interoperability when a client emits non-canonical names. - -If confidence is low after discovery, ask one clarifying question before loading more context. -``` - -This is intentionally guidance, not a guarantee. It gives Copilot a strong policy for when to use resources and when to fall back to discovery tools, while preserving the resource-first architecture. - ## Failure Modes and Recovery Common failure modes: @@ -258,22 +193,13 @@ Use this checklist when configuring GitHub Copilot in VS Code against `personal- 2. verify catalog resources are readable 3. verify at least one `resource://skills//document` can be fetched 4. add one deterministic `/` command for fallback -5. add Copilot instruction: prefer catalog-first discovery, then targeted skill fetch +5. confirm your workspace instruction policy exists (see [Authoring Guide](./authoring.md)) 6. verify context size remains bounded 7. validate behavior in Ask/Edit/Agent-style workflows with at least one task each -## Local Ruff Workflow +## Runtime Discovery Workflow -Use [Ruff](https://docs.astral.sh/ruff/) locally through `uv` so lint and format checks are consistent for contributors. - -1. Lint check: `uv run ruff check .` -2. Apply safe lint fixes: `uv run ruff check . --fix` -3. Format files: `uv run ruff format .` -4. Format check (CI-style): `uv run ruff format --check .` - -Rule-family baseline for this repository is `E`, `F`, `I`, and `UP`, configured in [pyproject.toml](../pyproject.toml). - -Suggested instruction policy text: +Use this runtime sequence in chat sessions: 1. Start with catalog-first discovery. 2. Prefer MCP resources when the chat surface exposes resource attachment. @@ -281,6 +207,66 @@ Suggested instruction policy text: 4. Prefer `list_resources`/`read_resource` first when operating in tool-only clients. 5. If confidence is low, ask one clarifying question before loading more. +## Thin Shim Path Binding Pattern + +For repositories that consume this MCP server, thin shims are a usage pattern for binding path scopes to the right MCP resources. The "thin shims" are just lightweight, repo-specific instructions files that tell Copilot to use certain MCP resources when editing files that match a pattern. That helps with ensuring Copilot uses the intended resources without too much specific goading in the prompt. + +Use thin shims in Copilot instruction files to bind file-path scopes to: + +1. the most relevant docs page for human-readable conventions +2. the matching MCP resource URI for machine retrieval + +Keep each shim short: trigger, primary resource, minimal execution pattern, and one fallback rule. + +Recommended binding pattern: + +1. Put shims in `.github/instructions/*.instructions.md`. +2. Scope each shim with `applyTo` so it activates only where needed. +3. Point to one primary `resource://skills//document` URI. +4. Link one repository docs page as the human-facing companion. +5. Expand to references only when the task needs deeper detail. + +Current repository examples: + +| applyTo scope | Primary docs page | Primary MCP resource | +| --- | --- | --- | +| `**/*.md` | [docs/authoring.md](./authoring.md) | `resource://skills/zensical-docs/document` | +| `tests/**` | [docs/testing.md](./testing.md) | `resource://skills/pytesting/document` | +| `.vscode/**` | [docs/skills/vscode-configuration/SKILL.md](./skills/vscode-configuration/SKILL.md) | `resource://skills/vscode-configuration/document` | + +Minimal shim shape: + +```md +--- +name: +description: Route edits to the Personal MCP resource. +applyTo: '' +--- + +When editing files matching , use `resource://skills//document` as the primary guidance source. + +Execution pattern: + +1. Load the primary skill document first. +2. Apply only sections relevant to the file being edited. +3. Keep edits minimal and aligned with repository conventions. +4. If confidence is low, ask one clarifying question before editing. + +Companion docs page: [docs/.md](./.md) +``` + +When to use thin shims: + +1. Repositories that want thin local policy while keeping canonical guidance in MCP resources. +2. Stable, repeated workflows with clear path ownership. +3. Cases where teams need predictable retrieval behavior. + +When not to use thin shims: + +1. Broad, ambiguous tasks with unclear ownership boundaries. +2. Cases where one shim would need many exceptions. +3. Situations better handled by catalog-first discovery at runtime. + ## Summary The intended model is: