Content
71%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.
An information-dense, highly actionable skill body with excellent executable examples and strong decision rules, undermined by structural bloat: duplicated API documentation for two languages and thrice-stated deploy/metadata warnings inflate the token cost. The inlined API reference is the clearest candidate for extraction into reference files.
Suggestions
Move the two full API reference blocks (lines ~242-413 and ~416-609) into references/ files such as references/typescript-api.md and references/python-api.md, keeping only a compact signature summary inline — progressive_disclosure is capped by ~370 lines of inlined API docs in a skill with no bundle files.
Deduplicate repeated guidance: state the deploy-only-on-explicit-request rule and the generate-metadata is-not-a-deploy behavior once instead of three times across the CLI list, 'Preview vs run', 'Keep metadata in sync', and 'After writing' sections.
Consolidate the post-edit flow (edit → preview → generate-metadata --dry-run → diff locks and report version bumps → deploy only on request) into a single ordered section so the workflow reads as one sequence instead of four scattered ones.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The guidance is dense with genuinely non-obvious domain knowledge (checkpoint/replay model, suspension internals, error record shape) that Claude would not already know, but it is noticeably padded: the deploy-only-on-explicit-request rule is stated three times (CLI list, 'Preview vs run', 'After writing'), generate-metadata behavior is re-explained across sections, and two ~170-line API reference blocks (TypeScript and Python) duplicate the same semantics per language. It sits between the 'noticeably verbose' (2) and 'mostly efficient' (3) anchors, above the midpoint because the repetition is redundant restatement rather than explanation of known concepts. | 3 / 5 |
Actionability | Fully executable throughout: exact CLI commands with flags ('wmill script preview <script_path>', 'wmill generate-metadata --dry-run', 'generate-metadata rehash'), complete copy-paste-ready dual-language examples for every construct, the concrete error shape '{"error": {"name", "message", "stack"?, "extra"?}}', and a per-dialect placeholder list ('$1 for PostgreSQL, ? for MySQL/Snowflake, @P1 for MSSQL'). Specific examples cover the common cases comprehensively. | 5 / 5 |
Workflow Clarity | Decision rules are explicit and unambiguous ('If the user says "run the script" ... while there are local edits, use script preview'; 'Only suggest/run a deploy when the user explicitly asks'), and validation feedback loops are present (preview before deploy, '--dry-run' to list stale items, diff regenerated locks and report version changes). However, the write → preview → metadata → deploy flow is distributed across four separate sections rather than presented as one coherent ordered sequence, leaving minor assembly work to the reader — the clear-sequence-with-minor-gaps anchor. | 4 / 5 |
Progressive Disclosure | Section headers are clear and well-organized, but roughly 370 lines of TypeScript and Python API reference ('## TypeScript Workflow-as-Code API (windmill-client)' and '## Python Workflow-as-Code API (wmill)') are inlined directly in SKILL.md with no bundle files at all — the textbook case of content that should be in separate reference files being inline. This matches the some-structure-but-could-be-better-organized anchor; not score 2 because headers and navigation exist, not score 4 because there are no references to separate files anywhere. | 3 / 5 |
Total | 15 / 20 Passed |