mcp-schema-enum-regression

Keep generated MCP schemas strict-client compatible by avoiding nullable enum signatures.

Quality

52%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.squad/skills/mcp-schema-enum-regression/SKILL.md

Quality

Discovery

40%

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 targets a very specific technical niche (MCP schema nullable enum handling), which gives it strong distinctiveness. However, it lacks a 'Use when...' clause, making it unclear when Claude should select this skill. The description is also quite terse, naming only one specific action without broader context about what the skill covers.

Suggestions

Add a 'Use when...' clause, e.g., 'Use when generating or reviewing MCP tool definitions, server schemas, or when the user mentions MCP compatibility issues.'

Expand the 'what' to cover more concrete actions, e.g., 'Validates and corrects MCP tool schemas to ensure strict-client compatibility by replacing nullable enums with oneOf patterns, fixing optional field declarations, and ensuring JSON Schema compliance.'

Include natural trigger terms users might say, such as 'MCP tool definition', 'MCP server', 'schema validation', 'JSON Schema', or 'enum null'.

Dimension	Reasoning	Score
Specificity	The description names a specific domain (MCP schemas) and a concrete action (avoiding nullable enum signatures), but it only describes one narrow action rather than listing multiple specific capabilities.	2 / 3
Completeness	The description answers 'what' (avoid nullable enum signatures in MCP schemas) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and the 'what' itself is also quite thin, warranting a 1.	1 / 3
Trigger Term Quality	Includes some relevant technical keywords like 'MCP schemas', 'nullable enum', and 'strict-client compatible', but these are fairly jargon-heavy. Users might say 'MCP tool definition' or 'schema validation' which are missing. The term 'strict-client compatible' is niche but relevant for the target audience.	2 / 3
Distinctiveness Conflict Risk	This is a very narrow, specific niche — MCP schema generation with nullable enum constraints. It is highly unlikely to conflict with other skills due to its precise technical focus.	3 / 3
	Total	8 / 12 Passed

Implementation

64%

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

This is a concise, domain-specific skill that efficiently communicates the core problem (nullable enums in MCP schemas) and the general approach. Its main weakness is the lack of executable code examples showing the actual fix pattern and the absence of an explicit validation workflow (test → fix → re-test). The anti-patterns section adds good guardrails.

Suggestions

Add a concrete code snippet showing the before/after of a nullable enum parameter being converted to an optional string parameter in the generator.

Include an explicit numbered workflow: 1) Run ListToolsAsync validation, 2) Identify nullable enum properties, 3) Apply the string-transport fix, 4) Re-run validation to confirm no enum arrays contain sentinels.

Show a minimal example of the recursive schema check that validates enum arrays don't contain null/empty sentinels.

Dimension	Reasoning	Score
Conciseness	Every bullet point conveys domain-specific knowledge that Claude wouldn't inherently know about MCP schema compatibility. No unnecessary explanations of what MCP is or how enums work in general.	3 / 3
Actionability	Provides specific patterns and anti-patterns with file path references, but lacks executable code examples. The guidance is concrete in concept (e.g., 'recurse every schema node that contains an enum array') but doesn't show actual code for implementing the fix or the validation check.	2 / 3
Workflow Clarity	The patterns section implies a sequence (test with ListToolsAsync, identify hazard points, fix by emitting optional strings) but doesn't present it as an explicit ordered workflow with validation checkpoints. For a task involving generated code modification, a clearer validate-fix-revalidate loop would be valuable.	2 / 3
Progressive Disclosure	References specific files as examples which is good for navigation, but the file references are just paths without links or explanation of what to look for in each. The skill is short enough that external references aren't strictly needed, but the example file references could be better signaled.	2 / 3
	Total	9 / 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
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: sbroenne/mcp-server-excel
Commit: 468809e

Reviewed: 2 days 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.