mcp-builder

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

Quality

57%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

57%

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

The body is a compact, well-structured reference of MCP server-building topics that stays token-efficient, but it stops at principle-level descriptions and concrete field lists without executable code or a sequenced build-and-validate workflow. Organization and disclosure are strong; actionability and workflow sequencing are the main gaps.

Suggestions

Add at least one executable minimal example showing tool registration and input schema definition with the @modelcontextprotocol/sdk (TypeScript) and FastMCP (Python) SDKs.

Provide a sequenced build workflow with an explicit validation checkpoint (e.g. run the MCP inspector / contract tests before declaring the server ready).

Move the '2025-06-18' spec version into a dedicated 'Current spec features' note framing rather than inline in the transport and features sections to avoid time-sensitive date repetition.

Dimension	Reasoning	Score
Conciseness	The body is mostly lean tables and bullets that assume MCP familiarity, but it states the time-sensitive spec version '2025-06-18' in two places outside any deprecated/old-patterns section and includes a brief 'What is MCP?' explainer, which the guidelines penalize.	2 / 3
Actionability	Provides concrete specifics (project structure, SDK package names, transport types, URI patterns, config fields) but no executable code showing how to actually register a tool or define an outputSchema, so the guidance is instructive-incomplete rather than copy-paste ready.	2 / 3
Workflow Clarity	Content is well organized into numbered topic sections and ends with a best-practices checklist, but there is no sequenced build workflow (scaffold -> define tools -> wire transport -> validate -> test) with explicit validation checkpoints for a server-building task.	2 / 3
Progressive Disclosure	A single well-organized SKILL.md with clear numbered sections, no nested/deep references, and no bundle files referenced; the overview-level table content is appropriately inline with no broken references.	3 / 3
	Total	9 / 12 Passed

Description

57%

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 clear niche and some relevant sub-areas but stays at the topic-label level rather than listing concrete actions, and it omits an explicit 'Use when...' trigger in the description field itself. It is distinguishable from other skills but reads more as a category label than an action-oriented trigger.

Suggestions

Replace topic labels with concrete actions, e.g. 'Scaffold MCP servers, design tool input schemas, and implement resource URI patterns' instead of 'Tool design, resource patterns, best practices'.

Add an explicit trigger clause to the description, e.g. 'Use when building or extending MCP (Model Context Protocol) servers, designing MCP tools, or implementing MCP resource patterns.'

Drop the generic 'best practices' phrase or replace it with the specific practices the skill covers.

Dimension	Reasoning	Score
Specificity	Names the domain ('MCP (Model Context Protocol) server building principles') and several sub-areas ('Tool design, resource patterns, best practices'), but these are topic labels rather than the multiple concrete actions the top anchor requires, and 'best practices' is generic fluff.	2 / 3
Completeness	The description field answers 'what' but contains no 'Use when...' clause or equivalent explicit trigger; per the judging guidelines a missing trigger clause caps completeness at 2 (the separate when_to_use frontmatter field is outside the evaluated description text).	2 / 3
Trigger Term Quality	Includes natural terms a user might say ('MCP server', 'MCP tools', 'resource patterns'), but coverage of common variations is limited and there are no broader phrasings like 'build an MCP server' or 'MCP resources'.	2 / 3
Distinctiveness Conflict Risk	'MCP server building' is a clear, narrow niche with distinct triggers unlikely to fire for unrelated skills, matching the top anchor's 'clear niche with distinct triggers'.	3 / 3
	Total	9 / 12 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	14 / 16 Passed

Repository: vudovn/ag-kit
Path: .agents/skills/mcp-builder/SKILL.md
Commit: 04514f0

Reviewed: about 12 hours 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.