Content
60%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The body is well organized with concrete, fully specified commands and a clear workflow sequence, but it is undermined by the missing bundle: all referenced scripts and reference guides are absent, making the commands unexecutable and the progressive-disclosure structure hollow. Redundancy between the Overview, Core Capabilities, and When to Use sections is a minor additional cost.
Suggestions
Ship the referenced bundle files (references/production-hardening-guide.md, references/openapi-extraction-guide.md, references/python-server-template.md, references/typescript-server-template.md, references/validation-checklist.md, and scripts/openapi_to_mcp.py, scripts/mcp_validator.py) or remove the dead links and inline the essential guidance, so no navigation path leads to a missing file.
Add an explicit validation feedback loop to the scaffold workflow: after running mcp_validator.py --strict, instruct to fix reported errors (duplicate names, missing descriptions, empty required fields) and re-run until it exits clean before proceeding to integration tests.
Consolidate the overlapping Overview, Core Capabilities, and When to Use sections — which each restate the frontmatter description — into one tighter section to reclaim token budget.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is efficient with concrete commands and no re-explanation of known concepts, but the Overview, Core Capabilities, and When to Use sections each restate the frontmatter description's content ("Use this skill to design and ship production-ready MCP servers from API contracts instead of hand-written one-off tool wrappers"), a minor redundancy that could be trimmed to fit the anchor for efficient content with minor over-explanation. | 4 / 5 |
Actionability | The bash commands are concrete and fully flagged (e.g., "python3 scripts/openapi_to_mcp.py --input openapi.json --server-name billing-mcp --language python --output-dir ./out --format text", plus a stdin variant), but the scripts they invoke — scripts/openapi_to_mcp.py and scripts/mcp_validator.py — do not exist in the bundle, so the guidance is incomplete rather than executable, matching the anchor for concrete guidance with missing key details. | 3 / 5 |
Workflow Clarity | The four workflows are clearly sequenced and workflow 2 is an explicit validation checkpoint ("Run validator before integration tests" with a strict-mode command that "Returns non-zero exit in strict mode when errors exist"). It falls short of the top anchor because no explicit fix-and-revalidate feedback loop is described — error recovery is only implied. | 4 / 5 |
Progressive Disclosure | Scored against the actual bundle structure per the rubric guideline: the body is well-signaled and one level deep in form, but every referenced file — references/production-hardening-guide.md, references/openapi-extraction-guide.md, references/python-server-template.md, references/typescript-server-template.md, references/validation-checklist.md, scripts/openapi_to_mcp.py, scripts/mcp_validator.py, and README.md — is missing from the bundle. The overview-to-details structure is a promise with no substance; navigation leads to nonexistent files, which sits below the anchor for references that are present but merely unclear. | 2 / 5 |
Total | 13 / 20 Passed |