swapped docs symlink

2026-08-07 21:07:23 -05:00
parent 5005cd7001
commit f240486a7e
92 changed files with 69 additions and 42 deletions
@@ -0,0 +1,105 @@
+---
+icon: lucide/workflow
+---
+
+# Skill Usage Mechanics
+
+## Purpose
+
+This page describes how clients discover and load `personal-mcp` skills published by the [FastMCP Skills Provider](https://gofastmcp.com/servers/providers/skills).
+
+Skills are MCP resources. The client remains responsible for selecting guidance, loading only useful supporting material, and applying it to the current workspace.
+
+## Published Skill Surface
+
+Each directory beneath `docs/skills/` publishes:
+
+1. `skill://<name>/SKILL.md` for primary instructions
+2. `skill://<name>/_manifest` for file discovery and integrity metadata
+3. `skill://<name>/{path*}` for supporting files
+
+The server uses `supporting_files="template"`. Main files and manifests appear in `resources/list`; supporting files stay behind per-skill wildcard templates so the resource list remains compact.
+
+The manifest contains every skill-relative path, byte size, and SHA256 hash. References do not have synthetic ids or a separate catalog record.
+
+Prompts are available through native MCP prompt discovery and rendering.
+
+## Discovery Workflow
+
+Use this bounded sequence:
+
+1. List resources or call FastMCP `list_skills()`.
+2. Compare skill names and descriptions.
+3. Read one selected `skill://<name>/SKILL.md`.
+4. Read `skill://<name>/_manifest` only when supporting material may be useful.
+5. Fetch the minimum supporting paths needed for the task.
+6. Reconcile the guidance with the actual repository code before making changes.
+
+Do not load every skill or every supporting file up front.
+
+## FastMCP Client Utilities
+
+FastMCP provides native utilities in `fastmcp.utilities.skills`:
+
+1. `list_skills(client)` discovers main skill resources.
+2. `get_skill_manifest(client, name)` parses a generated manifest.
+3. `download_skill(client, name, target_dir)` downloads one skill.
+4. `sync_skills(client, target_dir)` downloads all advertised skills.
+
+These utilities operate directly on the native `skill://` contract and require no repository-specific adapter.
+
+## Copilot Invocation
+
+In VS Code, skills can arrive through:
+
+1. explicit attachment from `Add Context > MCP Resources` or `MCP: Browse Resources`
+2. a slash-command prompt that names a specific native skill URI
+
+Instructions can steer retrieval, but they do not guarantee automatic resource attachment in every chat surface.
+
+A reliable prompt is:
+
+```text
+Browse personal-mcp resources and select the best matching skill://.../SKILL.md resource. Read one selected skill, inspect its _manifest only if supporting detail is needed, and reconcile the guidance with this workspace.
+```
+
+## Thin Shim Pattern
+
+Consumer repositories can bind file scopes to native skill resources with short `.github/instructions/*.instructions.md` files.
+
+| `applyTo` scope | Companion docs | Primary skill resource |
+| --- | --- | --- |
+| `**/*.md` | [Authoring Guide](./authoring.md) | `skill://zensical-docs/SKILL.md` |
+| `tests/**` | [Testing](./testing.md) | `skill://pytesting/SKILL.md` |
+| `.vscode/**` | [VS Code Configuration](./skills/vscode-configuration/SKILL.md) | `skill://vscode-configuration/SKILL.md` |
+
+Minimal shape:
+
+```md
+---
+name: <scope name>
+description: Route <path scope> edits to a personal-mcp skill.
+applyTo: '<glob>'
+---
+
+Load `skill://<skill-name>/SKILL.md` first. Read `_manifest` and supporting files only when the task needs deeper detail. Apply the guidance to the current repository rather than treating it as generated output.
+```
+
+## Failure Recovery
+
+When no skill is an obvious match:
+
+1. compare the available main-resource descriptions again
+2. select at most two candidates
+3. read their main files, not all supporting files
+4. ask one clarifying question if the choice remains ambiguous
+
+When a supporting path fails, refresh `_manifest`; file paths are the public supporting-resource identifiers.
+
+## Runtime Checklist
+
+1. Confirm MCP connectivity.
+2. Confirm at least one `skill://<name>/SKILL.md` resource is listed.
+3. Read its `_manifest` and verify `SKILL.md` appears with a SHA256 hash.
+4. Read one supporting file through its manifest path.
+5. Keep loaded context bounded to the selected skill and relevant files.