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 lean, well-structured body with a clear input/output contract, an explicit convergence checkpoint, and thoughtful anti-patterns — it reads more like precise internal documentation than an executable instruction sheet. The main gap is actionability: the primary extract operation is described rather than given as a runnable command or code path.
Suggestions
Show one complete, copy-pasteable invocation (e.g. a full `od plugin apply figma-extract --input fileUrl=<url> --token ...` example with the OAuth input step included) instead of the truncated fragment.
Add a minimal concrete example of `figma/tree.json` (one frame with a child node) so the output contract is verifiable rather than implied by the field list in the tree diagram.
Flesh out the failure path into a short validate → recover loop (e.g. "on 401, re-run `oauth-prompt` and retry once before aborting") to close the remaining workflow-clarity gap.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is compact and assumes reader competence — an inputs table, an output tree diagram, and terse sections ("The atom completes when `figma/tree.json` exists and is non-empty"); no padding or explanation of concepts Claude already knows. Not 5 because a few tokens go to project-internal bookkeeping ("Spec §10 / §21.3.1", the atom/orchestration framing) that is not operational; not 3 because there is no noticeable over-explanation to trim. | 4 / 5 |
Actionability | Concrete guidance exists but is incomplete: the only invocation form given is a fragment ("`od plugin apply --input fileUrl=…`") with no full command for the OAuth input, and the actual extraction behavior is delegated to "`apps/daemon/src/plugins/atoms/figma-extract.ts`" rather than shown. This matches anchor 3 (some concrete guidance, key details missing / pseudocode-level); not 4 because a reader cannot execute or faithfully reproduce the extract step from the body alone; not 2 because the output contract, invocation surface, and failure modes are specified concretely. | 3 / 5 |
Workflow Clarity | The flow is well sequenced with an explicit validation checkpoint and error paths: inputs → deterministic output ("writes a deterministic, JSON-shaped extract") → convergence check ("The `until` evaluator reads `figma.tree.nodes >= 1`") → failure handling ("if the figma file is empty or the OAuth token expired, the atom emits a clear error event and the run aborts"). Matches anchor 4 (clear sequence, most checkpoints present); not 5 because the error path ends in abort-and-let-the-user-fix rather than an explicit validate → fix → retry loop, and the token-exchange step is referenced ("Routed through `oauth-prompt`") without its own checkpoint. | 4 / 5 |
Progressive Disclosure | This is a short (~55-line), single-purpose skill with no bundle files (references/, scripts/, assets/ are absent) and no external reference files needed — the rubric's guideline that short, well-organized skills can score 5 applies. Sections (Inputs / Output / Convergence / Anti-patterns / Status) are clearly headed and each is appropriately scoped; the one file pointer (`apps/daemon/src/plugins/atoms/figma-extract.ts`) is a status note about an implementation location, not a buried multi-level reference chain. Not 4 because there are no organization gaps to point at — every section earns its place at one level of depth. | 5 / 5 |
Total | 16 / 20 Passed |