Content
52%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is comprehensive and well-structured in terms of workflow design — the three modes, the interactive fix-loop with its resume contract, and the quality gates are thoughtfully designed. However, it suffers significantly from being a monolithic document that inlines content explicitly acknowledged as mirrors of other files (invariants, caps tables). The result is a ~500+ line skill that consumes excessive context window for what should be an overview with references to detailed specifications.
Suggestions
Extract the full invariants reference (N-1 through S-7) into a separate file like `references/invariants-summary.md` and reference it — the skill already acknowledges `graph-invariants.md` is the source of truth, so duplicating it here wastes tokens.
Remove the mirrored Caps table entirely and just reference `skills/project-conventions/SKILL.md#canonical-specs` with a one-line note that the script holds the same values in `ARTIFACT_CAPS`.
Move the Mode C fix-loop details (the 6-phase structure, the per-finding-type dispatch table, trust mode rules) into a separate `MODE-C-REFERENCE.md` file, keeping only a concise summary in the main skill.
Remove explanatory text that Claude doesn't need — e.g., 'Nodes are artifacts... Edges are references...' and 'The check answers one question: is the graph complete and consistent' — and jump straight to the modes and invocation.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | At ~500+ lines, this skill is extremely verbose. It exhaustively enumerates every invariant (N-1 through N-21, E-1 through E-14, A-1, S-1 through S-7), every finding type with fix options, every Mode C interaction detail, and mirrors cap tables from other files. Much of this detail (e.g., the full invariant reference, the caps table that's explicitly a mirror, the detailed per-finding-type fix dispatch table) should live in separate reference files. Claude doesn't need explanations of what dead links or orphan nodes are. | 2 / 5 |
Actionability | The skill provides concrete invocation commands, specific file paths, tool references, grep patterns, and detailed output format templates. The workflow steps are specific with file path patterns and field names. However, much of the guidance is structural/declarative rather than executable code — the actual Mode A logic lives in `tools/consistency-check.py` which isn't shown, and the Mode B/C orchestration instructions are detailed but procedural prose rather than executable snippets. | 4 / 5 |
Workflow Clarity | The three modes are clearly defined with distinct triggers. The Mode C interactive fix-loop has an explicit 6-phase structure with validation (re-check in phase 4) and error recovery (resume contract, skip options). The main workflow (steps 1-6) is well-sequenced. Minor gap: Mode A's 8 checks don't have explicit ordering or dependency information, and the relationship between the pre-commit hook flow and the manual invocation flow could be clearer. | 4 / 5 |
Progressive Disclosure | This is a monolithic wall of content that badly needs decomposition. The invariants reference section alone is ~100 lines and is explicitly stated to be a copy from `graph-invariants.md`. The caps table is a mirror of another file. The Mode C fix-loop details, the viewer tool documentation, and the invariant definitions should all be in separate referenced files. The skill mentions several external files but inlines their content anyway. | 2 / 5 |
Total | 12 / 20 Passed |