mcp-builder

MCP (Model Context Protocol) server building principles. Tool design, resource patterns, best practices.

Quality

27%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Fix and improve this skill with Tessl

tessl review fix ./.agent/skills/mcp-builder/SKILL.md

Quality

Content

22%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill reads more like a reference card or cheat sheet than actionable guidance for building MCP servers. While the table-based organization is clean, the content lacks executable code examples, concrete implementation steps, and clear workflows. Claude would struggle to actually build an MCP server from this guidance alone.

Suggestions

Add executable TypeScript code examples showing minimal server setup, tool registration, and resource handling - not just descriptions of what they should contain

Include a step-by-step workflow for creating a new MCP server: init project → define tools → register handlers → configure transport → test → deploy

Remove the 'What is MCP?' and basic concept explanations - Claude knows these; focus on implementation specifics

Add concrete input/output examples for tools showing actual JSON schemas and response formats

Dimension	Reasoning	Score
Conciseness	The content is reasonably efficient with good use of tables, but includes some explanatory content Claude already knows (e.g., 'What is MCP?' section, basic definitions). Could be tighter by removing conceptual explanations.	2 / 3
Actionability	Almost entirely descriptive with no executable code examples. Tables describe concepts but don't show how to implement them. Missing concrete code for server setup, tool registration, or resource handling.	1 / 3
Workflow Clarity	No clear workflow for building an MCP server. Content is organized as reference tables but lacks step-by-step guidance, validation checkpoints, or sequenced instructions for creating a working server.	1 / 3
Progressive Disclosure	Content is well-organized with clear sections and tables, but everything is inline in one file. No references to external files for detailed implementation guides, API references, or examples that would benefit from separation.	2 / 3
	Total	6 / 12 Passed

Description

32%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description identifies a specific technical domain (MCP servers) but relies on abstract category labels rather than concrete actions. It critically lacks any 'Use when...' guidance, making it difficult for Claude to know when to select this skill. The trigger terms are too technical and miss natural user language variations.

Suggestions

Add an explicit 'Use when...' clause with trigger phrases like 'building MCP servers', 'implementing Model Context Protocol', 'creating MCP tools', or 'server-side protocol implementation'.

Replace abstract terms like 'best practices' with concrete actions such as 'implement tool handlers', 'define resource schemas', 'structure server responses', or 'handle protocol messages'.

Include natural user language variations like 'MCP server', 'protocol server', 'tool server', 'MCP integration' to improve trigger term coverage.

Dimension	Reasoning	Score
Specificity	Names the domain (MCP server building) and mentions some areas (tool design, resource patterns, best practices), but these are high-level categories rather than concrete actions like 'create handlers' or 'implement tool schemas'.	2 / 3
Completeness	Describes what at a high level but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per rubric guidelines, missing explicit trigger guidance caps this at 2, but the 'what' is also weak.	1 / 3
Trigger Term Quality	Includes 'MCP' and 'Model Context Protocol' which are relevant technical terms, but misses natural user phrases like 'build an MCP server', 'create tools', 'server implementation', or 'protocol integration'.	2 / 3
Distinctiveness Conflict Risk	'MCP' and 'Model Context Protocol' provide some distinctiveness, but 'tool design' and 'best practices' are generic enough to potentially overlap with other development or architecture skills.	2 / 3
	Total	7 / 12 Passed

Validation

90%

Warnings & errors only

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
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning

	Total	10 / 11 Passed

Repository: lchenrique/politron-ide
Commit: 7114206

Reviewed: 5 months ago

Table of Contents

Discovery Implementation Validation

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.