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

changed to skill provider

Browse Source
This commit is contained in:
John Lancaster
2026-08-07 19:09:54 -05:00
parent c6817a074e
commit 44edffb8b7
48 changed files with 552 additions and 2946 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/copilot.md
+61 -147
View File
@@ -6,199 +6,113 @@ icon: lucide/bot
## 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.
This page explains how GitHub Copilot in VS Code consumes native skill resources from `personal-mcp`, including sessions where tools are visible but resource attachment is not.
## Core Model
## Capability Lanes
Copilot interacts with MCP servers through separate capability lanes:
Copilot interacts with MCP servers through independently exposed lanes:
1. tools (invoked by the model during execution)
2. resources (attached as read-only context)
3. prompts (server-provided prompt templates)
1. tools invoked during execution
2. resources attached as read-only context
3. server-provided prompts
These lanes are related but independently gated in the client.
This server publishes skills as native `skill://` resources, prompts through registry-backed resources and MCP prompt objects, and generic resource fallback tools through FastMCP.
Reliable paths are:
## Native Skill Resources
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
For every skill, Copilot can discover:
## What Actually Happens In VS Code
1. `skill://<name>/SKILL.md`
2. `skill://<name>/_manifest`
3. `skill://<name>/{path*}` supporting-file template
### MCP server side
The main resource description comes from `SKILL.md`. The manifest discloses supporting paths, sizes, and SHA256 hashes. This is the only skill discovery contract; there is no parallel skill catalog.
Your server can advertise resources and serve them correctly. In this project that includes catalog resources and skill document resources.
## Resource Picker Availability
### Copilot session side
`MCP Resources...` in Add Context requires both:
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`.
1. a connected server advertising resource capability
2. a chat surface that exposes MCP resource attachment
That is why you can sometimes see MCP tools before you see `Add Context > MCP Resources`.
A successful `resources/list` response does not guarantee the picker appears in every session type. Use `MCP: Browse Resources` to distinguish server availability from chat UI availability.
## Why The Picker Sometimes Shows Only Tools
## Recommended Workflow
`MCP Resources...` in Add Context requires at least:
When resource attachment is available:
1. at least one connected MCP server advertises resource capability
2. the current chat surface exposes MCP resource attachment
1. browse the server's resources
2. attach one relevant `skill://<name>/SKILL.md`
3. attach `_manifest` only if supporting detail may be needed
4. attach only selected supporting files
If the second condition is not met, resources can be available on the server while still being absent from the picker.
When only tools are available:
## Practical Workflow
1. call `list_resources`
2. select a native main skill URI by name and description
3. call `read_resource` for that URI
4. read `_manifest` and supporting files only as needed
Use this sequence to confirm behavior:
Both paths resolve through the same FastMCP provider.
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
## Prompt Examples
## Recommended Usage Pattern
1. rely on canonical catalog resources for discovery (`skills_index`, then `skills/{skill_id}`)
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 ResourcesAsTools first, then thin catalog discovery tools as parity fallback:
1. `list_resources`
2. `read_resource`
3. `search_patterns`
4. `get_pattern_by_id`
5. `get_skill_document_by_id`
Canonical naming policy:
1. Prefer the five canonical tool names above in prompts and instructions.
2. For compatibility with clients that emit `catalog_*` naming, the server also exposes:
- `catalog_search_patterns`
- `catalog_get_pattern_by_id`
- `catalog_get_skill_document_by_id`
3. Canonical and compatibility alias tools return equivalent payloads for the same input.
The first two are generated from the canonical resource surface and should be preferred in tool-only clients.
These should stay read-only, minimal, and schema-aligned with catalog resources.
For very large tool catalogs, server operators can optionally enable tool search mode (`regex` or `bm25`) while keeping `list_resources` and `read_resource` pinned as always-visible fallback tools.
## 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:
Resource attachment:
```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.
Use the attached personal-mcp skill as guidance, then reconcile it with the repository before proposing changes.
```
If you want to keep the attachment sequence explicit, use:
Tool-only discovery:
```text
I attached personal-mcp catalog resources first. Use them to identify the best matching skill, then work only from the selected skill document.
Call list_resources, choose the best matching skill://.../SKILL.md resource, and read it. Inspect its _manifest only if a supporting file is needed. Load at most two candidate skills.
```
### If only tools are available
Ask Copilot to explicitly use resource-backed tools first.
Example resource-backed prompt:
Direct loading:
```text
Use personal-mcp tool fallback by first calling list_resources, then read_resource for resource://catalog/skills_index and the selected resource://skills/<skill-id>/document URI. Use only that loaded skill context in your answer.
Read skill://async-fastapi-sqlmodel/SKILL.md and apply only the sections relevant to this repository.
```
If needed, use the thin catalog tools.
Example discovery prompt:
Supporting material:
```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.
Read skill://pytesting/_manifest, select the one reference relevant to async test lifecycle, and use that file with the main skill instructions.
```
Example direct-load prompt:
## Repository Instruction Pattern
```text
Call get_skill_document_by_id for async-fastapi-sqlmodel 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:
A repo-level instruction should name the native retrieval order and context budget:
```md
# MCP Usage
When a task matches a personal-mcp skill:
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 `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. Treat skill documents as guidance, then reconcile them with the actual repository code before making changes.
Preferred discovery 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
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 catalog discovery, ask one clarifying question before loading more skill documents.
1. Prefer an already attached native skill resource.
2. Otherwise use `list_resources` and select one `skill://<name>/SKILL.md` resource by description.
3. Read `_manifest` only when supporting material is needed.
4. Load at most two candidate main files and only the relevant supporting paths.
5. Reconcile guidance with the current repository before editing.
```
That instruction style does two useful things:
Instructions steer behavior but do not force VS Code to attach resources automatically.
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
## Prompt Objects
If you want stronger behavior, add one more line that names the MCP server directly:
Prompt modules remain separate from skills. When the client supports MCP prompt APIs, use prompt listing and `get_prompt` for parameterized workflows. Authored `PROMPT.md` remains the source of truth for each prompt.
```md
Use the `personal-mcp` server for skill discovery whenever the task involves documented implementation patterns available from the catalog.
```
## Troubleshooting
## 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.
1. Use `MCP: List Servers` to confirm the server is enabled.
2. Use `MCP: Browse Resources` to confirm native skill resources exist.
3. Restart the MCP server after changing skill files because production uses `reload=False`.
4. Reload the VS Code window if the server is healthy but the resource picker remains stale.
5. In tool-only sessions, verify `list_resources` and `read_resource` are visible.
## 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)
1. [FastMCP Skills Provider](https://gofastmcp.com/servers/providers/skills)
2. [Add and manage MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
3. [MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)
4. [Manage context for AI](https://code.visualstudio.com/docs/chat/copilot-chat-context)
5. [Skill Usage Mechanics](./usage.md)