Content
63%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.
The body is a well-structured, domain-specific instruction document with a concrete I/O contract, decision rules, and validation/convergence checkpoints. Its weaknesses are a dangling reference to a nonexistent examples file, meta-commentary about expected accuracy that adds tokens without adding instruction, and example material inlined where a one-level-deep reference would be cleaner.
Suggestions
Fix or remove the reference to examples/semantic-inference-before-after.json — the file does not exist in the skill bundle, so the pointer is currently unusable.
Trim the meta-commentary ("This deterministic v1 atom does not claim a measured accuracy lift by itself... Real accuracy numbers require a fixture suite...") — it explains expectations rather than instructing, and the Before/after section already demonstrates the improvement.
Move the before/after examples and the reasoning-note jsonc blocks into a one-level-deep reference file (e.g., references/semantic-inference-examples.md) and keep only the decision rules in SKILL.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with domain-novel content (semantic inference evidence types, mapping rules) but includes unnecessary material: the hedging paragraph "This deterministic v1 atom does not claim a measured accuracy lift by itself... Real accuracy numbers require a fixture suite" is meta-commentary, and the Before/after section largely re-treads the earlier reasoning-note example. Mostly efficient but could be tightened — anchor 3, not 4. | 3 / 5 |
Actionability | Concrete guidance throughout: exact input paths ("figma/tokens.json from figma-extract", "code/tokens.json from design-extract"), a full output contract with per-file schemas, explicit decision rules ("map to an active design-system token only when the evidence is role-based, not value-only"), and a jsonc reasoning-note example. Falls short of 5 because the actual 'executable mapping pass' mechanics are deferred to the implementation file without a concrete procedure here. | 4 / 5 |
Workflow Clarity | A clear sequence (inputs → semantic role inference → map/unmatched decision → write bucket files) with real validation checkpoints: the unmatched.json human-review audit, the explicit convergence criterion ("every input token is either mapped or explicitly recorded under unmatched.json with a non-empty reason"), and the strict/soft-converge evaluator behavior. Minor gaps only — steps are organized as sections rather than an ordered procedure — so anchor 4 rather than 5. | 4 / 5 |
Progressive Disclosure | Sections are clearly headed, but there is no bundle (no references/, scripts/, or assets/), yet the body points to "examples/semantic-inference-before-after.json" which does not exist in the skill directory — a dangling reference. Additionally, the inlined before/after and reasoning-note example blocks are content that could live in a separate reference file. This matches anchor 3: some structure, references not clearly signaled, content that should be separate is inline. | 3 / 5 |
Total | 14 / 20 Passed |