prompts/docs/copilot.md

icon

icon
lucide/bot

Copilot MCP Mechanics

Purpose

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.

Capability Lanes

Copilot interacts with MCP servers through independently exposed lanes:

1. tools invoked during execution
2. resources attached as read-only context
3. server-provided prompts

This server publishes skills as native skill:// resources, prompts through registry-backed resources and MCP prompt objects, and generic resource fallback tools through FastMCP.

Native Skill Resources

For every skill, Copilot can discover:

1. skill://<name>/SKILL.md
2. skill://<name>/_manifest
3. skill://<name>/{path*} supporting-file template

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.

Resource Picker Availability

MCP Resources... in Add Context requires both:

1. a connected server advertising resource capability
2. a chat surface that exposes MCP resource attachment

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.

Recommended Workflow

When resource attachment is available:

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

When only tools are available:

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

Both paths resolve through the same FastMCP provider.

Prompt Examples

Resource attachment:

Use the attached personal-mcp skill as guidance, then reconcile it with the repository before proposing changes.

Tool-only discovery:

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.

Direct loading:

Read skill://async-fastapi-sqlmodel/SKILL.md and apply only the sections relevant to this repository.

Supporting material:

Read skill://pytesting/_manifest, select the one reference relevant to async test lifecycle, and use that file with the main skill instructions.

Repository Instruction Pattern

A repo-level instruction should name the native retrieval order and context budget:

When a task matches a personal-mcp skill:

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.

Instructions steer behavior but do not force VS Code to attach resources automatically.

Prompt Objects

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.

Troubleshooting

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

1. FastMCP Skills Provider
2. Add and manage MCP servers
3. MCP configuration reference
4. Manage context for AI
5. Skill Usage Mechanics