Content
85%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 exceptionally actionable and safe for destructive operations, with concrete tool calls, checklists, validation checkpoints, and error-recovery feedback loops throughout. Its weaknesses are length that could be trimmed in places and a complete absence of progressive disclosure: the detailed error-recovery and rename-semantics material should live in referenced files rather than inline.
Suggestions
Move the 17-row error-recovery table and the deep rename-semantics paragraphs (plan_token lifecycle, retention budgets, provider coverage rules) into a references/ file (e.g., references/rename-errors.md), keeping SKILL.md to the bind-preview-apply-verify workflow with one-line pointers per error class.
Trim inline detail that the core workflow does not need at decision time, such as the eviction arithmetic ('16 plans or 64 MiB') and the extended discussion of applying through a read-only server, summarizing these in one line each.
Split the checklists for Extract Module and Split Function/Service into a references/checklists.md (or a scripts/ helper) so SKILL.md's inline checklist coverage scales without growing the always-loaded context.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Almost every token is GitNexus-specific knowledge Claude cannot know (plan_token semantics, 15-minute expiry, 16-plan/64 MiB eviction, GITNEXUS_MCP_READ_ONLY), with no concept-explanation padding — but a few dense passages (eviction budget arithmetic, extended read-only server discussion) exceed what the core workflow needs and could be trimmed. | 4 / 5 |
Actionability | Fully executable call syntax with exact parameters (rename({symbol_name: 'validateUser', ...}), dry_run, plan_token), a concrete cypher query, a worked end-to-end example, and per-error next steps cover all common cases copy-paste ready. | 5 / 5 |
Workflow Clarity | The destructive-write workflow has explicit validation checkpoints (preview → confirm bound paths → apply with token → detect_changes → run tests) and genuine feedback loops ('Re-analyze... then preview again', 'never blindly retry the apply call'), plus per-task checklists — satisfying the destructive-operation validation requirement. | 5 / 5 |
Progressive Disclosure | No bundle files exist, so everything — including a 17-row error-recovery table and multi-paragraph rename-semantics details that clearly belong in a separate reference file — is inlined in a single ~225-line SKILL.md. Section structure is good and navigable, but there is no progressive disclosure at all. | 3 / 5 |
Total | 17 / 20 Passed |