Content
85%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 tightly written, highly actionable body that earns its token budget with genuinely non-obvious operational knowledge and well-checkpointed workflows. The one real defect is bundle structure: the advertised jira-adf.md reference is missing, leaving the Jira-ADF capability without its promised details.
Suggestions
Ship the missing jira-adf.md in references/ (or inline its essentials — the ADF call, the media id Jira validates against, and the two opaque 400 meanings) so the Jira-description capability is reachable rather than a dead link.
Add one example invocation each for the common cases (e.g. downloading a ticket's attachments and uploading a file to a Slack message), noting they may drift and `--help` remains authoritative.
Consider moving the Slack bot limitations list into a reference file if it grows, keeping SKILL.md as the overview; today it is still short enough to inline safely.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with non-obvious operational knowledge — the exit-0-with-no-data gotcha, the token-in-shell-history warning, mrkdwn vs markdown, invited-channels-only, dist-is-not-source — with zero padding or explanation of concepts Claude already knows. Every token earns its place, matching the score-5 anchor. | 5 / 5 |
Actionability | Concrete, executable guidance dominates: the `--help` discovery loop, copy-paste `jira`/`slack setup` and `config` commands, exact error signatures ("No Jira config found", "◆ SLACK_BOT_TOKEN"), and a full `gh issue create` invocation. Not score 5 because the common operations (download/upload/delete) get no example invocations, and the ADF-description capability dead-ends at a referenced file; not score 3 because the `--help`-as-source-of-truth design is explicit, justified, and executable for the remaining capabilities. | 4 / 5 |
Workflow Clarity | Sequences are explicit with validation checkpoints and feedback loops: re-read `--help` "when a command surprises you", verify the hand-off via `jira config`, treat the HTML error as not-invited and "invite it and retry", and rehearse destructive deletes in a sandbox channel. The destructive-operation validation cap is satisfied by the rehearsal and sign-off guidance, matching the score-5 anchor's error-recovery loops. | 5 / 5 |
Progressive Disclosure | Section structure is good and the single external reference ([`jira-adf.md`](jira-adf.md)) is clearly signaled and one level deep — but the file does not exist in the bundle (no references/ directory), so the ADF call details, media id, and 400 meanings are neither inlined nor reachable. Not score 4 because a nonexistent reference is more than a 'minor organization gap'; not score 2 because the remaining structure is well-organized rather than inlined-monolithic. | 3 / 5 |
Total | 17 / 20 Passed |