Content
63%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 action-oriented with concrete commands and a reasonable workflow structure, but it carries moderate redundancy between sections and references bundle files that are absent, weakening both conciseness and progressive disclosure.
Suggestions
Ship the referenced bundle files (references/*.md, scripts/*.py, README.md) or remove the dead links so navigation from SKILL.md actually resolves.
Collapse the redundant Overview/Core Capabilities/When to Use sections so the description is not restated and capability bullets do not duplicate the workflow steps.
Add an explicit validate->fix->retry feedback loop in the scaffold workflow (e.g. run mcp_validator.py, fix reported issues, re-run until clean) to reach the workflow_clarity top anchor.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient with concrete commands, but the Overview restates the frontmatter description and the "Core Capabilities" bullets overlap with the "Key Workflows" steps, so several lines could be tightened. Not a 4 because the redundancy is more than minor; not a 2 because there is no padded concept explanation. | 3 / 5 |
Actionability | Provides copy-paste-ready bash commands with full arguments (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 and a validator command. Not a 5 because no example output/manifest is shown and some runtime logic is left undescribed. | 4 / 5 |
Workflow Clarity | Workflows are clearly sequenced (numbered steps for scaffold generation) with a dedicated validate step ("Run validator before integration tests", strict-mode non-zero exit). Not a 5 because there is no explicit validate->fix->retry feedback loop inline in the scaffold workflow; not a 3 because checkpoints are present and the operation is generative rather than destructive. | 4 / 5 |
Progressive Disclosure | The body is well structured with a clear overview and a Reference Material section listing one-level-deep links with annotations, but the referenced bundle (references/*.md, scripts/*.py, README.md) does not exist on disk, so the signaled references are non-functional and navigation is incomplete. Not a 4 because dead references are more than a minor organization gap; not a 2 because structure and signaling in SKILL.md itself are good and content is appropriately split rather than inlined. | 3 / 5 |
Total | 14 / 20 Passed |