prompts/docs/usage.md

icon

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. guided skill 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 registers resources from the validated docs registry and exposes catalog discovery resources:

1. resource://catalog/skills_index
2. resource://catalog/skills/{skill_id}

Each skill publishes a canonical Markdown document resource:

1. resource://skills/<skill-id>/document
2. resource://skills/<skill-id>/references/<ref-id>

The document payload is loaded from docs/skills/<skill-id>/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 using list_resources/read_resource (ResourcesAsTools), with thin catalog tools as parity fallback

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

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.

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.

Copilot Instruction Pattern

If you want Copilot to use personal-mcp skill content more reliably, the instruction file should describe three things clearly:

1. when MCP-backed skill guidance is relevant
2. which retrieval path Copilot should prefer first
3. how much skill context it should load before answering

That matters because instructions can strongly steer discovery behavior, but they do not force VS Code to auto-attach MCP resources. A good instruction tells Copilot to prefer the canonical MCP content path while remaining accurate about the fallback path.

In this repository, the right policy is:

1. start from catalog discovery
2. prefer MCP resources when the current chat surface exposes resource attachment
3. fall back to catalog tools when resource attachment is unavailable
4. keep loaded skill context bounded

Suggested instruction text:

When a task may match a documented implementation pattern from `personal-mcp`:

1. Start with catalog-first discovery.
2. Prefer MCP resources when the chat surface exposes resource attachment.
3. If MCP resource attachment is unavailable, use `list_resources`/`read_resource` first, then thin catalog tools if needed.
4. Load only the most relevant skill document, or at most 2 skill documents.
5. Reconcile loaded skill guidance with the actual repository code before making changes.

Preferred resource order:

1. `resource://catalog/skills_index`
2. `resource://catalog/skills/{skill_id}`
3. `resource://skills/<skill-id>/document`
4. `resource://skills/<skill-id>/references/<ref-id>` when needed

Preferred tool fallback order:

1. `list_resources`
2. `read_resource`
3. `search_patterns`
4. `get_pattern_by_id`
5. `get_skill_document_by_id`

If confidence is low after discovery, ask one clarifying question before loading more context.

This is intentionally guidance, not a guarantee. It gives Copilot a strong policy for when to use resources and when to fall back to discovery tools, while preserving the resource-first architecture.

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

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.