Content
77%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-structured, highly actionable skill body with a clear phased workflow, concrete commands, parameters, and error-handling feedback loops. Its main weakness is progressive disclosure: the provided reference files are never linked from the body, which instead inlines duplicate condensed versions, hiding deeper material like Audit Mode.
Suggestions
Replace the inlined File Type → Scan Type and severity-mode tables with pointers to references/supported-languages.md and references/severity-thresholds.md, keeping only a minimal operational summary in the body — this would surface details like Audit Mode that are currently undiscoverable.
Specify a concrete cache mechanism for the 'Cache results keyed by file + content_hash with a 12-hour TTL' guidance (e.g., where the cache is stored and how to check it), or drop the caching instruction if no persistent mechanism is intended.
Trim the opening paragraph, which restates the frontmatter description almost verbatim, to reclaim tokens without losing information.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is information-dense with almost no explanation of concepts Claude already knows — every table and command earns its place — but the opening paragraph largely restates the frontmatter description and the file-type/threshold tables duplicate material already in the reference files, leaving minor trimmable content short of the lean level-5 anchor. | 4 / 5 |
Actionability | Concrete, mostly executable guidance throughout: exact git commands ('git diff --name-only HEAD', 'git diff -U0'), named MCP tools with parameters ('severity_threshold: "medium"', 'all_projects: true'), hunk-range parsing ('@@ -X,Y +A,B @@'), and a copy-ready '.snyk' policy YAML. The gap is 'Cache results keyed by file + content_hash with a 12-hour TTL', which specifies no storage mechanism, fitting level 4 rather than fully executable level 5. | 4 / 5 |
Workflow Clarity | Five clearly sequenced phases (change detection → scans → filter → report/decision → metrics) with explicit block decision logic and genuine feedback loops: 'Retry once with smaller scope' for timeouts, auth error retry via 'snyk_auth', and suppress-then-'re-run to verify' for false positives. The skill is explicitly non-destructive ('Never modify code, only report findings'), so the batch-operation cap does not apply. | 5 / 5 |
Progressive Disclosure | The body is well-sectioned, but the two actual bundle files (references/severity-thresholds.md and references/supported-languages.md) are never mentioned anywhere in the body — instead condensed duplicates of both (the File Type → Scan Type table and the severity mode table) are inlined, and content such as Audit Mode exists only in the unreferenced file. This matches the level-3 anchor: references present but not clearly signaled, content that should be separate is inline. | 3 / 5 |
Total | 16 / 20 Passed |