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 strong, actionable reference for Windmill Workflow-as-Code with excellent executable examples and genuinely non-obvious domain knowledge, but it underuses progressive disclosure by inlining two full API references and carries notable duplication of conceptual explanations across sections. Tightening the repeated prose and splitting the API sections into reference files would cut context cost substantially without losing guidance value.
Suggestions
Move the 'TypeScript Workflow-as-Code API (windmill-client)' and 'Python Workflow-as-Code API (wmill)' sections (~370 lines) into reference files such as references/typescript-api.md and references/python-api.md, keeping only the import lines and 2-3 key signatures inline with clearly signaled links.
State each conceptual rule once instead of repeating it per language: the retry-backoff semantics, cache_ttl keying, single-job/nested-task rule, and approval-key uniqueness each appear nearly verbatim in both API sections and the prose sections.
Add an explicit authoring sequence with a validation loop for the WAC half (scaffold file shape -> wrap side effects in task/step -> wmill script preview -> fix and re-preview -> generate-metadata -> diff locks), mirroring the checkpoint discipline the CLI section already has.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient, non-obvious domain knowledge (checkpoint/replay semantics, single-job rule, failure record shape), but several explanations are duplicated nearly verbatim: the retry-backoff paragraph appears in both the TypeScript TaskRetry docstring and the Python task docstring, cache_ttl keying semantics appear twice, the 'a task runs as a single job' rule appears three times, and the preview-vs-deploy distinction is restated at least three times across the CLI sections. Deduplicating these and tightening the dense metadata-sync prose would save well over a hundred lines. | 3 / 5 |
Actionability | Fully executable, copy-paste-ready code throughout: complete file shapes for both Bun TypeScript and Python, exact import lines, working examples for tasks, taskScript/taskFlow, steps, parallelism, approvals, and error handling, plus exact CLI commands (wmill script preview, generate-metadata, generate-metadata rehash, --dry-run) covering the common cases. | 5 / 5 |
Workflow Clarity | The CLI half has a clear sequence with most checkpoints present — preview validates local edits before any deploy, '--dry-run' lists stale items before narrowing with a path, regenerated locks are diffed and version changes reported, and deploys are gated on explicit user request. However, the WAC authoring half is organized as rules and API reference rather than an explicit end-to-end sequence, and there is no articulated fix-and-retry loop for a failed preview. | 4 / 5 |
Progressive Disclosure | Section structure is good and external references that exist are clearly signaled (AGENTS.wmill.md, the preview skill), but roughly 370 lines — about 60% of the file — are inline TypeScript and Python API reference sections that clearly belong in separate reference files (e.g. references/typescript-api.md, references/python-api.md), matching the rubric's example of API reference inlined in SKILL.md. | 3 / 5 |
Total | 15 / 20 Passed |