Content
85%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 well-engineered orchestration body: scoped, phased workflows with strong validation and recovery machinery, and clean one-level progressive disclosure into real reference and script files. The main improvable areas are token-level duplication of batching/validation guidance and a few spots where concrete call composition (helper-script embedding) is described but not shown.
Suggestions
Deduplicate the batching/visual-review/validation-evidence guidance that currently appears in both §1 ('Batch related operations…', 'Take one visual review per coherent composition phase') and Critical Rule 12 — state it once and cross-reference it.
Add one short example in §11 or Critical Rule 15 showing a helper script from scripts/ actually embedded in a use_figma call, since the rule requires embedding but never demonstrates it.
Tighten §5's get_libraries pagination discussion (offset handling, community-vs-org paging) into a two-line rule; the details could live in references/discovery-phase.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense, table-driven, and assumes Claude's competence — it never explains what Figma or design tokens are. It falls short of anchor 5 only through repetition: batching/visual-review guidance appears in both §1 ('Batch related operations… Take one visual review per coherent composition phase') and Critical Rule 12, and the get_libraries pagination discussion (§5) runs longer than needed. It is clearly above anchor 3, where unnecessary explanation or padding would dominate. | 4 / 5 |
Actionability | Highly actionable throughout: concrete API call shapes ('get_libraries({ fileKey })', 'search_design_system({ queries: [{ entity: "component", query }], fileKey, includeLibraryKeys: ["lk-abc123…"] })'), an exact state-ledger JSON format, specific scope table, naming patterns, and a helper-scripts table. It misses anchor 5 on minor gaps — e.g., Critical Rule 15 says 'embed scripts from scripts/' but shows no example of embedding a helper into a use_figma call, and some guidance ('Communicate proportionally… give updates at meaningful boundaries') is behavioral rather than executable. | 4 / 5 |
Workflow Clarity | Each scope has a numbered, sequenced path with explicit validation steps ('Validate counts, mode values, aliases, scopes, syntax, styles… then stop'), a definition-of-done checklist, an explicit error feedback loop ('If a required acceptance check fails, fix the scoped defect before continuing'), idempotency checks, and a resume protocol for context truncation. This matches the anchor-5 example's validate → fix → retry structure; anchor 4 would require missing checkpoints. | 5 / 5 |
Progressive Disclosure | SKILL.md is a genuine overview: §10 gives a 'Load when' trigger table for all seven reference docs, §11 indexes the helper scripts, and inline summaries (naming conventions, token architecture) are backed by full references. All referenced files exist and references are exactly one level deep (they link only back to SKILL.md and to the sibling figma-use skill), matching the anchor-5 structure. It is not below 5 since no content that clearly belongs in a separate file is inlined. | 5 / 5 |
Total | 18 / 20 Passed |