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 well-engineered skill body: highly actionable commands and examples, a clearly split one-level-deep reference file, and a coherent six-step workflow. The remaining polish is trimming repeated source attributions and Overview overlap, and adding an explicit error-recovery loop around rule validation.
Suggestions
Trim the Overview section (it re-states Semgrep's description already in frontmatter) and consolidate the repeated 'Per [sg-cli][sg-cli]' attribution lines into a single provenance note in the References section.
After `semgrep validate --config .semgrep.yml` in Step 3, add an explicit recovery loop: if validation fails, read the reported rule-id error, fix the YAML, and re-validate before proceeding.
Convert the bare documentation URLs in the References section (semgrep.dev/docs/writing-rules/rule-syntax, semgrep.dev/docs/semgrep-ci/overview) into markdown links so navigation is consistent with the other references.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dominated by terse commands, YAML, and tables that earn their tokens, but the Overview re-states what Semgrep is (already in the description) and the attribution phrase 'Per [sg-cli][sg-cli]' repeats roughly six times. These are minor trimmable instances matching anchor 4, not 5's 'every token earns its place' and not 3's padded-explanation level. | 4 / 5 |
Actionability | Every section gives copy-paste-ready material: install commands, `semgrep scan --config auto`, a complete custom-rule YAML with CWE metadata, `semgrep validate --config .semgrep.yml`, a full GitHub Actions workflow with SARIF upload, and a suppression table with a mandatory justification template. Fully executable and covering the common cases matches anchor 5. | 5 / 5 |
Workflow Clarity | Steps 1-6 are clearly sequenced and include a validation checkpoint (`semgrep validate --config .semgrep.yml`) plus explicit exit-code gating (0/1/2). However, there is no explicit validate-fail -> fix -> re-validate recovery loop, so it sits at anchor 4 ('most checkpoints present; minor validation gaps') rather than 5's feedback loops. | 4 / 5 |
Progressive Disclosure | The spine keeps only the common commands and delegates exhaustive flag, performance, and exit-code tables to references/cli-reference.md, which exists as a real file, is clearly signaled in Step 6, and is exactly one level deep. Combined with clean section/table navigation, this matches the anchor-5 example of a well-split overview with well-signaled references. | 5 / 5 |
Total | 18 / 20 Passed |