Content
85%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.
A highly actionable, well-sequenced specification with concrete examples, exact file paths, and explicit validation checkpoints for command development. Its main structural weakness is that everything lives in one long SKILL.md with no bundle files or references to split detailed material out.
Suggestions
Split reference-style material — the shared options-shapes table, the testing-harness conventions, and the StructuredError/help-format details — into references/ files (e.g., references/options.md, references/testing.md) and link them from the body, keeping SKILL.md as an overview.
Trim the 18-item checklist by removing items that restate rules already specified in earlier sections (e.g., items 15-18 duplicate the interactive-mode, help-example, and output rules), or fold them into a shorter cross-referenced checklist.
Consider moving the detailed MSW test-harness usage examples into the proposed testing reference file, keeping only the 'tests MUST cover' list inline.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is a dense, project-specific specification with no padding about concepts Claude already knows — tables, file paths, and examples all convey non-obvious conventions. Minor instances could be trimmed (e.g., the 18-item checklist partially restates rules already specified in earlier sections), placing it at the 4 anchor rather than the 5 anchor's 'every token earns its place'. | 4 / 5 |
Actionability | Guidance is fully executable throughout: concrete bash invocations with sample output ('px project create --name foo --format raw' → JSON line), TypeScript interfaces with TSDoc blocks, exact module paths (src/config.ts, src/io.ts, src/exitCodes.ts), and a test harness recipe. This matches the 5 anchor ('fully executable; copy-paste ready; examples cover the common cases') rather than the 4 anchor with 'minor gaps'. | 5 / 5 |
Workflow Clarity | The 'Checklist for Adding a New Resource Command' is a clearly sequenced 18-step process with explicit validation checkpoints and feedback loops: 'Run pnpm test — fix any failures before proceeding', 'Run pnpm build — fix any type errors before proceeding', and 'Run manually with --format raw and --no-input to verify'. Validation is explicit and repeated, not implicit, matching the 5 anchor. | 5 / 5 |
Progressive Disclosure | The skill is a single ~300-line file with no references/, scripts/, or assets/ directories and no disclosure mechanism at all; reference-style material (the options-shapes table, testing-harness conventions) is inlined that could plausibly live in a references file. This matches the 3 anchor ('content that should be separate is inline') better than the 4 anchor, but the clear section headers and coherent structure keep it above the 2 anchor's header-less inlined reference. | 3 / 5 |
Total | 17 / 20 Passed |