Content
63%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 well-organized, appropriately behavioral instruction skill with genuinely concrete CLI commands and a clear numbered workflow for the change-context path, though it is longer than it needs to be due to extensive scripted dialogue examples and could split illustrative examples into a reference file.
Suggestions
Trim the four scripted example dialogues to one or two representative ones, or move them to a references/examples.md file and keep a one-line pointer in SKILL.md.
Cut or compress the 'What You Don't Have To Do' section, since it restates the stance already covered by 'This is a stance, not a workflow' and the Guardrails section.
Consider adding a brief validation cue for artifact creation (e.g., running 'openspec validate') before capturing insights into specs or designs.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient stance guidance, but roughly 100 lines of scripted example dialogues with large ASCII art plus a 'What You Don't Have To Do' section that restates the stance could be tightened, matching 'mostly efficient but includes some unnecessary explanation or could be tightened'. | 3 / 5 |
Actionability | Concrete, executable commands are provided ('openspec list --json', 'openspec status --change "<name>" --json', 'openspec store list --json') with specific JSON fields to consume (changeRoot, artifactPaths, actionContext) and a table mapping insight types to capture locations; minor gaps remain in that the bulk of the guidance is behavioral rather than operational. | 4 / 5 |
Workflow Clarity | The 'when a change exists' path is a clear numbered 4-step sequence ending with an explicit user-decision checkpoint, and the entry check (openspec list --json) is specified; the skill is non-destructive so no validation cap applies, but the deliberately unsequenced stance sections keep it below the top anchor. | 4 / 5 |
Progressive Disclosure | The body is a single 275-line file with clear section headers but no bundle files at all; the four example dialogues are content that could live in a reference file, and at over 50 lines the simple-skill exception does not apply, matching 'some structure but could be better organized'. | 3 / 5 |
Total | 14 / 20 Passed |