Content
90%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 well-structured, token-efficient overview with copy-paste-ready examples and genuine one-level-deep progressive disclosure. The two gaps are the dead eval-scenario links and validation being placed in Quick Start rather than woven into the creation workflow itself.
Suggestions
Remove the Eval Scenarios section or correct the evals/scenario-*/task.md paths — the linked files do not exist in the bundle, which undermines navigation trust.
Fold the validation step ('run `bun run opencode` and confirm via `/agents`') into the Creation Workflow as an explicit final checkpoint after Phase 3, so the sequence ends with verify-not-assume.
Add one line of error-recovery guidance (e.g., 'if the agent does not appear, check frontmatter YAML syntax') to close the feedback loop that is currently only implied by Phase 3.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Lean body where every token earns its place: a decision table, terse anti-patterns with one-line WHYs, and a 'When NOT to use' section. 'An agent is a markdown file with YAML frontmatter' is OpenCode-specific convention, not knowledge Claude already has, so it is not padding. | 5 / 5 |
Actionability | Fully executable guidance: copy-paste-ready frontmatter and permission YAML blocks, the exact target path '.opencode/agents/<name>.md', and a concrete verification command ('Run `bun run opencode` and type `/agents` to confirm'). Common cases are covered by worked examples. | 5 / 5 |
Workflow Clarity | Clear phase sequence (1, 1.5, 2, 3) with a review feedback loop ('Show draft, iterate until user approves') and a validation checkpoint (run + `/agents` confirm). Not 5: the validation step lives in Quick Start rather than being integrated into the workflow sequence, and error-recovery/troubleshooting detail is delegated entirely to the reference file with only one-line phase summaries inline. | 4 / 5 |
Progressive Disclosure | Good structure with two well-signaled, one-level-deep references (references/agent-patterns.md and references/opencode-config.md) that exist and match their in-body descriptions. Not 5: the Eval Scenarios section links 'evals/scenario-0..2/task.md' but no evals directory exists in the bundle, leaving dead navigation links. | 4 / 5 |
Total | 18 / 20 Passed |