Content
57%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, well-organized lookup index for plugin authoring references with one usable validation command and official doc URLs, and it appropriately avoids teaching Claude things it already knows. Its effectiveness is undermined by unresolvable bundle-relative reference paths (no reference files actually exist alongside the skill), an implicit rather than explicit lookup workflow, and cryptic jargon ("RU/EN question", "tracked skill contracts") that assumes unstated context.
Suggestions
Move the referenced markdown files into the skill bundle (e.g. a references/ directory) and rewrite the pointers as bundle-relative paths so "Read only references relevant to the question" is actually executable.
State the lookup workflow as an explicit ordered sequence (resolve topic → select reference → verify against official docs → answer with source paths), with the verify step as an explicit checkpoint before presenting behavior as current.
Replace unexplained jargon like "the RU/EN question" and "tracked skill contracts" with self-contained wording, since the skill never defines what these mean.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is a dense pointer list with essentially no explanation of concepts Claude already knows, so it is well above a 3. It falls short of 5 because a few statements are tangential or opaque and could be tightened, e.g. "Resolve the RU/EN question into the relevant manifest..." and "Setup defaults are per skill: compare documented behavior with executable resolution and report disagreements" assume context the skill never establishes. | 4 / 5 |
Actionability | There is some concrete guidance — "Validate affected product skill directories with `bash brewcode/skills/skills/scripts/validate-skill.sh <affected-skill-directory>`", "Locate with `rg --files`; inspect focused ranges", and three official doc URLs — but it is incomplete: the primary guidance consists of relative reference paths ("../../rules/best-practice.md", "../../../brewcode/...") that do not resolve from the skill's location, so the key instruction "Read only references relevant to the question" cannot be executed as written. Not a 2 because the commands and URLs that do exist are specific and usable. | 3 / 5 |
Workflow Clarity | A rough sequence is present but implicit and scattered across prose: resolve the question into a topic, consult the relevant references, "verify current or uncertain behavior before presenting it as current", then answer with sources and report disagreements. No explicit ordered steps or checkpoints are given, matching the 3 anchor (sequence present, checkpoints implicit). Not a 4 because the verify-before-presenting checkpoint is buried in a reference bullet rather than stated as an explicit workflow step. | 3 / 5 |
Progressive Disclosure | The body is organized as a clearly signaled one-level-deep reference list with per-reference scope notes, which is above a 2. However, scored against the actual bundle structure, there are no references/, scripts/, or assets/ files in the bundle at all — every file pointer uses fragile "../../"-style paths escaping the skill directory that do not resolve, so the disclosure structure is present in form but broken in practice, keeping it below 4. | 3 / 5 |
Total | 13 / 20 Passed |