Content
78%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, actionable overview that leans on tables and concrete commands rather than padding, and points one level deep to script-generated references. Its main weakness is mild repetition across the token-rule sections, which keeps conciseness just below excellent.
Suggestions
Consolidate the 'CRITICAL RULE: Always Use Design Tokens', 'When encountering absolute values', and 'Token usage priority' sections to remove overlapping guidance and tighten conciseness.
Add a small runnable Vue 2.7 render example (e.g., a GlButton with category/variant props) to make the import snippet fully copy-paste ready and lift actionability.
Add an explicit 'if peer-dependency verification fails, adjust the scaffold and re-verify' feedback loop to the scaffold workflow to match the validation rigor of a score-5 workflow.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Largely efficient — tables, imperative directives, and no padding about what a design system is — but the absolute-value rules, the 'When encountering absolute values' steps, and the 'Token usage priority' list overlap slightly and could be tightened. Fits the score-4 anchor (efficient, minor over-explanation to trim); not 5 due to that repetition. | 4 / 5 |
Actionability | Provides concrete executable commands ('npm info @gitlab/ui peerDependencies --json', 'bash scripts/update-refs.sh'), specific token names, a runnable import snippet, and a 5-step Figma lookup chain. Mostly copy-paste ready with minor gaps (no full Vue render example), matching score-4. | 4 / 5 |
Workflow Clarity | Clear sequenced workflows for initialization, scaffolding (check peerDeps → pick scaffold → verify), component lookup, and Figma matching, with an explicit 'Verify after install' checkpoint and a token-resolution feedback loop. Not score-5 because the scaffold flow lacks an explicit fix-and-revalidate loop, but well above score-3. | 4 / 5 |
Progressive Disclosure | SKILL.md is a well-signaled overview pointing one level deep to references via a token-reference table and SSoT reference columns; the referenced paths (component-index.md, design-tokens/token-map.md, tokens.css) are confirmed to be produced by the bundled scripts, and content is appropriately split. Matches the score-5 anchor. | 5 / 5 |
Total | 17 / 20 Passed |