prompts/docs/usage.md

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

## 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:

```md
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 catalog tools instead.
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` or `resource://catalog/patterns`
2. `resource://skills/<skill-id>/document`

Preferred tool fallback order:

1. `search_patterns`
2. `get_pattern_by_id`
3. `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 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.