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

changed to skill provider

Browse Source
This commit is contained in:
John Lancaster
2026-08-07 19:09:54 -05:00
parent c6817a074e
commit 44edffb8b7
48 changed files with 552 additions and 2946 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/usage.md
+71 -309
View File
@@ -6,361 +6,123 @@ icon: lucide/workflow
## Purpose
This page explains practical usage mechanics for the GitHub Copilot extension in VS Code when `personal-mcp` is configured as an MCP server:
This page describes how clients discover and load `personal-mcp` skills published by the [FastMCP Skills Provider](https://gofastmcp.com/servers/providers/skills).
1. explicit `/` command flows when you want deterministic control
2. guided skill loading when relevance can be inferred
Skills are MCP resources. The client remains responsible for selecting guidance, loading only useful supporting material, and applying it to the current workspace.
The goal is to show how Copilot behaves as a client and how to shape that behavior.
## Published Skill Surface
## Mental Model
Each directory beneath `docs/skills/` publishes:
In Copilot Chat, there are two distinct mechanisms:
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
1. `/` commands are user-invoked orchestration shortcuts.
2. MCP resources are server-published knowledge units that can be attached as read-only context, while MCP tools provide an execution path for discovery and retrieval.
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.
In this repository, skill guidance is exposed as MCP resources, not as server-owned prompt execution. Copilot remains the orchestrator.
The manifest contains every skill-relative path, byte size, and SHA256 hash. References do not have synthetic ids or a separate catalog record.
Prompt guidance is now exposed through both prompt resources and MCP prompt objects. Prompt objects are additive; authored markdown remains the canonical source.
Prompts remain available through prompt catalog resources, prompt document resources, and MCP prompt objects.
## Background Mechanics
## Discovery Workflow
### What the server publishes
Use this bounded sequence:
`personal-mcp` registers resources from the validated docs registry and exposes catalog discovery resources:
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.
1. `resource://catalog/skills_index`
2. `resource://catalog/skills_index{?q,tag,capability,cursor,limit}`
3. `resource://catalog/skills/{skill_id}`
4. `resource://catalog/prompts_index`
5. `resource://catalog/prompts_index{?q,tag,cursor,limit}`
6. `resource://catalog/prompts/{prompt_id}`
Do not load every skill or every supporting file up front.
Each skill publishes a canonical Markdown document resource:
## FastMCP Client Utilities
1. `resource://skills/<skill-id>/document`
2. `resource://skills/<skill-id>/references/<ref-id>`
FastMCP provides native utilities in `fastmcp.utilities.skills`:
Prompts publish a canonical prompt document resource:
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.
1. `resource://prompts/<prompt-id>/document`
These utilities operate directly on the native `skill://` contract and require no repository-specific adapter.
The document payload is loaded from `docs/skills/<skill-id>/SKILL.md` and returned with metadata.
## Tool-Only Clients
### What Copilot does as the client
The server installs [`ResourcesAsTools`](https://gofastmcp.com/servers/transforms/resources-as-tools), which exposes generic tools:
When connected to MCP, Copilot can do the following at runtime:
1. `list_resources`
2. `read_resource`
1. interpret the current chat request
2. use attached MCP resources that you provide through the chat UI
3. invoke MCP tools when the task and tool descriptions make that relevant
4. summarize relevant sections into working context
5. apply guidance while generating edits or recommendations
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.
This behavior is shaped by the active chat surface, prompt or instruction guidance, and available MCP tools.
There are no skill-specific search, detail, or document tools. This avoids maintaining a second discovery implementation.
For reliable progressive discovery, use one of these sequences:
## Optional Tool Search
1. explicit resource path: attach a catalog resource first, then attach only selected skill documents
2. tool path: call catalog tools first, then load only selected skill documents
For large tool inventories, FastMCP search transforms can reduce tool-list noise:
### What `/` commands do
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.
`/` commands in VS Code are client-side prompt entry points (for example in prompt files). They do not replace MCP resources. In Copilot, they typically:
These settings filter tools, not native skill resources.
1. enforce a known sequence
2. collect missing inputs
3. call discovery/read steps in a predictable order
## Copilot Invocation
Think of `/` commands as orchestration shortcuts on top of MCP resources.
In VS Code, skills can arrive through:
### What automatic loading means here
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
In this project, "automatic loading" should be read as a preference you express through instructions and prompts, not as a guaranteed VS Code feature that auto-attaches MCP resources.
Instructions can steer retrieval, but they do not guarantee automatic resource attachment in every chat surface.
In practice, there are two reliable ways to make skill content available in chat:
A reliable prompt for a tool-only session is:
1. explicit resource attachment through `Add Context > MCP Resources` or `MCP: Browse Resources`
2. MCP tool invocation using `list_resources`/`read_resource` (ResourcesAsTools), with thin catalog tools as parity fallback
For prompt content, there is a third option when the client supports MCP prompt APIs:
1. prompt-object discovery and invocation through MCP prompt lists and `get_prompt`
Instruction quality and metadata quality still matter, because they influence whether Copilot recognizes that the MCP server is relevant and chooses the tool path well.
## Invocation Mechanics Deep Dive
This section expands on how invocation works at runtime across chat entry points.
### Invocation Surfaces
A user request can arrive through one of these surfaces:
1. plain chat request in Ask/Edit/Agent mode
2. slash command invocation of a prompt or skill
3. chat request with manually attached MCP resources
Each surface changes how much discovery Copilot must do before applying guidance.
### Resolution Order
When multiple retrieval paths are possible, use this priority order:
1. attached MCP resources already in context
2. explicit slash-command workflow steps
3. catalog-first discovery via MCP resources
4. tool fallback (`list_resources` then `read_resource`, then thin catalog parity tools)
This ordering keeps behavior predictable while minimizing unnecessary context expansion.
### Prompt Invocation Pipeline
For prompt-oriented flows, treat invocation as this sequence:
1. parse prompt frontmatter and argument hints
2. validate required inputs and ask one clarifying question if blocked
3. run bounded discovery against prompt or skill catalogs
4. fetch only selected document resources
5. apply instructions to produce edits, recommendations, or commands
6. report what was loaded and why
Prompt objects and prompt document resources are additive mechanisms. The authored Markdown prompt document remains the canonical contract.
### Argument Syntax Nuance
Invocation strings such as target_modules=src/personal_mcp/registry/ingest/skill.py, mode=plan-only are a structured authoring convention, not a guaranteed client-level grammar.
In practice:
1. Prompt metadata defines expected argument names and intent.
2. Prompt body instructions define how those inputs should be interpreted.
3. Copilot may receive equivalent intent in freeform phrasing and still resolve it correctly.
Implication for authors:
1. Treat key=value examples as clarity aids for users.
2. Do not assume strict parser enforcement unless your prompt explicitly validates and rejects malformed input.
3. Include accepted invocation examples and one fallback freeform example so behavior is predictable for both humans and the model.
This distinction is important because argument hints improve discoverability, while robust prompt instructions determine actual runtime reliability.
### Skill Invocation Pipeline
For guided skill loading, use this sequence:
1. start from `resource://catalog/skills_index` or scoped index query
2. inspect one or two top candidates for intent and capability fit
3. fetch `resource://skills/<skill-id>/document`
4. load references only when the task needs deeper detail
5. apply only relevant sections and keep context bounded
This avoids the common failure mode where many skill documents are loaded up front.
### Determinism vs Flexibility
Use this decision rule:
1. choose slash-command invocation when repeatability and step order are critical
2. choose guided loading when requests vary and speed matters more than strict orchestration
3. escalate from guided loading to slash-command flow when confidence is low or conflicting skills appear
### Invocation Trace (What to Log in Results)
For transparent operation, include a concise invocation trace in task outputs:
1. entry surface used (plain chat, slash command, or attached resource)
2. discovery source used (catalog resource or tool path)
3. resources fetched (ids only)
4. clarifying questions asked (if any)
5. reason for fallback or escalation (if used)
This makes behavior auditable and easier to tune over time.
## Operating Pattern
Use both modes intentionally in Copilot Chat.
### Mode A: Explicit `/` command
Use when you need predictable, repeatable behavior across teammates.
Good fits:
1. onboarding workflows
2. compliance-sensitive tasks
3. repetitive scaffolding
### Mode B: Guided skill loading
Use when requests are varied and you want lower friction during normal chat.
Good fits:
1. ad hoc implementation questions
2. mixed-topic debugging
3. architecture tradeoff discussions
### Mode C: Fallback flow
Start with guided loading in chat; escalate to a `/` command when:
1. confidence is low
2. multiple skills conflict
3. the user wants strict repeatability
## Suggested Resolution Flow
```mermaid
flowchart TD
A[User request in Copilot Chat] --> B{Deterministic workflow needed?}
B -- Yes --> C[/Run slash command/]
C --> D[Copilot fetches known catalog and skill resources]
B -- No --> E[Copilot uses attached resources or catalog tools]
E --> F{Confident skill match?}
F -- Yes --> G[Copilot fetches skill documents]
F -- No --> H[Ask clarifying question or suggest slash command]
D --> I[Apply guidance to task]
G --> I
H --> I
```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.
```
## Authoring Requirements
## Thin Shim Pattern
Authoring rules for metadata quality and instruction patterns are maintained in [Authoring Guide](./authoring.md).
Consumer repositories can bind file scopes to native skill resources with short `.github/instructions/*.instructions.md` files.
## Practical Guidelines
1. Keep `/` commands minimal and high-value.
2. Do not duplicate full methodology text inside command files.
3. Keep canonical guidance in `docs/skills/*/SKILL.md`.
4. In Copilot instructions, prefer catalog-first discovery before skill fetch.
5. Prefer small, relevant context slices over loading every skill.
6. Keep slash commands focused on deterministic orchestration, not content duplication.
If you skip the catalog/index step, behavior is less predictable and may either miss relevant skills or pull too much context.
## Optional Tool Search Mode
When tool catalogs grow, FastMCP search transforms can reduce tool-list noise for tool-only clients.
Runtime switches:
1. `PERSONAL_MCP_TOOL_SEARCH=none|regex|bm25` (default `none`)
2. `PERSONAL_MCP_TOOL_SEARCH_MAX_RESULTS=<positive int>` (default `5`)
Behavior:
1. `regex` uses deterministic regex matching for targeted queries.
2. `bm25` uses ranked natural-language matching.
3. `list_resources` and `read_resource` stay visible so resource-backed fallback remains primary.
## Failure Modes and Recovery
Common failure modes:
1. No relevant skill selected.
2. Too many skills selected (context bloat).
3. Stale assumptions from old metadata.
4. Slash command bypasses normal discovery and forces the wrong skill.
Recovery sequence:
1. re-run catalog lookup
2. narrow by tags and intent
3. fetch only top candidates
4. if still ambiguous, ask one clarifying question
5. use explicit `/` workflow for deterministic fallback
## Checklist
Use this checklist when configuring GitHub Copilot in VS Code against `personal-mcp`:
1. confirm server connectivity
2. verify catalog resources are readable
3. verify at least one `resource://skills/<id>/document` can be fetched
4. add one deterministic `/` command for fallback
5. confirm your workspace instruction policy exists (see [Authoring Guide](./authoring.md))
6. verify context size remains bounded
7. validate behavior in Ask/Edit/Agent-style workflows with at least one task each
## Runtime Discovery Workflow
Use this runtime sequence in chat sessions:
1. Start with catalog-first discovery.
2. Prefer MCP resources when the chat surface exposes resource attachment.
3. Otherwise use tool fallback to load one or two likely skill documents.
4. Prefer `list_resources`/`read_resource` first when operating in tool-only clients.
5. If confidence is low, ask one clarifying question before loading more.
## Thin Shim Path Binding Pattern
For repositories that consume this MCP server, thin shims are a usage pattern for binding path scopes to the right MCP resources. The "thin shims" are just lightweight, repo-specific instructions files that tell Copilot to use certain MCP resources when editing files that match a pattern. That helps with ensuring Copilot uses the intended resources without too much specific goading in the prompt.
Use thin shims in Copilot instruction files to bind file-path scopes to:
1. the most relevant docs page for human-readable conventions
2. the matching MCP resource URI for machine retrieval
Keep each shim short: trigger, primary resource, minimal execution pattern, and one fallback rule.
Recommended binding pattern:
1. Put shims in `.github/instructions/*.instructions.md`.
2. Scope each shim with `applyTo` so it activates only where needed.
3. Point to one primary `resource://skills/<skill-id>/document` URI.
4. Link one repository docs page as the human-facing companion.
5. Expand to references only when the task needs deeper detail.
Current repository examples:
| applyTo scope | Primary docs page | Primary MCP resource |
| `applyTo` scope | Companion docs | Primary skill resource |
| --- | --- | --- |
| `**/*.md` | [docs/authoring.md](./authoring.md) | `resource://skills/zensical-docs/document` |
| `tests/**` | [docs/testing.md](./testing.md) | `resource://skills/pytesting/document` |
| `.vscode/**` | [docs/skills/vscode-configuration/SKILL.md](./skills/vscode-configuration/SKILL.md) | `resource://skills/vscode-configuration/document` |
| `**/*.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 shim shape:
Minimal shape:
```md
---
name: <short scope name>
description: Route <path scope> edits to the Personal MCP <skill-id> resource.
name: <scope name>
description: Route <path scope> edits to a personal-mcp skill.
applyTo: '<glob>'
---
When editing files matching <glob>, use `resource://skills/<skill-id>/document` as the primary guidance source.
Execution pattern:
1. Load the primary skill document first.
2. Apply only sections relevant to the file being edited.
3. Keep edits minimal and aligned with repository conventions.
4. If confidence is low, ask one clarifying question before editing.
Companion docs page: [docs/<page>.md](./<page>.md)
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.
```
When to use thin shims:
## Failure Recovery
1. Repositories that want thin local policy while keeping canonical guidance in MCP resources.
2. Stable, repeated workflows with clear path ownership.
3. Cases where teams need predictable retrieval behavior.
When no skill is an obvious match:
When not to use thin shims:
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. Broad, ambiguous tasks with unclear ownership boundaries.
2. Cases where one shim would need many exceptions.
3. Situations better handled by catalog-first discovery at runtime.
When a supporting path fails, refresh `_manifest`; file paths are the public supporting-resource identifiers.
## Summary
## Runtime Checklist
The intended model is:
1. skills are canonical MCP resources
2. `/` commands are explicit Copilot control shortcuts
3. guided skill loading should be catalog-driven, bounded, and explicit about whether it is using resources or tools
Using all three together gives predictable control when needed and low-friction assistance by default in VS Code.
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.