Content
82%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.
A highly actionable, well-structured CLI reference: every command is executable, defaults and failure modes are documented, and the main analyze workflow includes an explicit verification step. Weaknesses are minor — the destructive `clean` operations lack taught validation steps, and version-specific troubleshooting detail is inlined rather than split into a reference.
Suggestions
Add a validation step around the destructive/batch `clean` and `clean --all` operations (e.g., run `node .gitnexus/run.cjs status` first to confirm the target index, and again after to verify removal), since these currently rely only on the CLI's built-in confirmation prompt.
Move the npm 11.x / pnpm workaround blockquote into a one-level-deep troubleshooting reference (e.g., references/troubleshooting.md) to keep the overview lean and isolate time-sensitive version details.
Tighten the PostToolUse-hook rationale ("to avoid blocking the agent for up to 120s and risking KuzuDB corruption on timeout") to a shorter clause — the why is useful but can be trimmed without losing the operative guidance.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is a dense, efficient command reference with zero padding and no explanations of concepts Claude already knows. Not 5 because the npm 11.x crash workaround blockquote (version-specific detail, issue link, long pnpm flag string) is time-sensitive material that could be trimmed or relocated to a troubleshooting reference. | 4 / 5 |
Actionability | Every command is a copy-paste-ready `node .gitnexus/run.cjs <command>` invocation with complete flag tables, explicit defaults (model, concurrency), config file paths, and a concrete regeneration path when the runner is missing. All five common cases are covered with executable guidance and no gaps. | 5 / 5 |
Workflow Clarity | Sequencing is clear: "Run from the project root", explicit "When to run" triggers including the staleness-detection hook, an explicit post-index verification step ("Read gitnexus://repo/{name}/context to verify the index loaded"), and error-recovery guidance in Troubleshooting. Not 5 because the destructive `clean` and batch `clean --all` operations rely on the CLI's built-in confirmation prompt without teaching any validation of their own (e.g., a `status` check before/after). | 4 / 5 |
Progressive Disclosure | The skill has no bundle files and is well-organized into per-command sections with flag tables, easy to navigate at overview level. Not 5 because at ~83 lines it exceeds the under-50-line exception, and the environment-specific npm/pnpm workaround blockquote is inline content that would sit better in a one-level-deep troubleshooting reference. | 4 / 5 |
Total | 17 / 20 Passed |