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

usage docs

Browse Source
This commit is contained in:
John Lancaster
2026-06-18 23:50:37 -05:00
parent 1254cc5432
commit 59c638c634
5 changed files with 514 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/copilot.md
+177
View File
@@ -0,0 +1,177 @@
---
icon: lucide/bot
---
# Copilot MCP Mechanics
## Purpose
This page explains how the GitHub Copilot extension in VS Code behaves as an MCP client when connected to `personal-mcp`, including why tools can appear while resource attachment appears unavailable.
## Core Model
Copilot interacts with MCP servers through separate capability lanes:
1. tools (invoked by the model during execution)
2. resources (attached as read-only context)
3. prompts (server-provided prompt templates)
These lanes are related but independently gated in the client.
The documented reliable paths are:
1. attach MCP resources explicitly through `Add Context > MCP Resources` or `MCP: Browse Resources`
2. let Copilot invoke MCP tools when the task and tool descriptions make that relevant
3. invoke MCP prompts explicitly with `/server.prompt` when your server exposes them
## What Actually Happens In VS Code
### MCP server side
Your server can advertise resources and serve them correctly. In this project that includes catalog resources and skill document resources.
### Copilot session side
The chat surface exposes tools, resources, and prompts through different UI paths. In practice, you can encounter sessions where tool use is available but MCP resource attachment is not exposed in `Add Context`.
That is why you can sometimes see MCP tools before you see `Add Context > MCP Resources`.
## Why The Picker Sometimes Shows Only Tools
`MCP Resources...` in Add Context requires at least:
1. at least one connected MCP server advertises resource capability
2. the current chat surface exposes MCP resource attachment
If the second condition is not met, resources can be available on the server while still being absent from the picker.
## Practical Workflow
Use this sequence to confirm behavior:
1. run `MCP: Browse Resources` and verify resources exist
2. use `MCP: List Servers` to verify the server is enabled and running
3. open Copilot Chat
4. check `Add Context` for `MCP Resources...`
5. if still missing, restart the server and reload VS Code window
## Recommended Usage Pattern
1. rely on catalog resources for discovery (`skills_index`, `patterns`, etc.)
2. fetch only selected skill documents for context
3. keep slash commands for deterministic fallback flows
When resource attachment is unavailable in the active session, use thin catalog discovery tools as operational fallback:
1. `search_patterns`
2. `get_pattern_by_id`
3. `get_skill_document_by_id`
These should stay read-only, minimal, and schema-aligned with catalog resources.
## What To Type In Copilot Chat
Use prompts that tell Copilot which MCP feature path to take.
### If `MCP Resources...` is available
Use the resource attachment UI first, then ask Copilot to work from the attached material.
Example:
```text
I attached the catalog resources and the FastAPI async SQLAlchemy modernization skill document. Use that context to propose a migration plan for this repo.
```
If you want to keep the attachment sequence explicit, use:
```text
I attached personal-mcp catalog resources first. Use them to identify the best matching skill, then work only from the selected skill document.
```
### If only tools are available
Ask Copilot to explicitly use the catalog tools.
Example discovery prompt:
```text
Use the personal-mcp catalog tools to search for the most relevant skill for FastAPI async SQLAlchemy modernization. Then load the selected skill document and use it as context for your answer.
```
Example direct-load prompt:
```text
Call get_skill_document_by_id for fastapi-async-sqlalchemy-modernization and use that document as the main context for this task.
```
Example bounded-selection prompt:
```text
Search personal-mcp skills for NiceGUI UI customization, select at most 2 strong matches, load the best skill document, and answer using only that material plus the workspace code.
```
## Repo Instructions Example
Repo instructions are the best place to teach Copilot when MCP content is relevant and which path to prefer.
If you add a repo-level `copilot-instructions.md`, keep the rule simple: prefer catalog-first discovery, keep loaded skill context small, and fall back to tools when resource attachment is unavailable.
Instructions can strongly steer behavior, but they do not guarantee that VS Code will auto-attach MCP resources for a request. For reliable resource use, either attach resources explicitly or prompt Copilot to use the fallback tools.
Example:
```md
# MCP Usage
When a task may benefit from personal-mcp skills, use this sequence:
1. Start with personal-mcp catalog discovery when the task appears to match documented implementation patterns.
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. Treat skill documents as guidance, then reconcile them with the actual repository code before making changes.
Preferred discovery order:
1. `resource://catalog/skills_index` or `resource://catalog/patterns`
2. `resource://skills/<skill-id>/document`
Tool fallback order:
1. `search_patterns`
2. `get_pattern_by_id`
3. `get_skill_document_by_id`
If confidence is low after catalog discovery, ask one clarifying question before loading more skill documents.
```
That instruction style does two useful things:
1. it tells Copilot to prefer the MCP server when relevant without forcing it on every prompt
2. it keeps context size bounded so skill loading does not become noisy or expensive
If you want stronger behavior, add one more line that names the MCP server directly:
```md
Use the `personal-mcp` server for skill discovery whenever the task involves documented implementation patterns available from the catalog.
```
## Known Gotcha
A successful `resources/list` response from the server does not guarantee the resource picker appears in every Copilot session type. UI availability is session-capability-dependent.
## Further Reading
### VS Code docs
1. [Add and manage MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
2. [MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
3. [Manage context for AI](https://code.visualstudio.com/docs/chat/copilot-chat-context)
4. [AI features cheat sheet](https://code.visualstudio.com/docs/agents/reference/ai-features-cheat-sheet)
### Project docs
1. [Resource-First Pattern Module Architecture](./architecture.md)
2. [Static Docs Hosting Pattern](./mcp_layout.md)
3. [Skill Usage Mechanics](./usage.md)
docs/index.md
+2
View File
@@ -30,3 +30,5 @@ When the server is running, the health check is available at `/healthz` and the
- [Resource-First Pattern Module Architecture](./architecture.md)
- [Static Docs Hosting Pattern](./mcp_layout.md)
- [Skill Usage Mechanics](./usage.md)
- [Copilot MCP Mechanics](./copilot.md)
docs/new_skill.md
+20
View File
@@ -28,6 +28,26 @@ Use this checklist after generating a new skill under `docs/skills/<slug>/`.
8. Rebuild and smoke-test.
Run `uv run zensical build` to publish the docs site, then run a quick Python check or start the app to confirm the new resource loads.
## Discovery Tool Policy
To keep behavior consistent across MCP clients and Copilot session types, follow this boundary:
1. Keep per-skill servers resource-only.
2. Keep discovery/query tools centralized in the catalog server.
3. Keep canonical content in `docs/skills/<slug>/SKILL.md` and expose it through `resource://skills/<skill-id>/document`.
### Do
1. Add or update `metadata.yaml` fields (`id`, `description`, `tags`, `capabilities`) so catalog discovery quality stays high.
2. Use catalog resources as the primary discovery surface.
3. Add thin, read-only catalog tools only when client behavior needs a fallback path.
### Don't
1. Do not add duplicate discovery tools to each skill package.
2. Do not duplicate canonical skill guidance in tool descriptions.
3. Do not create mutating catalog tools for skill discovery.
## Minimal Shape
- Docs content: `docs/skills/<slug>/SKILL.md`
docs/usage.md
+194
View File
@@ -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.