Content
73%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-built operational skill body: fully executable commands with flags, a realistic output sample, a tight fix-and-re-run error-recovery loop, and a bundle structure whose referenced files all exist. Its weaknesses are redundancy (the Common Scenarios and 11 anti-pattern sections repeat content already conveyed) and one broken pseudocode example in the Extending section.
Suggestions
Consolidate the 'Common Scenarios' section (which repeats Basic Usage commands) and trim the 11 anti-pattern blocks to the non-obvious ones — e.g. the rule codes already shown in the output example and the strict-mode guidance carry most of the information — to tighten conciseness.
Fix or remove the non-executable code in 'Extending the Skill': the example references an undefined `pool` variable and lacks the method scaffolding, so it reads as broken pseudocode rather than a working custom-rule template.
Replace the vague "see `references/` for rule details" pointer in error recovery with the explicit file name (references/azure-pipelines-reference.md), and consider moving the detailed anti-pattern catalog into that reference file.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The operational content (commands, flags, output sample, troubleshooting table) is efficient and free of concepts-Claude-already-knows padding, but ~65 lines of 11 anti-pattern blocks partially restate rule codes already shown in the output example, and "Common Scenarios" re-runs commands verbatim from Basic Usage — more than the 'minor trimmable instances' of the 4 anchor, fitting 'mostly efficient but could be tightened' at 3. Not 2, since there is no unnecessary concept explanation and most sections earn their tokens. | 3 / 5 |
Actionability | Nearly everything is copy-paste executable: "bash scripts/validate_azure_pipelines.sh azure-pipelines.yml --security-only --strict", per-layer flags, a real output/error format, and a troubleshooting table with concrete fixes. The gap is the "Extending" snippet — "if 'tags' not in pool" references an undefined `pool` and is incomplete pseudocode, which the guidelines penalize — so 4 (minor gaps) rather than 5. | 4 / 5 |
Workflow Clarity | The workflow is clearly sequenced with an explicit feedback loop: "Fix findings in layer order", numbered error-recovery steps ("Note the rule code... Fix the flagged line and re-run the same layer... Run full validation once all targeted fixes are applied"), and a validation checkpoint treating MEDIUM/HIGH security findings as merge blockers — this matches the explicit-validation-with-error-recovery 5 anchor, not 4 where checkpoints have gaps. | 5 / 5 |
Progressive Disclosure | Structure is good: SKILL.md is an overview with one-level-deep references that all exist (references/azure-pipelines-reference.md, five assets/examples files, all referenced scripts), and the References section signals each file's purpose. Minor gaps keep it at 4: the error-recovery pointer "see `references/` for rule details" is vague rather than naming the file, and the large inline anti-patterns block is content that could be split out; not 3, since the split and navigation are genuinely good and nothing is buried. | 4 / 5 |
Total | 16 / 20 Passed |