Content
53%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 SKILL.md body is a well-organized, token-efficient overview that correctly avoids inlining detail, and the version-numbering section is genuinely executable. However, the entire progressive-disclosure structure is broken in practice — all seven referenced bundle files are absent — which also undermines actionability, since the conventions the skill exists to convey are unreachable. A concrete lint/test command would strengthen the lone implicit validation checkpoint.
Suggestions
Add the seven referenced bundle files (file-entities.md, code-entities.md, coding-conventions.md, hooks.md, dependency-injection.md, data-integrity.md, unit-tests.md) to the skill bundle, or remove the references and inline the essential conventions — as written, every detailed instruction is a dead link.
Replace 'Run linting and tests before committing changes' with the specific lint and test commands (e.g., the exact phpcs/phpunit invocations the project uses) so the validation checkpoint is executable.
Drop the redundant opening paragraph that restates the frontmatter description, and clarify the odd 'Prefer bun over npm/bunx' phrasing (npm/npx?) so it reads unambiguously.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean, assumes Claude's competence, and explains nothing Claude already knows — close to the top anchor. It is not a 5 because of minor trimmable content: the opening sentence 'This skill provides guidance for developing WooCommerce backend PHP code according to project standards and conventions.' merely restates the frontmatter description. | 4 / 5 |
Actionability | The in-body guidance is concrete in places — 'Place new internal classes in `src/Internal/`', 'Use PSR-4 autoloading with `Automattic\WooCommerce` namespace', and a fully executable version-determination procedure — but the primary instruction path delegates all convention detail to seven referenced files ('See [file-entities.md](file-entities.md)...') that do not exist in the bundle, so key executable details are missing. Not a 4 because following the main instructions dead-ends rather than yielding mostly executable guidance. | 3 / 5 |
Workflow Clarity | The Version Information section gives a clear sequenced procedure (read `$version` in `includes/class-woocommerce.php` on trunk, strip `-dev`), and 'Run linting and tests before committing changes' is a checkpoint, but it is implicit with no commands given, and there is no validation or error-recovery loop for the code-modification work the skill directs. This matches the 'steps listed but validation gaps' anchor rather than 4, which requires most checkpoints to be explicit. | 3 / 5 |
Progressive Disclosure | The SKILL.md structure itself is well organized — a topical index with clearly signaled, one-level-deep references per topic — but every one of the seven referenced files (file-entities.md, code-entities.md, coding-conventions.md, hooks.md, dependency-injection.md, data-integrity.md, unit-tests.md) is missing from the bundle, so the navigation promise fails entirely. This sits noticeably below the midpoint between 'impossible to navigate' (1) and 'good structure' (3/4): the overview is clean but the disclosed content does not exist. | 2 / 5 |
Total | 12 / 20 Passed |