Content
81%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.
Highly actionable and well-sequenced content with strong validation checkpoints and a complete executable SDK example. The main weakness is token efficiency: the brief template and issue-fetching instructions are duplicated between the prose workflow and the embedded code snippet.
Suggestions
Deduplicate the brief structure: keep either the 'Recommended brief shape' markdown template in step 3 or the equivalent section inside the JS snippet, not both — reference one from the other to save ~40 lines.
Move the full SDK publishing snippet into a scripts/ file (e.g., scripts/propose-issue.mjs) invoked by the documented env-var command, keeping only a short excerpt inline in SKILL.md.
Consolidate issue-fetching guidance: step 2 describes fetching the issue and comments, and the JS snippet repeats that logic; state it once and let the snippet be the implementation.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is directive and free of concept-explanation padding, but the brief structure is written out twice (the ~40-line 'Recommended brief shape' template in step 3 and again inside the JS snippet), and issue-fetch instructions appear in both step 2 and the snippet. More than minor trimming is available, so it fits 'mostly efficient but could be tightened' rather than anchor 4. | 3 / 5 |
Actionability | Fully executable guidance: exact CLI commands with an npx fallback, a complete self-contained ESM SDK snippet, and the precise env-var invocation command. Copy-paste ready and covers the common end-to-end case with no gaps. | 5 / 5 |
Workflow Clarity | A clear five-step sequence with explicit validation checkpoints at each risky step: stop on missing team/diary ids, stop on an empty token, ask if the issue is closed, preview and ask once before publishing, and stop rather than falling back to a human token, plus fallback paths for CLI/SDK availability. | 5 / 5 |
Progressive Disclosure | A single-file skill with well-organized sections and clearly signaled external doc links, and the inline 110-line snippet is explicitly justified as intentionally self-contained for publishing outside the repo. At ~300 lines the snippet and brief template could still be split into scripts/references for a leaner SKILL.md, keeping it below anchor 5. | 4 / 5 |
Total | 17 / 20 Passed |