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.

Prompt guidance is now exposed through both prompt resources and MCP prompt objects. Prompt objects are additive; authored markdown remains the canonical source.

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_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}

Each skill publishes a canonical Markdown document resource:

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

Prompts publish a canonical prompt document resource:

1. resource://prompts/<prompt-id>/document

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

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

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

Authoring rules for metadata quality and instruction patterns are maintained in Authoring Guide.

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)
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
**/*.md	docs/authoring.md	resource://skills/zensical-docs/document
tests/**	docs/testing.md	resource://skills/pytesting/document
.vscode/**	docs/skills/vscode-configuration/SKILL.md	resource://skills/vscode-configuration/document

Minimal shim shape:

---
name: <short scope name>
description: Route <path scope> edits to the Personal MCP <skill-id> resource.
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)

When to use thin shims:

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 not to use thin shims:

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.

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.