docs

2026-06-22 08:39:18 -05:00
parent 313c4ecb1e
commit 1cfe9c8e40
2 changed files with 139 additions and 80 deletions
@@ -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/<skill-id>/document`
+4. `resource://skills/<skill-id>/references/<ref-id>` 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