usage docs
This commit is contained in:
John Lancaster
+194
@@ -0,0 +1,194 @@
|
||||
---
|
||||
icon: lucide/workflow
|
||||
---
|
||||
|
||||
# Skill Usage Mechanics
|
||||
|
||||
## Purpose
|
||||
|
||||
This page explains practical usage mechanics for the GitHub Copilot extension in VS Code when `personal-mcp` is configured as an MCP server:
|
||||
|
||||
1. explicit `/` command flows when you want deterministic control
|
||||
2. automatic skill context loading when relevance can be inferred
|
||||
|
||||
The goal is to show how Copilot behaves as a client and how to shape that behavior.
|
||||
|
||||
## Mental Model
|
||||
|
||||
In Copilot Chat, there are two distinct mechanisms:
|
||||
|
||||
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.
|
||||
|
||||
In this repository, skill guidance is exposed as MCP resources, not as server-owned prompt execution. Copilot remains the orchestrator.
|
||||
|
||||
## Background Mechanics
|
||||
|
||||
### What the server publishes
|
||||
|
||||
`personal-mcp` mounts skill modules and a catalog module. The catalog exposes discovery resources:
|
||||
|
||||
1. `resource://catalog/skills_index`
|
||||
2. `resource://catalog/skills_details`
|
||||
3. `resource://catalog/patterns`
|
||||
4. `resource://catalog/patterns_by_id`
|
||||
|
||||
Each skill publishes a canonical Markdown document resource:
|
||||
|
||||
1. `resource://skills/<skill-id>/document`
|
||||
|
||||
The document payload is loaded from `docs/skills/<slug>/SKILL.md` and returned with metadata.
|
||||
|
||||
### What Copilot does as the client
|
||||
|
||||
When connected to MCP, Copilot can do the following at runtime:
|
||||
|
||||
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
|
||||
|
||||
This behavior is shaped by the active chat surface, prompt or instruction guidance, and available MCP tools.
|
||||
|
||||
For reliable progressive discovery, use one of these sequences:
|
||||
|
||||
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
|
||||
|
||||
### What `/` commands do
|
||||
|
||||
`/` 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:
|
||||
|
||||
1. enforce a known sequence
|
||||
2. collect missing inputs
|
||||
3. call discovery/read steps in a predictable order
|
||||
|
||||
Think of `/` commands as orchestration shortcuts on top of MCP resources.
|
||||
|
||||
### What automatic loading means here
|
||||
|
||||
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.
|
||||
|
||||
In practice, there are two reliable ways to make skill content available in chat:
|
||||
|
||||
1. explicit resource attachment through `Add Context > MCP Resources` or `MCP: Browse Resources`
|
||||
2. MCP tool invocation such as `search_patterns` followed by `get_skill_document_by_id`
|
||||
|
||||
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.
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## Authoring Requirements For Reliable Matching
|
||||
|
||||
For resource selection or tool-based matching to work well, each skill should have:
|
||||
|
||||
1. precise `description`
|
||||
2. focused `tags`
|
||||
3. explicit `capabilities`
|
||||
4. stable `id` and slug naming
|
||||
|
||||
Weak metadata reduces Copilot match quality and increases wrong context injection.
|
||||
|
||||
## 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.
|
||||
|
||||
## 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. add Copilot instruction: prefer catalog-first discovery, then targeted skill fetch
|
||||
6. verify context size remains bounded
|
||||
7. validate behavior in Ask/Edit/Agent-style workflows with at least one task each
|
||||
|
||||
Suggested instruction policy text:
|
||||
|
||||
1. Start with catalog-first discovery.
|
||||
2. Prefer MCP resources when the chat surface exposes resource attachment.
|
||||
3. Otherwise use catalog tools to search and load one or two likely skill documents.
|
||||
4. If confidence is low, ask one clarifying question before loading more.
|
||||
|
||||
## Summary
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user