Content
92%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.
An exceptionally well-built skill file: the quick-check workflow is fully sequenced with explicit validation and rerun loops, every command is copy-paste executable with flags and caveats, and all bulk material (21 rules, fix code, audit mode, probe commands) is properly deferred to real, well-signaled reference files. The only weakness is mild length in the changelog-logging step and the Resources link list, which could be tightened without losing anything.
Suggestions
Trim step 10's changelog mechanics (runs-folder options, index.md rebuild details) down to the command and the three hand-edit steps, moving storage-location details into the script's --help output.
Consolidate the six Convex doc URLs in Resources into the single docs index (https://docs.convex.dev/llms.txt) already listed, keeping only the auth and testing links that the workflow directly relies on.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with operational specifics ("The scanner works per file. A file that calls an auth helper anywhere passes, even if one function in it skips the check") and never explains concepts Claude already knows, but step 10's changelog mechanics ("It also rebuilds `~/sec-check-runs/index.md`, one row per repo. Set `SEC_CHECK_RUNS` or pass `--runs DIR`...") and the six Convex doc URLs in Resources could be trimmed. It is efficient with only minor over-explanation, matching anchor 4 rather than 5. | 4 / 5 |
Actionability | Fully executable, copy-paste ready commands cover every common case: "bash <skill-dir>/scripts/sec-scan.sh . --strict", "node <skill-dir>/scripts/surface.cjs . --json", "node <skill-dir>/scripts/changelog.cjs . --mode quick --note \"one line on this run\"", plus a concrete regression-test pattern ("call the fixed function with `t.withIdentity({ subject: \"B\" })` and expect it to throw"). Not 4: commands include flags, caveats (--no-history, --strict, gitleaks install), and a complete report template with no gaps. | 5 / 5 |
Workflow Clarity | The 9-step numbered checklist is copied into the conversation and worked top to bottom, with explicit validation checkpoints and feedback loops: "Repeat until the scanner exits 0 and every ledger `open` row is fixed", "Before merging, say what breaks if the fix is wrong and how to roll back", and a 17-item pre-ship gate checklist. The destructive/batch validation cap does not apply because verification (step 8 rerun, verify-a-fix verdicts, tsc typecheck) is explicit throughout. Not 4: both the sequence and its checkpoints are fully explicit, including error-recovery guidance for inconclusive verdicts. | 5 / 5 |
Progressive Disclosure | The main file is a clear overview with well-signaled one-level-deep references that all exist on disk: "Read the full rule in [references/rules.md](references/rules.md) before you fix or reject a finding", "Apply the matching rule from [references/rules.md] and the code in [references/patterns.md]", with rules.md (303 lines), patterns.md (945 lines), audit.md, and probe.md holding the bulk detail and deep-link anchors (#11, #13, #18, #19) verified present. Not 4: all four references and three scripts are real, clearly signaled with what each contains, and content is appropriately split — nothing that belongs in a reference is inlined in the main file. | 5 / 5 |
Total | 19 / 20 Passed |