Content
78%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 an unusually actionable conventions reference: every section gives executable code, exact commands, or a decision tree, and it assumes Claude's competence rather than re-teaching basics. Its main structural weakness is that it is a ~470-line monolith — the pattern deep-dives and test-infrastructure recipes belong in reference bundle files, keeping SKILL.md as a lean overview with one-level-deep pointers.
Suggestions
Split the pattern deep-dives (Molecule, Loadable bridge, Runnables, Entity selection) and the package unit-test infrastructure (vitest config, package.json scripts, Fern mocking, integration tests) into references/ files, leaving SKILL.md a lean overview with one-level-deep pointers as the progressive-disclosure anchor describes.
Add a short fix-on-failure loop to the verification rule — what to do when 'pnpm turbo run lint --filter=@agenta/<package>' fails (e.g. where the no-explicit-any and queryClient lint rules live) — to close the workflow-clarity validation gap.
Trim the 'import {...} from' placeholder blocks in the subpath-imports section to the handful of subpaths users most often need, or move the full list into a reference file keyed to the package table.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and assumes Claude's competence — no tutorials on jotai, vitest, or React basics, and 'Why:' rationales are brief and load-bearing (e.g. the tests-outside-src explanation cites commit 1c0a900). Not 5 because a few sections could be trimmed, notably the 'import {...} from' placeholder blocks in the subpath-imports section and the style-utilities example; not 3 because nearly all content is project-specific rather than padding. | 4 / 5 |
Actionability | Fully executable throughout: a copy-paste placement decision tree, hard rules with exact commands ('pnpm turbo run build --filter=@agenta/<package>'), a complete minimal vitest.config.ts, a full Fern-mocking test example with assertions, adapter tables, and runnable component code. Covers the common cases concretely. | 5 / 5 |
Workflow Clarity | The placement decision is sequenced as a decision tree and closes with an explicit verification checkpoint ('Verify your change builds AND lints before pushing' with exact commands), and the test sections are well-structured. Not 5 because there is no fix-on-failure loop (what to do when lint/build fails) and the integration-vs-unit decision guidance is prose rather than a checklist; above 3 because the validation checkpoint is explicit and commanded, not implicit. | 4 / 5 |
Progressive Disclosure | Pointers to deeper material are clearly signaled one level deep ('Full documentation: web/packages/agenta-entities/src/shared/README.md', 'see web/packages/README.md for the full list'), but no bundle files exist and roughly 300 lines of deep reference material — the molecule/loadable/runnable/selection pattern guides and the full test-infrastructure setup (configs, scripts, mocking recipes) — are inlined in SKILL.md where a references/ split belongs. This matches 'some structure, content that should be separate is inline' better than the 4 anchor. | 3 / 5 |
Total | 16 / 20 Passed |