Content
66%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 well-structured with a clear workflow and genuinely good progressive disclosure into real reference files, but it is undermined by inline JSON examples whose schema contradicts the skill's own config-schema reference, three sections of duplicated content, and broken eval links. The strongest material is the workflow and anti-pattern guidance; the weakest is executable correctness of the headline examples.
Suggestions
Align the inline opencode.json examples with references/config-schema.md: replace the 'providers' array with 'baseEnv' entries with the documented 'provider' object map using '{env:VAR}' apiKey options, and replace 'permissions': {'filesystem', 'shell'} with the documented 'permission': {'edit', 'bash', 'webfetch'} structure, so copy-paste examples are actually valid.
Remove or merge redundant sections: drop the 'Information Architecture' TOC (headers already navigate), fold 'Quick Commands' into the Workflow (they repeat steps 4-5 verbatim), and consolidate 'Quick Start' with 'Configuration Examples'.
Fix or remove the 'Eval Scenarios' section — the three links point to evals/scenario-0..2/task.md but no evals/ directory exists in the bundle.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body contains several structurally redundant sections: the 'Information Architecture' bullet list duplicates the file's own headers as a table of contents, 'Quick Commands' repeats the exact commands already embedded in Workflow steps 4-5, and 'Quick Start' overlaps the 'Configuration Examples' section with a near-identical provider JSON block. This is 'mostly efficient but could be tightened' rather than score 4, where over-explanation would be only minor instances — here three whole sections could be removed or merged with no loss of information. | 3 / 5 |
Actionability | Concrete commands (jq, rg, opencode run) and full JSON/markdown templates exist, but the primary copy-paste examples contradict the skill's own references/config-schema.md: SKILL.md shows a top-level 'providers' array with 'baseEnv' and 'default: true' model entries and a 'permissions' object with 'filesystem'/'shell' keys, while the bundled schema documents 'provider' (object map with '{env:...}' apiKey options), 'permission' with 'edit'/'bash'/'webfetch' keys, and 'model': 'provider/model-id'. A user copy-pasting the inline examples produces config the skill's own reference says is invalid — concrete guidance with a substantive correctness gap, not the 'minor gaps' of score 4. | 3 / 5 |
Workflow Clarity | The six-step Workflow has an explicit sequence with two validation checkpoints ('jq . opencode.json >/dev/null', smoke test 'opencode run "test"') and a stated error-recovery loop ('If errors surface, re-read config precedence before widening permissions'). This matches the top anchor — clear sequence, explicit validation steps, feedback loop for error recovery — and the destructive/batch cap of 3 does not apply because verification is present. | 5 / 5 |
Progressive Disclosure | Structure is good: a references table with a 'When to Use' column clearly signals three one-level-deep reference files that all exist, and deep field material is correctly kept in references/config-schema.md rather than inlined. It falls short of score 5 because the 'Eval Scenarios' section links to evals/scenario-0..2/task.md and no evals/ directory exists in the bundle — three dead navigation links — and the 'Information Architecture' hub adds a redundant navigation layer. | 4 / 5 |
Total | 15 / 20 Passed |