mcp-builder
Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP), Node/TypeScript (MCP SDK), or C#/.NET (Microsoft MCP SDK).
83
73%
Does it follow best practices?
Impact
100%
2.50xAverage score across 3 eval scenarios
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./.github/skills/mcp-builder/SKILL.mdQuality
Discovery
89%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a solid description that clearly identifies its niche (MCP server development) and provides explicit 'Use when' guidance with language-specific triggers. Its main weakness is that the 'what' portion is somewhat high-level—it describes the purpose of MCP servers rather than listing the specific concrete actions the skill teaches (e.g., defining tool schemas, handling authentication, structuring server code).
Suggestions
Add 2-3 more specific concrete actions the skill covers, such as 'define tool schemas, implement authentication, handle errors, and structure server endpoints' to improve specificity.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names the domain (MCP servers) and a general action ('creating high-quality MCP servers that enable LLMs to interact with external services through well-designed tools'), but it doesn't list multiple specific concrete actions like 'define tool schemas, handle authentication, implement error handling, register endpoints'. | 2 / 3 |
Completeness | Clearly answers both 'what' (creating MCP servers that enable LLMs to interact with external services through well-designed tools) and 'when' (explicit 'Use when building MCP servers to integrate external APIs or services' with language-specific triggers). | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'MCP', 'Model Context Protocol', 'MCP servers', 'external APIs', 'FastMCP', 'MCP SDK', 'Python', 'Node', 'TypeScript', 'C#', '.NET'. These cover multiple language variations and the core terminology a user would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | MCP server development is a very specific niche. The description clearly targets Model Context Protocol servers specifically, with distinct triggers like 'MCP', 'FastMCP', 'MCP SDK' that are unlikely to conflict with general API or server-building skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
57%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured orchestration skill that excels at progressive disclosure, organizing a complex multi-language, multi-platform topic into a navigable hierarchy. Its main weaknesses are the lack of executable code examples in the main file (nearly all implementation is deferred to references), repeated listings of the same reference files inflating token count, and missing validation/feedback loops in the workflow. The skill reads more like a project management outline than a hands-on development guide.
Suggestions
Add at least one minimal but complete, executable MCP server example (e.g., a 15-line TypeScript or Python hello-world MCP server) directly in the main skill to improve actionability.
Add explicit validation checkpoints with feedback loops in Phase 3, e.g., 'If build fails: check error output → fix → rebuild. If Inspector test fails: verify tool schemas → check error messages → re-test.'
Consolidate the reference file listings—they appear in Phase 1, Phase 2, and again in the Reference Files section. List them once in the Reference Files section and use brief inline links elsewhere to reduce token waste.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill has some unnecessary verbosity—particularly the repeated reference file listings (the same guides are linked 3-4 times throughout), and some sections explain concepts Claude already knows (e.g., what async/await is for, DRY principle). However, it's not egregiously padded and most content serves a purpose. | 2 / 3 |
Actionability | The skill provides structured guidance and some concrete commands (e.g., `npm run build`, `npx @modelcontextprotocol/inspector`, `python -m py_compile`), but lacks executable code examples for the core task of building an MCP server. Most implementation details are deferred to reference files, leaving the main skill with abstract checklists rather than copy-paste-ready code. | 2 / 3 |
Workflow Clarity | The four-phase workflow is clearly sequenced and logically organized, but lacks explicit validation checkpoints and feedback loops. Phase 3 mentions testing but doesn't define what success looks like or what to do when tests fail. There's no 'validate -> fix -> retry' loop despite the complexity of the multi-phase process. | 2 / 3 |
Progressive Disclosure | Excellent progressive disclosure with a clear overview in the main file and well-signaled, one-level-deep references to language-specific guides, best practices, Microsoft patterns, and evaluation guides. References are clearly labeled with emojis and descriptive summaries of what each file contains. | 3 / 3 |
Total | 9 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- microsoft/agent-skills
- Commit
265cb08
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.