Content
70%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.
Operationally excellent — executable commands, a precise tool contract, and a rigorous verify-then-escalate workflow with real feedback loops — but severely overlong for a SKILL.md, with duplicated guidance, migration history, and contributor notes that belong in a changelog. Worse, all five companion files it directs the agent to read are missing from the bundle, so its progressive-disclosure design exists only on paper.
Suggestions
Ship the companion files the body depends on (MACOS.md, WINDOWS.md, LINUX.md, BROWSER.md, RECORDING.md) or inline their critical content — every per-OS forbidden list, launch idiom, and dispatch detail is currently unreachable because the referenced files do not exist in the bundle.
Cut migration history and contributor material (capture_mode deprecation prose, the get_app_state history with the IINA reproducer, 0.14/0.17 version notes, the schema_consistency_test contributor note) into a CHANGELOG.md or CONTRIBUTING file; keep only current behavior plus a one-line 'deprecated, ignored' note.
Deduplicate the repeated guidance: the verify-then-escalate ladder appears in three sections and session semantics in two — keep one authoritative statement of each and cross-reference it, and move the agent-cursor-overlay aesthetic detail (theme/glow/animation description) into its own reference file.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | At ~1070 lines the body is noticeably verbose with several padded sections: changelog/migration prose ("capture_mode is DEPRECATED and ignored", "Why window selection is the caller's job now", "0.14 migration notes", "bare indices fail closed in 0.17"), contributor-facing material ("CI gate (schema_consistency_test) … don't re-hand-write the JSON, or the gate fails"), cursor-overlay aesthetics ("glow fades to transparent around the full silhouette … tighter, softer glow"), and guidance repeated 2–3 times (sessions in "Choose the target on each action" and the canonical loop; verify-then-escalate in "Start with the narrowest semantic route", the ladder algorithm, and "Verify after every action"). Not score 1 because it never explains concepts Claude already knows — the padding is domain-specific, not background tuition. | 2 / 5 |
Actionability | Fully executable throughout: copy-paste CLI invocations with JSON args ("qwen-cua-driver click '{"pid":844,"element_token":"s0000002a:14"}'"), a complete tool dispatch table with exact parameter shapes, a runnable PIL crosshair script, and an error table keyed on literal error strings ("No cached AX state for pid X window_id W") with specific fixes. Covers the common cases end-to-end. | 5 / 5 |
Workflow Clarity | The workflow is explicitly sequenced with validation checkpoints and feedback loops: the canonical loop (launch → get_window_state → act → verify_state), the verify-then-escalate ladder with concrete escalation signals ("resp.effect == 'suspected_noop' … check.status != 'satisfied'"), and "Verify after every action — mandatory" with a bounded poll instead of hand-written sleeps. Error-recovery paths and the single most common failure mode ("Agents that skip this step report success on silently-dropped actions") are called out — this satisfies the destructive/batch validation cap rather than tripping it. | 5 / 5 |
Progressive Disclosure | The in-file structure and routing guidance are good ("Platform-specific reading — read this first" with clearly signaled one-level-deep pointers to MACOS.md/WINDOWS.md/LINUX.md/BROWSER.md/RECORDING.md), but scored against the actual bundle, none of those companion files exist — the bundle contains only SKILL.md — and one pointer escapes the bundle entirely ("../../../docs/action-result-contract.md"). The advertised split is absent, leaving a 1070-line monolith whose critical per-platform content (forbidden lists, launch semantics, dispatch details) is unreachable, so it cannot score 4 ("most content is appropriately placed") and is not the unstructured inlining of the 2 anchor. | 3 / 5 |
Total | 15 / 20 Passed |