Content
60%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 operational guidance is outstanding — exact commands, executable code, and genuinely thoughtful validation loops (dry-run inspection, lock diffs, intent-based preview/run selection). The skill's structure undermines it: a ~640-line SDK API reference is inlined into SKILL.md with no bundle files at all, bloating every context load with material needed only occasionally.
Suggestions
Move the entire 'TypeScript SDK (windmill-client)' API listing (lines ~200–837) into a references/ file (e.g. references/windmill-client.md), keeping only the import line, the prefer-client-over-fetch rule, and 3–4 most-used helpers inline with a clearly signaled pointer.
Break the dense run-on bullets (e.g. the custom resource-type paragraph) into short scannable rules; each currently packs 4–5 decisions into one sentence.
Consider splitting the CLI/metadata-sync operational sections into their own reference or tightening them, so SKILL.md reads as an overview (structure, resources, preview/deploy intent) with one-level-deep pointers to detail.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Roughly 640 of the ~837 lines are an inlined windmill-client SDK API dump ('The full windmill-client API reference (every exported function and its signature) is included below'), material that should live in a references file and be consulted on demand. Some sections are exemplary (preview-vs-run intent rules, metadata sync), but the dense run-on paragraphs (e.g. the custom resource-type bullet) and the reference wall make this noticeably verbose. It is above 1 because most content is non-obvious Windmill-specific fact rather than explanation of concepts Claude already knows, but the sheer padding of the inline reference keeps it at 2. | 2 / 5 |
Actionability | Guidance is fully executable throughout: exact CLI commands with intent-mapped usage ('wmill script preview <script_path>', 'wmill generate-metadata --dry-run', 'wmill generate-metadata f/foo'), copy-paste-ready code for main()/RT/S3 operations, and per-database placeholder syntax ('$1 for PostgreSQL, ? for MySQL/Snowflake, @P1 for MSSQL'). Not score 4: the common cases (structure, resources, client import, S3 read/write) are each covered by concrete runnable examples. | 5 / 5 |
Workflow Clarity | The operate/test/deploy workflow is clearly sequenced with real checkpoints: choose preview vs. run by intent, offer to test after writing, dry-run metadata regeneration to inspect stale items before narrowing, and diff regenerated locks to report dependency version changes. Not 5: the script-authoring half is a collection of principles rather than a sequenced flow with an explicit validate-before-deploy checklist, and validation depends on the model choosing preview; not 3 because validation steps (dry-run, lock diff, preview gating) are explicit and well placed. | 4 / 5 |
Progressive Disclosure | No bundle files exist (no references/, scripts/, or assets/), yet the body inlines a ~640-line API reference — a near-verbatim match for the score-2 anchor '[300 lines of API reference that should be in a separate file with no section headers]'. External pointers that do exist (AGENTS.wmill.md, the preview and write-script-bunnative skills, rt.d.ts) are clearly signaled and one level deep, which keeps it above 1, but the failure to split the SDK reference into a separate file dominates the score. | 2 / 5 |
Total | 13 / 20 Passed |