Content
77%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 an exceptionally actionable, well-gated multi-phase workflow with strong validation and error-recovery loops throughout. Its main weaknesses are token efficiency and organization: a 931-line monolith that inlines schema references and deep validation-design prose that belong in one-level-deep reference files.
Suggestions
Move the KnowledgeGraph schema reference (node/edge type tables and edge weight conventions) and the symbol-loss validation design details into a separate reference file (e.g., references/graph-schema.md, references/symbol-loss-validation.md) linked from the relevant phases, cutting the main body substantially.
Trim the dense Phase 2 incremental-validation prose (paragraphs on source identity, scope indices, and parser adapters) down to the operational rules the executing agent needs, leaving the rationale and cross-product test matrix in the already-referenced docs/incremental/symbol-loss-validation.md.
Extract the inline Node validation script to a bundled scripts/ file invoked by path, matching the pattern used for the other bundled helpers.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The 931-line body is mostly operational (commands, gates, templates) rather than padded with concepts Claude already knows, but it includes dense internal-design prose (e.g., the Phase 2 symbol-loss sections: "The strict parser emits versioned, scoped symbol evidence...", "Source identity is (file path, symbol kind, owner, name)") and an inlined 13-type/26-type schema reference that could be tightened or moved to a reference file. This fits "mostly efficient but could be tightened" rather than the minor-trim profile of score 4. | 3 / 5 |
Actionability | Guidance is fully executable: exact bash invocations with arguments (e.g., "node \"<SKILL_DIR>/prepare-incremental.mjs\" \"$PROJECT_ROOT\" \"$LAST_COMMIT_HASH\""), a complete copy-paste-ready Node validation script ("Write the following Node.js script to $UA_DIR/tmp/ua-inline-validate.cjs"), filled dispatch-prompt templates, and concrete decision tables covering the common full/incremental/review paths. | 5 / 5 |
Workflow Clarity | Phases 0 through 7 are explicitly sequenced with numbered steps, decision tables for every branch (full vs. incremental vs. review-only), gate checks ("verify each batchIndex ... has a corresponding batch-<batchIndex>.json ... on disk before proceeding"), explicit feedback loops (subagent retry once, one targeted symbol-repair retry, re-run validation after fixes), and hard STOP conditions ("If the script exits non-zero ... abort Phase 7 ... Do NOT proceed to step 3"). Validation is present for batch and destructive operations, so no cap applies. | 5 / 5 |
Progressive Disclosure | Structure is good — clearly delineated phase sections with signaling of bundled scripts ("located next to this SKILL.md file"), plus references to agents/, languages/, frameworks/, and locales/ files. However, no bundle files are provided alongside this SKILL.md, and substantial content that clearly belongs in separate reference files is inlined: the KnowledgeGraph schema tables ("Node Types (13 total)", "Edge Types (26 total)", edge weights), the multi-paragraph symbol-loss validation design notes, and the full inline validator script. This sits between the score-3 and score-4 anchors; the heavy inlined reference material keeps it at 3. | 3 / 5 |
Total | 16 / 20 Passed |