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