Add a Claude Code skill (`.claude/skills/mcp-docs/`) that provides live MCP documentation and specification context ## Motivation and Context The modelcontextprotocol.io site provides both an [MCP server](https://modelcontextprotocol.io/mcp) and an [llms.txt](https://modelcontextprotocol.io/llms.txt) index for machine-readable access to the documentation. This skill leverages both to give Claude live access to the current spec during development. ## How Has This Been Tested? The skill was evaluated on 3 realistic scenarios (implementation, code review, spec question) comparing with-skill vs without-skill baseline: - **Pass rate**: 100% vs 67% — skill consistently cites spec sources and uses RFC 2119 language - **Token efficiency**: 41% fewer tokens on average (44k vs 75k) — goes directly to spec instead of reverse-engineering from codebase - **Accuracy**: with-skill discovered URL mode elicitation (new in spec 2025-11-25) that baseline missed entirely - **Description triggering**: optimized through 5 iterations of automated trigger evaluation against 20 test prompts ## Breaking Changes None ## Types of changes - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update ## Checklist - [x] I have read the [MCP Documentation](https://modelcontextprotocol.io) - [x] My code follows the repository's style guidelines - [x] New and existing tests pass locally - [x] I have added appropriate error handling - [x] I have added or updated documentation as needed
76 lines
3.5 KiB
Markdown
76 lines
3.5 KiB
Markdown
---
|
|
name: mcp-docs
|
|
description: >
|
|
Fetch live MCP specification and docs from modelcontextprotocol.io. Training data may be
|
|
outdated — default to using this skill when the query touches MCP protocol in any way.
|
|
Trigger for: implementing or debugging MCP features (sampling, elicitation, completion, tools,
|
|
resources, prompts, transports); SEPs or spec requirements; MCP transport behavior (SSE,
|
|
Streamable HTTP, reconnection, retry); authorization/OAuth; conformance test failures;
|
|
capability negotiation; message schemas. Skip only for pure Kotlin, build system, or
|
|
refactoring tasks with zero MCP protocol dependency. When in doubt, trigger.
|
|
user_invocable: true
|
|
---
|
|
|
|
# MCP Documentation Skill
|
|
|
|
Provides access to the official MCP specification and docs from modelcontextprotocol.io. The spec evolves faster than training data — always consult live documentation for protocol specifics like message schemas, required fields, capability negotiation, error handling, and transport requirements.
|
|
|
|
## When to use
|
|
|
|
**Proactively** (without being asked):
|
|
- Implementing a feature defined in the MCP spec
|
|
- Reviewing code that implements MCP protocol behavior
|
|
- Fixing conformance test failures
|
|
|
|
**On demand** (user asks or invokes `/mcp-docs`):
|
|
- Questions about how a specific MCP feature works
|
|
- Clarifying spec ambiguities
|
|
- Looking up SEPs (Specification Enhancement Proposals)
|
|
|
|
## How to fetch documentation
|
|
|
|
### Strategy: MCP tool first, llms.txt fallback
|
|
|
|
**Step 1 — Try the MCP search tool.** If `search_model_context_protocol` is available, use it:
|
|
|
|
```
|
|
search_model_context_protocol(query: "<your search query>")
|
|
```
|
|
|
|
One call, semantically ranked results. Fastest path.
|
|
|
|
**Step 2 — Fallback to llms.txt + WebFetch.** If the MCP tool is not available:
|
|
|
|
1. Fetch the documentation index:
|
|
```
|
|
WebFetch("https://modelcontextprotocol.io/llms.txt", "Return the full content as-is")
|
|
```
|
|
|
|
2. Identify the relevant page URL(s) from the index. Key sections:
|
|
- **Specification**: `specification/...` — protocol details, message formats, transports, lifecycle
|
|
- **SEPs**: `seps/...` — specification enhancement proposals
|
|
- **Learning**: `docs/learn/...` — architecture, concepts
|
|
- **Development**: `docs/develop/...` — building clients/servers
|
|
|
|
3. Fetch the specific page:
|
|
```
|
|
WebFetch("<page-url>", "Return the full content of this documentation page")
|
|
```
|
|
|
|
### Version handling
|
|
|
|
Always use the latest spec version by default. Only use a specific version or draft when the user explicitly requests it (e.g., "check the 2025-03-26 spec" or "what does the draft say").
|
|
|
|
### Search guidance
|
|
|
|
- Protocol message formats, required fields, capability negotiation → **Specification** section
|
|
- Feature motivation, design rationale → relevant **SEP**
|
|
- High-level concepts and architecture → **Learning** resources
|
|
- Use your judgment on query count. A field-level question may need one page; implementing a feature may need 2-3.
|
|
|
|
## Presenting information
|
|
|
|
- **Always cite sources.** Include links to spec pages used: `(source: <url>)`
|
|
- **Spec over training data** for specific protocol details (schemas, fields, error codes, capabilities). Training data is fine for general MCP concepts.
|
|
- **Preserve RFC 2119 language.** The spec uses MUST/SHOULD/MAY — keep this distinction when explaining requirements.
|
|
- **Be concise.** Focus on the details relevant to the user's task. Avoid dumping entire spec pages — extract what matters for the specific question or implementation at hand.
|