Content
56%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 highly actionable with concrete commands, a verified install path, and solid troubleshooting, but it is noticeably verbose with README-style sections and duplicated instructions, and its architecture references point at files missing from the bundle. Structure is present but detail that belongs in reference files is inlined.
Suggestions
Move the ScanReport/Vulnerability schema, Roadmap, Contributing, License, and Resources sections into a references/ file or README, keeping SKILL.md to install, usage, and troubleshooting.
Deduplicate tool-install instructions (prerequisites vs. troubleshooting) and test-running commands (Verification vs. Development) into single authoritative sections.
Reconcile the architecture tree with the actual bundle — either ship the referenced lib/, hooks/, and test/ files or remove those entries so navigation reflects what exists.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~500-line body inlines README material (Roadmap, Contributing, License, Resources), duplicates tool-install instructions between Prerequisites and Troubleshooting, duplicates test commands between Verification and Development, and offers two parallel install routes. Several unnecessary padded sections match the 2 anchor; not 3 given the volume of duplication. | 2 / 5 |
Actionability | Concrete and mostly executable: exact CLI invocations with flags ('runner.sh --target ./skills/ --output report.json --format json'), env vars, a complete signature-verified install script, and a hook setup command. Minor gaps: 'node test/*.test.mjs' and 'python ../../utils/validate_skill.py' reference paths that are not in this bundle. | 4 / 5 |
Workflow Clarity | Install → verify binaries → scan → hook setup is clearly sequenced, with a Fail-Open Philosophy section, a Troubleshooting section covering failure modes, and a Verification section including '--check' and unit tests for this batch operation. Not 5 because the main scan workflow lacks an explicit 'validate the report' checkpoint after scanning. | 4 / 5 |
Progressive Disclosure | Sections are well organized, but everything is inlined — the 28-line ScanReport/Vulnerability schema, roadmap, and license belong in separate reference files, and the architecture tree references 'lib/', 'hooks/clawsec-scanner-hook/HOOK.md', and 'test/' that do not exist in the actual bundle (only 'scripts/' is present). Some structure with inline content that should be separate and partly misleading references fits the 3 anchor. | 3 / 5 |
Total | 13 / 20 Passed |