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) or Node/TypeScript (MCP SDK).
77
66%
Does it follow best practices?
Impact
97%
2.55xAverage score across 3 eval scenarios
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/all-skills/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 framework-specific triggers. Its main weakness is that it could be more specific about the concrete actions it covers (e.g., defining tools, configuring transports, handling authentication) rather than staying at the high-level 'creating servers' framing.
Suggestions
Add specific concrete actions the skill covers, e.g., 'defining tools and resources, configuring transports, structuring server code, handling authentication' to improve specificity.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | 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 doesn't list multiple specific concrete actions like defining tools, handling authentication, setting up transport layers, etc. | 2 / 3 |
Completeness | Clearly answers both 'what' (creating high-quality MCP servers that enable LLMs to interact with external services through well-designed tools) and 'when' (explicitly states 'Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK)'). | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'MCP', 'Model Context Protocol', 'MCP servers', 'FastMCP', 'MCP SDK', 'external APIs', 'Python', 'Node', 'TypeScript', 'tools'. These cover the main variations a user building MCP servers would naturally mention. | 3 / 3 |
Distinctiveness Conflict Risk | MCP server development is a very specific niche with distinct trigger terms (MCP, Model Context Protocol, FastMCP, MCP SDK). Unlikely to conflict with general coding skills or other integration-related skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
42%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill has excellent structure and progressive disclosure, appropriately splitting content across reference files with clear navigation. However, it is significantly too verbose, repeating information multiple times and explaining concepts Claude already knows. The lack of executable code examples is a notable gap for a development guide—the skill describes what to do but rarely shows how with concrete, copy-paste ready code.
Suggestions
Cut at least 50% of the content by removing generic software engineering advice (DRY, error handling concepts, what async/await is) and eliminating the repeated reference file listings—list them once at the top or bottom, not throughout each phase.
Add concrete, executable code examples showing minimal MCP server setup in both Python (FastMCP @mcp.tool decorator) and TypeScript (server.registerTool), rather than just describing what to do.
Add explicit validation checkpoints with commands, e.g., after implementation: 'Run `python -m py_compile server.py` → if errors, fix and recompile → only proceed when clean'.
Remove explanatory text like 'Before diving into implementation, understand how to design tools for AI agents' and the detailed descriptions of what each reference file contains—just link them with a one-line summary.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose, explaining many concepts Claude already knows (what MCP is, what error handling means, what DRY principle is, how async/await works). There's extensive repetition—reference files are listed multiple times throughout the document and again in a dedicated section. Many instructions are generic software engineering advice rather than MCP-specific knowledge Claude wouldn't already have. | 1 / 3 |
Actionability | The skill provides some concrete guidance like specific URLs to fetch, XML format for evaluations, and tool annotation fields. However, it lacks executable code examples—there are no actual code snippets showing how to register a tool, create a server, or implement any of the described patterns. Most guidance is procedural description rather than copy-paste ready implementation. | 2 / 3 |
Workflow Clarity | The four-phase workflow is clearly sequenced and logically organized. However, validation checkpoints are weak—the testing section (3.2) warns about hanging processes but doesn't provide a clear validate-fix-retry loop. The 'Quality Checklist' is deferred to external files rather than providing inline checkpoints. Missing explicit feedback loops for error recovery during implementation. | 2 / 3 |
Progressive Disclosure | The skill effectively uses progressive disclosure with clear references to external files (Python guide, TypeScript guide, evaluation guide, best practices) that are one level deep and well-signaled with emoji markers and descriptive summaries of what each file contains. The main document serves as an overview with appropriate pointers to detailed materials. | 3 / 3 |
Total | 8 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- davepoon/buildwithclaude
- Commit
7cc63f3
- 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.