Content
50%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The content is well-organized into clear sections with a few concrete anchors (a command, file paths, a capture table), but it is verbose for a stance skill — heavy on illustrative example dialogues and ASCII art — and monolithic with no progressive disclosure to reference files. Tightening the examples and splitting detail out would lift the weaker dimensions.
Suggestions
Trim the four multi-line example dialogues to one or two compact illustrations; the ASCII diagrams and full transcripts pad the token budget without adding proportionate guidance.
Extract the OpenSpec capture table and artifact-path reference into a separate file (e.g., references/capture.md) and link to it, giving the overview lean progressive-disclosure structure.
Convert 'you might do' stance lists into more imperative, concrete guidance so the actionability moves from illustrative to instructive.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~300-line body is padded with four lengthy example dialogues and large ASCII diagrams that illustrate rather than instruct, though it avoids explaining basic concepts Claude already knows — fitting the 'mostly efficient but could be tightened' anchor. | 2 / 3 |
Actionability | It offers some concrete guidance (the `openspec list --json` command, explicit artifact paths, and an insight-to-file capture table) but the bulk is 'you might do' illustrative stance material rather than direct, executable instruction. | 2 / 3 |
Workflow Clarity | The skill explicitly disclaims a fixed workflow ('This is a stance, not a workflow'), and while entry-point handling and guardrails are organized with a 4-step 'when a change exists' sequence, there are no validation checkpoints and process clarity is moderate rather than crisp. | 2 / 3 |
Progressive Disclosure | The body is a well-sectioned but monolithic single file (~300 lines) with no external reference files at all, matching the anchor for structure present but content that could be split remaining inline. | 2 / 3 |
Total | 8 / 12 Passed |