feat: add mcp documentation skill for spec-aware development#609
feat: add mcp documentation skill for spec-aware development#609
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a Claude Code skill that provides live MCP specification context from modelcontextprotocol.io, enabling spec-aware development and reviews without relying on potentially outdated model training data.
Changes:
- Update
.gitignoreto allow committing.claude/content while keeping local Claude settings untracked. - Add a new Claude Code skill at
.claude/skills/mcp-docs/SKILL.mdwith guidance for fetching and citing MCP spec sources (MCP search tool first,llms.txtfallback).
Reviewed changes
Copilot reviewed 1 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
.gitignore |
Stops ignoring the entire .claude/ directory; ignores only .claude/settings.local.json so skills can be committed. |
.claude/skills/mcp-docs/SKILL.md |
Introduces the mcp-docs skill instructions for retrieving and citing up-to-date MCP specification content. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
| --- | ||
| name: mcp-docs | ||
| description: > | ||
| Fetch live MCP specification and docs from modelcontextprotocol.io. Training data may be |
There was a problem hiding this comment.
There was a problem hiding this comment.
Please read the PR description more carefully. What you sent is not related to this skill
There was a problem hiding this comment.
Sorry, I missed the mention of documentation in the PR, that was my mistake. It is stated in the skill itself
| 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") | ||
| ``` |
There was a problem hiding this comment.
see previous comment. there is a well-known spec locations
There was a problem hiding this comment.
please check llms.txt
This skill is about documentation in general, not the specification schema. I’ll create a separate skill for the schema and open a dedicated PR for it later
|
|
||
| ### 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"). |
There was a problem hiding this comment.
...or comment explicitly states the spec version
There was a problem hiding this comment.
Where exactly is that stated in the comment? In the prompt, in the KDoc, or somewhere else?
The instruction should be unambiguous, which is why the wording user explicitly requests is used with an example
Add a Claude Code skill (
.claude/skills/mcp-docs/) that provides live MCP documentation and specification contextMotivation and Context
The modelcontextprotocol.io site provides both an MCP server and an 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:
Breaking Changes
None
Types of changes
Checklist