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.
An excellent single-file operational guide with copy-paste commands, a well-sequenced 8-phase workflow, and validation checkpoints at every risky step (auth gate, duplicate stop, pre-post style check, post-post readback). Its weaknesses are duplicated guidance between the phases and the Rules section, and a ~330-line monolithic body with no reference files despite containing inlineable bulk like the issue-body template and style-constraint tables.
Suggestions
Split inlineable bulk into one-level-deep reference files (e.g. references/issue-body-template.md with the Phase 5 markdown skeleton, and references/style-requirements.md with the per-track style-constraints and screenshot rules), keeping SKILL.md as the phased overview that points to them.
De-duplicate the '📜 Rules' section against the phases: state each rule once (GH_PAGER=cat, projectCards, click/textbox appear in both a phase and Rules) and use Rules only for constraints not covered in any phase.
Trim editorial asides that add length without adding instruction (e.g. 'The difference matters. A spec issue answers what should be built and why. The mission builder answers how it reads. Never write the mission markdown in this skill.') to a single directive line.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with repo-specific, non-inferable knowledge (fiscal-quarter milestones, GH_PAGER=cat, projectCards deprecation, per-track frontmatter contracts) and avoids explaining concepts Claude already knows. But the '📜 Rules' section restates guidance already given in the phases — GH_PAGER=cat, the projectCards warning, and the click/textbox rule each appear twice — which is trimmable duplication. This fits the 4 anchor (efficient with minor over-explanation) rather than 5 (every token earning its place). | 4 / 5 |
Actionability | Commands are copy-paste ready throughout: the milestones query ('GH_PAGER=cat gh api repos/microsoft/agent-academy/milestones --jq ...'), the full 'gh issue create' invocation with every flag, the verify readback with an exact '--json title,labels,milestone,assignees,url' field list, plus exact title formats and a complete issue-body template. This matches the 5 anchor — fully executable guidance covering the common cases. | 5 / 5 |
Workflow Clarity | Eight explicitly numbered phases with checkpoints at every fragile point: a prerequisites gate ('Do not proceed until both checks pass'), a stop-and-ask on duplicate matches, a style check run before posting ('Fix anything the check surfaces before posting. Do not post and then clean up.'), user confirmation before the irreversible public action, and a Phase 8 readback that verifies all four metadata fields and H1/title consistency. This matches the 5 anchor — clear sequence, explicit validation, and feedback loops for error recovery. | 5 / 5 |
Progressive Disclosure | There are no bundle files at all (no references/, scripts/, or assets/), and the ~330-line body inlines substantial material that belongs in one-level-deep reference files: the complete issue-body template, the per-track style-constraints table, and the screenshot rules. Section headers and tables do give it real structure, and the files it does point to (WRITING_STYLE.md, CONTRIBUTING-*.md) are runtime targets in another repo rather than bundle references. That places it at the 3 anchor ('some structure; content that should be separate is inline') rather than 4, which would require most bulk content to be appropriately split out. | 3 / 5 |
Total | 17 / 20 Passed |