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.
A highly actionable, platform-specific guide with excellent command-level and API-level detail, real validation feedback loops in the metadata-sync workflow, and correct risk gating around deploys. Its weaknesses are repetition of the deploy-gating rule across sections and a monolithic structure that inlines the entire SDK API reference instead of splitting it into a references/ file.
Suggestions
Move the ~640-line 'TypeScript SDK (windmill-client)' API reference into references/windmill-client.md and keep only the most-used helpers (getResource, runScriptByPath, S3 helpers) inline with a clearly signaled pointer.
Consolidate the deploy-gating guidance (repeated in CLI Commands, Preview vs run, and After writing sections) into a single 'Deploying' subsection stated once.
Tighten the very long multi-clause sentences in General Principles into short imperative bullets so each rule is scannable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient platform-specific content Claude cannot know (wmill CLI semantics, windmill-client API, S3 conventions), but the deploy-gating rule is repeated four times ("Only suggest/run a deploy when the user explicitly asks", "Do NOT push... pushing is a deploy", "Only use sync push when the user explicitly asks to deploy", "do it only when the user explicitly asks to deploy/publish/push") and "it is not a deploy" recurs across the metadata sections. This matches 'Mostly efficient but includes some unnecessary explanation or could be tightened'; it is not 4 because the duplication is substantial rather than minor, and not 2 because nearly all content is genuinely novel, not concepts Claude already knows. | 3 / 5 |
Actionability | Fully executable guidance throughout: exact commands (`wmill script preview <script_path>`, `wmill generate-metadata --dry-run`, `wmill generate-metadata rehash`, `wmill resource-type list --schema`), complete runnable TypeScript examples (async main, preprocessor event typing, S3 load/write), and copy-paste-ready SDK signatures with usage examples covering the common cases. It cannot exceed 5, and nothing pulls it to 4 since no pseudocode or missing key details were found. | 5 / 5 |
Workflow Clarity | Clear sequences with real validation checkpoints: preview-vs-run is decided by explicit intent rules, and the metadata-sync workflow has genuine feedback loops — `--dry-run` lists stale items with reasons before changing anything, and after regenerating you diff the lock files and report version bumps before deploying. It falls short of 5 because the write-edit-test-deploy workflow is scattered across three overlapping sections (CLI Commands, Preview vs run, Keep metadata in sync) with no single coherent sequence or checklist, leaving minor gaps in how the steps stitch together. | 4 / 5 |
Progressive Disclosure | The body has real section structure, but ~640 lines of the windmill-client SDK API reference are inlined directly in SKILL.md with no bundle files at all (references/, scripts/, assets/ do not exist) — exactly anchor 3's pattern ('content that should be separate is inline', like '200 lines of API reference that could be in a separate file'). It is not 2 because headers and clear section boundaries exist (unlike anchor 2's 'no section headers'), and not 4 because the SDK reference is the bulk of the file and clearly belongs in a one-level-deep reference file. | 3 / 5 |
Total | 15 / 20 Passed |