Content
75%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 a strong, highly actionable reference: exact tool-call shapes, parameter bounds, and real Cypher make it copy-paste ready, and the entry workflow carries an explicit staleness checkpoint. It is held back from the top band by verbosity in the staleness section (three overlapping JSONC examples) and inlined reference material that could be split out.
Suggestions
Collapse the three staleness JSONC examples (current/behind/diverged) into one compact table or a single annotated example to cut redundancy and raise conciseness.
Move the detailed pagination walkthrough and full staleness semantics into a separate reference file (e.g., `references/staleness.md`) and link to it, keeping SKILL.md as a lean overview.
Tighten or merge the duplicated staleness guidance between the "Always Start Here" callout and the "Inline staleness signal" subsection to avoid stating the same rule twice.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is information-dense and largely assumes Claude's competence (tool tables, field shapes, status semantics), but the staleness section runs long with three near-redundant JSONC examples and extended prose explaining edge cases that could be tightened, putting it between the 3 and 4 anchors; the repetition of the same guidance across intro and the inline-staleness subsection pulls it toward 3. | 3 / 5 |
Actionability | It provides concrete, executable guidance throughout — exact tool call shapes (e.g., `trace { from: "validateUser", to: "executeQuery" }`, `list_repos { offset: 50 }`), parameter defaults/maxes, real Cypher, and runnable CLI (`node .gitnexus/run.cjs analyze`) — covering common cases copy-paste ready, matching the fully-executable anchor. | 5 / 5 |
Workflow Clarity | The "Always Start Here" section gives a clear numbered sequence with a staleness checkpoint (read `staleness.status` before using answers, re-analyze only for behind/diverged), but the document is reference-oriented rather than a single destructive/batch workflow, so validation checkpoints exist for the risky read path but are not as tightly looped as a validate->fix->retry cycle; this fits just above the 3 anchor but below the explicit-feedback-loop 5. | 4 / 5 |
Progressive Disclosure | Structure is good with well-organized sections (Always Start Here, Skills, Tools, Resources, Graph Schema) and one-level-deep references to other skill files (e.g., `gitnexus-pdg-query` skill, `gitnexus://repo/{name}/schema`); however, no bundle files exist and several large reference blocks (full staleness JSONC examples, pagination walkthrough) are inlined where they could live in a separate reference, so it sits at 4 rather than 5. | 4 / 5 |
Total | 16 / 20 Passed |