Content
63%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 well-organized and highly actionable for a complex orchestration skill, with a clear gated 5-step workflow and a thorough success checklist. Its main problems are redundancy (diagram vs. workflow table, hard-gate restated five times) and a broken bundle reference: the detailed workflow file `workflows/scan-workflow.md` is cited as the primary instruction source but is missing from the bundle, and the helper scripts are not indexed.
Suggestions
Fix or remove the dangling `workflows/scan-workflow.md` reference — the file does not exist in the bundle; either add the detailed 5-step workflow file or inline the detailed steps into SKILL.md.
Deduplicate the Step 3 approval-gate guidance (currently restated in Essential Principles, Workflow, Task tracking, Rationalizations to Reject, and Success Criteria) and drop the ASCII orchestration diagram, which repeats the Workflow table's content.
Add `scripts/scan-status.sh` (the `wait_semgrep_scans` source) and `scripts/merge_sarif.py` to the Reference Index so every bundle file is discoverable from SKILL.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and almost entirely skill-specific policy (no generic concept explanations), but it could be tightened: the ASCII orchestration diagram duplicates the Workflow table's five steps, the Step-3 hard gate is restated in at least five places (Essential Principles, Workflow, Task tracking, Rationalizations, Success Criteria), and the 13-row "Rationalizations to Reject" table repeats Principles 2–4. This fits "mostly efficient but includes some unnecessary explanation or could be tightened"; a 4 would require only minor trimmable instances. | 3 / 5 |
Actionability | Mostly executable guidance: `command -v semgrep`, `SEMGREP_ENABLE_VERSION_CHECK=0 semgrep --metrics=off --version`, a copy-paste output-directory resolution block, `--severity MEDIUM --severity HIGH --severity CRITICAL` flags, and `uv run {baseDir}/scripts/merge_sarif.py $OUTPUT_DIR/raw $OUTPUT_DIR/results/results.sarif`. Minor gaps remain — Step 1 language detection is described only as "Supported file search" with no command, and the detailed execution process is delegated to a workflow file that is not in the bundle. | 4 / 5 |
Workflow Clarity | The five steps are clearly sequenced with an explicit hard gate at Step 3, per-step references, task-tracking guidance, and a 15-item Success Criteria checklist including validation (fresh JSON/SARIF pairs passed `wait_semgrep_scans`, `results.sarif` valid JSON). However, the body states "Follow the detailed workflow in [scan-workflow.md]" and that file does not exist, so the summary table carries the sequence alone and checkpoint detail (error-recovery loops) is only implicit in the checklist — clear sequence with minor validation gaps rather than a full 5. | 4 / 5 |
Progressive Disclosure | Section structure is good and the three references/ files are real, clearly signaled, and indexed, but the bundle structure has real defects: `workflows/scan-workflow.md` is referenced twice (Workflow section and Reference Index) yet does not exist — a dangling pointer to the skill's core detailed process — and `scripts/scan-status.sh` plus `scripts/merge_sarif.py` are absent from the Reference Index (scan-status is only alluded to as "the bundled scan-status helper"). Structure is present but navigation fails at the most important reference point. | 3 / 5 |
Total | 14 / 20 Passed |