prompts/docs/usage.md

icon

icon
lucide/workflow

Skill Usage Mechanics

Purpose

This page describes how clients discover and load personal-mcp skills published by the FastMCP Skills Provider.

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

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	skill://zensical-docs/SKILL.md
tests/**	Testing	skill://pytesting/SKILL.md
.vscode/**	VS Code Configuration	skill://vscode-configuration/SKILL.md

Minimal shape:

---
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.