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

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	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. Keep loaded context bounded to the selected skill and relevant files.