Content
86%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 tight, command-driven skill body: the engine does retrieval deterministically while the skill instructs only the judgment work, with verified CLI commands and a concrete deliverable shape. The main gaps are minor redundancy in the intro and the absence of explicit failure-mode checkpoints (empty digest, indexing errors) in the flow.
Suggestions
Trim the duplicated lifecycle description: the intro's "(new / open / recently closed)" preview repeats the full status definitions given in 'How the engine splits the work' — keep only the latter.
Add a brief failure-mode note to step 2, e.g. 'if the digest is empty, confirm the DB was indexed against the right --projects/--scan scope before concluding no work happened' — this adds the missing validation checkpoint for the batch indexing step.
Mention that --db defaults to ~/.specstory/workthreads.db so the index and threads commands are copy-paste runnable as-is for the common single-machine case.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and assumes competence ("you do the synthesis", no explanation of what transcripts or threads are conceptually), but the lifecycle is stated twice ("lines of work and their lifecycle (new / open / recently closed)" in the intro and again as full definitions in 'How the engine splits the work'), and the intro paragraph partially restates the frontmatter description. Not 5: those duplications could be trimmed; not 3: there is no genuinely unnecessary explanation or padding. | 4 / 5 |
Actionability | Gives exact, verified commands — "node "${CLAUDE_SKILL_DIR}/scripts/workthreads.mjs" index --projects <parent-of-repos> --db <db>", "threads --db <db> --days 7" and "--days 7 --json" — plus a concrete output shape (sections a-e), a dated file convention, and "threads --out <file>". The flags match the actual CLI in scripts/workthreads.mjs (index/threads, --projects/--scan/--dir, --db, --days, --json, --out). Not 4: commands are copy-paste ready and cover the common cases; the only placeholders (<db>, <parent-of-repos>) are inherently user-specific paths. | 5 / 5 |
Workflow Clarity | The default flow is a clearly numbered sequence (index → threads → write rollup → save to dated file) with a deliverable checklist (a-e) and an explicit evidence-citation requirement ("cite evidence refs (path:line) so each claim is checkable"). Not 5: there is no explicit checkpoint for failure modes — e.g., what to do if indexing errors, the digest comes back empty, or the DB was built against the wrong scope; the engine's own stderr/exit-code reporting is relied on implicitly. Not 3: the sequence is complete and the operations are non-destructive (read-only over the corpus, one report file written), and the 'checkable claims' instruction plus the in-progress caveat function as verification affordances. | 4 / 5 |
Progressive Disclosure | SKILL.md is a concise overview; the implementation lives in a real, verified bundle (scripts/workthreads.mjs plus lib/ modules) referenced one level deep via the bash commands, with no nested references and well-organized sections (engine split, default flow, guided start, conventions). Not 4: nothing that belongs in a separate file is inlined — the digest format, statuses, and flags are all interface-level detail the body legitimately needs. | 5 / 5 |
Total | 18 / 20 Passed |