john/prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc updates

Browse Source
This commit is contained in:
John Lancaster
2026-08-30 11:49:58 -05:00
parent bbaa84720c
commit 9eb4ccbc6e
9 changed files with 203 additions and 675 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/personal_mcp/docs/usage.md
+41 -87
View File
@@ -2,105 +2,59 @@
icon: lucide/workflow
---
# Skill Usage Mechanics
# Using Personal MCP
## Purpose
Personal MCP gives clients access to skills, prompts, and general documentation. Use the smallest piece of content that matches the task instead of loading the whole library.
This page describes how clients discover and load `personal-mcp` skills published by the [FastMCP Skills Provider](https://gofastmcp.com/servers/providers/skills).
## Connect
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 `src/personal_mcp/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. direct resource reads on selected `skill://<name>/SKILL.md` entries
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. Use `MCP: Browse Resources` to confirm server-side availability, then attach only the minimum skill resources needed for the current task.
A reliable prompt is:
The HTTP endpoint is `/mcp`. For a local server on port `8765`, connect to:
```text
Browse MCP resources, select the best matching skill://.../SKILL.md entry by description, inspect its _manifest only if supporting detail is needed, and reconcile the guidance with this workspace.
http://127.0.0.1:8765/mcp
```
## Thin Shim Pattern
Clients that launch servers as subprocesses can use:
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.
```bash
uv run mcp-stdio
```
## Failure Recovery
## Use A Skill
When no skill is an obvious match:
Skills are MCP resources. A client should:
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
1. browse the available `skill://<name>/SKILL.md` resources
2. choose one by its name and description
3. read the main `SKILL.md`
4. read its `_manifest` only when extra reference material is needed
5. load only the relevant supporting files
When a supporting path fails, refresh `_manifest`; file paths are the public supporting-resource identifiers.
The guidance should then be checked against the code and conventions in the current workspace.
## Runtime Checklist
## Use A Prompt
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.
Prompts are reusable workflows with named arguments. Browse the server's prompts, select one by its description, and supply the requested values when invoking it.
In VS Code, MCP prompts appear as chat slash commands. Resources can be opened from **MCP: Browse Resources** and attached as context when the active chat surface supports it.
## Tool Fallbacks
Some clients can call tools but cannot browse MCP resources or prompts directly. For those clients, the server exposes four read-only tools:
- `list_resources`
- `read_resource`
- `list_prompts`
- `get_prompt`
They provide access to the same underlying content. Clients with native resource and prompt support should use those native features.
## Example Request
```text
Browse the available Personal MCP skills, choose the best match for this task,
read its main SKILL.md, and load supporting files only if they are needed.
Apply the guidance to this repository rather than treating it as generated output.
```
For the exact resource and prompt formats, see the [content contracts](./contracts/index.md).