129 lines
5.1 KiB
Markdown
129 lines
5.1 KiB
Markdown
---
|
|
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 remain available through prompt catalog resources, prompt document resources, and MCP prompt objects.
|
|
|
|
## 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.
|
|
|
|
## Tool-Only Clients
|
|
|
|
The server installs [`ResourcesAsTools`](https://gofastmcp.com/servers/transforms/resources-as-tools), which exposes generic tools:
|
|
|
|
1. `list_resources`
|
|
2. `read_resource`
|
|
|
|
A tool-only client should list resources, select a `skill://<name>/SKILL.md` URI, and read it. It can then read `_manifest` and selected supporting paths through the same tool.
|
|
|
|
There are no skill-specific search, detail, or document tools. This avoids maintaining a second discovery implementation.
|
|
|
|
## Optional Tool Search
|
|
|
|
For large tool inventories, FastMCP search transforms can reduce tool-list noise:
|
|
|
|
1. `PERSONAL_MCP_TOOL_SEARCH=none|regex|bm25` defaults to `none`.
|
|
2. `PERSONAL_MCP_TOOL_SEARCH_MAX_RESULTS=<positive int>` defaults to `5`.
|
|
3. `list_resources` and `read_resource` remain visible in search modes.
|
|
|
|
These settings filter tools, not native skill resources.
|
|
|
|
## Copilot Invocation
|
|
|
|
In VS Code, skills can arrive through:
|
|
|
|
1. explicit attachment from `Add Context > MCP Resources` or `MCP: Browse Resources`
|
|
2. generic `list_resources` and `read_resource` tool calls
|
|
3. 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 for a tool-only session is:
|
|
|
|
```text
|
|
Use personal-mcp list_resources to find 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. Confirm `list_resources` and `read_resource` are available for tool-only clients.
|
|
6. Keep loaded context bounded to the selected skill and relevant files.
|