Content
73%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 an exceptionally actionable, well-gated pipeline runbook with real validation and recovery loops, and its use of one-level-deep, conditionally-loaded references is disciplined. Its main cost is token weight: systematic redundancy and bug-history commentary make it noticeably verbose for an always-loaded SKILL.md.
Suggestions
State the no-API-key rule once in Step 3 as a single blockquote instead of three separate ones, and drop the repeated "INPUT_PATH is read from graphify-out/.graphify_root; there is no path to substitute" lines in favor of one note near Step 1.
Trim issue-tracker archaeology (#2843, #1392, #2225, #1939, #479) to one-line rationale comments — keep the instruction, cut the multi-sentence bug narrative a maintainer would read in the repo, not the skill.
Move the Step B0–B3.5 cache/merge choreography into a references/extraction-cache.md and keep only the dispatch decision points inline, slimming the always-loaded body.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~800-line body has several padded or redundant passages: the "never ask for an API key" rule is stated in three separate blockquotes in Step 3, "INPUT_PATH is read from graphify-out/.graphify_root; there is no path to substitute" is repeated three times, and long issue-tracker archaeology (#2843, #1392, #2225, #1939, #479) explains library internals far beyond what the agent needs to act. This matches "noticeably verbose; several unnecessary explanations or padded sections"; it is not a 3 because the redundancy is systematic rather than incidental. | 2 / 5 |
Actionability | Fully executable bash/Python blocks with exact commands, and every placeholder (IS_DIRECTED, IS_FORCE, LABELS_DICT, SPEC_PATH, INPUT_PATH heredoc) has explicit substitution instructions plus fallback paths (interpreter detection, NetworkX query fallback, chunk-failure handling). Copy-paste ready and covers the common cases, matching the top anchor. | 5 / 5 |
Workflow Clarity | Steps 0–9 are clearly sequenced with explicit validation checkpoints for this batch operation: empty-graph guard, the #479 shrink-guard, the Step 4.5 read-only health check, Step B3.5 coverage verification against real file lengths, and a stop rule when more than half the chunks fail — plus feedback loops (partially-read files cached as partial and retried on --update). This matches the anchor with explicit validation steps and error-recovery loops. | 5 / 5 |
Progressive Disclosure | All 8 reference files exist on disk and are well-signaled, one level deep, and conditionally loaded at the right points (e.g. "Load it only here, only when at least one chunk holds a doc, paper, or image"); opt-in flows (transcribe, exports, query, add-watch, hooks, update, merge) are properly split out. It falls short of a 5 because the main body is a ~600-line runbook rather than an overview — the Step B0–B3.5 cache choreography is dense enough to belong in its own reference. | 4 / 5 |
Total | 16 / 20 Passed |