Content
56%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 delivers a well-structured, largely concrete methodology for workspace analysis with clear phase sequencing and validation mechanisms, but it is severely bloated with illustrative sample artifacts and its core commands depend on specification files that are missing from the bundle. Splitting reference material into actual bundle files and tightening the inline examples would resolve its main weaknesses.
Suggestions
Create the referenced bundle files (commands/analyze-workspace.md, commands/sync-contracts.md) or inline their actual specifications, since the skill's primary workflows currently depend on files that do not exist.
Move the full worked artifact examples (TOPOLOGY.md, CONTRACTS.md, DEPENDENCY_GRAPH.md, CROSS_REPO_INDEX.md formats) and CI/CD integration examples into a references/ directory, keeping only the format skeleton and purpose summary in SKILL.md.
Trim the ASCII-art diagrams and replace the fictional 47-endpoint worked example with a compact one-module example to cut hundreds of tokens without losing guidance value.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~970-line body is noticeably verbose: multiple large ASCII-art boxes, fully worked fictional artifacts (a complete 47-endpoint CONTRACTS.md, TOPOLOGY.md, and DEPENDENCY_GRAPH.md samples with invented module details), and a full GitHub Actions YAML that could each be condensed or moved out of context. It assumes little of Claude's competence and much of the content is illustrative padding rather than instruction. | 2 / 5 |
Actionability | There is genuinely concrete guidance (detection commands, grep patterns, detection tables, hook scripts), but the two central commands /analyze-workspace and /sync-contracts defer to 'commands/analyze-workspace.md' and 'commands/sync-contracts.md' files that do not exist in the bundle, leaving the core workflows under-specified. | 3 / 5 |
Workflow Clarity | The four analysis phases are clearly sequenced with time estimates and a discovery checklist, and validation appears via contract validation-status tables, freshness tiers, CI gates, and a troubleshooting section. However, there is no explicit per-phase validate-and-fix loop, so checkpoints are present but not uniformly explicit. | 4 / 5 |
Progressive Disclosure | Section structure is clear, but the skill is monolithic: full artifact-format specifications, token-budget diagrams, and CI/CD examples that belong in separate reference files are inlined at length, and the only references given (commands/analyze-workspace.md, commands/sync-contracts.md, plus existing-repo.md and session-management.md) point to files absent from the bundle. | 3 / 5 |
Total | 12 / 20 Passed |