Content
82%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 a dense, highly actionable operations manual: executable commands, fully enumerated manifest keys, explicit failure-resume and verification rules, with real bundle scripts backing every referenced path. Weaknesses are mild: the manifest/1Password reference material is inlined rather than split out, the release workflow is never presented as an explicit ordered sequence, and one or two passages could be tightened.
Suggestions
Move the long manifest key and 1Password field documentation into a references/manifest.md (referenced one level deep from SKILL.md) to slim the main body.
Add a short ordered workflow section (e.g. 1. status check → 2. notes → 3. build/package → 4. appcast + verify → 5. draft release + check-assets → 6. publish → 7. Done checklist) so the command sequence is explicit rather than inferred from listing order.
Break the MAC_RELEASE_CODESIGN_* keychain paragraph into bullet points or move it to a reference file; it packs a dozen distinct behaviors into one run-on sentence.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body never explains concepts Claude already knows and is densely operational throughout ("Never print private key material", "Upload app/dSYM assets to a draft before publication"). It is not anchor 5 because a few passages could be trimmed: the codesign keychain paragraph (line 81) is a run-on covering a dozen behaviors, and the 1Password rules partially restate manifest field semantics. | 4 / 5 |
Actionability | Commands are copy-paste ready with full paths and subcommands (status, notes, changelog-html, make-appcast, verify-appcast, check-assets, release, codesign-run, package-run), and every manifest key is enumerated with defaults, examples, and semantics (e.g. "MAC_RELEASE_SPARKLE_OP_REF — exact `op://Vault/Item/field` reference..."). Concrete coverage of the common cases, matching anchor 5. | 5 / 5 |
Workflow Clarity | The Commands section order (status → notes → changelog → appcast → verify-appcast → check-assets → release) implies a clear sequence, and validation is genuinely present (verify-appcast, check-assets, the "Done" checklist, and the resume-on-failure rule that preserves release state). It is not anchor 5 because there is no explicit ordered walkthrough of a full release tying the commands together; not anchor 3 because checkpoints are explicit, not merely implicit. | 4 / 5 |
Progressive Disclosure | Structure is good (Rules / Commands / Manifest / Done), the 76KB of implementation is properly externalized into scripts/mac-release and scripts/lib/mac_release.sh (both verified to exist), and the body documents the interface rather than the implementation. It is not anchor 5 because ~60 lines of manifest and 1Password field reference are inlined in SKILL.md rather than split into a references/ file (none exists in the bundle). | 4 / 5 |
Total | 17 / 20 Passed |