Content
78%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 security-operations skill with concrete CLI forms, a useful decision table, and sequenced validation-gated workflows for rotation and incident response. Its main defects are a missing explicit failure-path loop in the rotation workflow and, more importantly, two referenced bundle files (the secret-contract and rotation-record templates) that are absent from the actual bundle, breaking two core workflows.
Suggestions
Add the missing templates/secret-contract.md and templates/rotation-record.md files to the bundle (or remove/replace the references in the body), since the contract and rotation workflows instruct the reader to use them and currently dead-end.
Add an explicit failure-path step to the rotation workflow (e.g., 'if validation of the replacement fails, do not revoke the old token; fix scope/expiry and re-validate'), and do the same for the compromise-response sequence.
Trim the overlap between the reference-reading paragraph and the 'Bundled resources' section by keeping read-triggers in one place and content summaries in the other.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with product-specific operational rules ('A token is shown once and cannot be retrieved later', '--no-inherit-env ... is not a sandbox') and avoids generic concept explanations. It is not a 5 because the reference-reading paragraph (line 10) and the 'Bundled resources' list (lines 43-50) partially duplicate each other, and several table 'Prohibited shortcut' cells restate baseline rules already given. | 4 / 5 |
Actionability | Guidance is fully executable for the common cases: exact command forms ('bws run --project-id <id> --no-inherit-env -- <trusted-entrypoint>', 'BWS_ACCESS_TOKEN', '--uuids-as-keynames', '~/.config/bws/config', 'bws --version', 'scripts/validate_secret_contract.py <completed-contract.md>') plus a need/decision/prohibited-shortcut table. Per the rubric's code-vs-instruction note, an instruction-only skill with guidance this concrete earns full marks; only deep rotation/recovery detail is deferred to references, which is appropriate. | 5 / 5 |
Workflow Clarity | Rotation ('Create a replacement ... validate without output and validate the affected service, then revoke') and compromise response ('Stop or isolate ... create and validate a replacement, revoke ..., then run a disposable recovery test') are explicitly sequenced with validation checkpoints, and confirmation gates cover destructive changes, so the no-validation cap does not apply. Not a 5 because there is no explicit failure-path feedback loop (what to do when pre-revocation validation fails is left implicit/deferred to references). | 4 / 5 |
Progressive Disclosure | Structure is clean with clearly signaled, one-level-deep references and per-topic read triggers, but scoring against the actual bundle reveals that 'templates/secret-contract.md' and 'templates/rotation-record.md' — referenced as required artifacts for the contract and rotation workflows — do not exist in the bundle (only references/ and scripts/ are present). Broken navigation to two of six referenced files, including a core workflow artifact, is more than a minor organization gap, so it sits at 3 rather than 4. | 3 / 5 |
Total | 16 / 20 Passed |