Content
75%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 lean, highly actionable instruction set with concrete commands, an ordered derivation procedure, explicit validation steps, and well-signaled one-level-deep spec references. Its main weaknesses are the absence of a template or example for the generated SKILL.md/open-design.json deliverable, no explicit validate-fail retry loop, and a few over-dense paragraphs that could move to reference files.
Suggestions
Add a minimal worked example (or template) of the generated SKILL.md frontmatter and an open-design.json manifest covering the required fields, instead of deferring entirely to docs/schemas/open-design.plugin.v1.json.
Close the validation loop explicitly: state that if `od plugin validate` fails, fix the reported fields and re-run before packing and installing.
Consider moving the plugin.repo gh-auth fallback ladder and the jq guidance into a short reference file to slim the main body's densest paragraphs.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is imperative and dense — no concept explanations, no padding, and it assumes Claude's competence ("read what's already there", ordered file-reading list). A few passages could be trimmed, notably the long single-paragraph plugin.repo fallback chain and the "source of the bug that closed #2332" rationale, so it falls just short of anchor 5's "every token earns its place" but is well above anchor 3. | 4 / 5 |
Actionability | Concrete copy-paste commands appear throughout (`od plugin validate`, `od plugin pack`, `od plugin install --source <absolute-folder-path>`, `node -e '...'`), with a specific field list for open-design.json and an explicit fallback ladder for gh auth. The main gap is that the skill's primary deliverable — the generated SKILL.md and open-design.json — has no template or worked example, deferring entirely to the external schema reference, which keeps it below anchor 5. | 4 / 5 |
Workflow Clarity | The sequence is clear (read project files in order, derive fields, scaffold generated-plugin/, validate, pack, install, summarize, STOP) with an explicit validation step (`od plugin validate`) and detailed error-recovery paths for gh auth. It lacks an explicit fix-and-re-validate retry loop for validation failures, so it sits at anchor 4 rather than 5. | 4 / 5 |
Progressive Disclosure | The ~70-line body is organized into well-labeled sections (Required outcome, Auto-derive, Validate, Do NOT chain, Language, folder shape) with external spec references clearly signaled at the end and only one level deep (docs/plugins-spec.md, the plugin schema, the sibling authoring scenario). The dense inline plugin.repo and jq handling could be split into reference files if a bundle existed, keeping it just below anchor 5. | 4 / 5 |
Total | 16 / 20 Passed |