create-design-md

Create or update a DESIGN.md from an existing product repository or public website. Use when asked to document an interface's design language, reconstruct its visual system, extract design tokens and guidance from current evidence, or give coding agents persistent UI context. Do not modify product source or promote accidental implementation patterns into design decisions.

Quality

85%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

77%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A highly actionable, well-sequenced workflow with strong validation feedback loops, but it is a long single-file rule book with noticeable internal redundancy and no progressive disclosure to external reference files for the schema/format contract details.

Suggestions

Move the format contract (canonical typography fields, token-name regex, export-family verification mappings, frontmatter shape rules) into a references/ file and link to it from SKILL.md to improve progressive disclosure and reduce body length.

Deduplicate the repeated guidance across sections 2–4 (rounded.base example, canonical typography field list, omission gates) so each rule appears once.

Consider folding the repository-vs-URL evidence rules into a shared subsection to avoid restating the three-proof gate and omission criteria in multiple places.

Dimension	Reasoning	Score
Conciseness	The body is directive and assumes Claude's competence (no padding with basic concepts), but it restates the same rules multiple times — the rounded.base example, canonical typography fields, and omission gates each recur across sections 2–4 — so it could be tightened noticeably.	3 / 5
Actionability	Provides copy-paste-ready commands (npx @google/design.md spec/lint/export/diff), concrete YAML frontmatter and typography examples, an explicit token-name regex, and a fixed export-target mapping (css-tailwind/json-tailwind/dtcg) covering the common cases.	5 / 5
Workflow Clarity	A clear six-step sequence (mode → evidence → decide → write → validate → report) with explicit validation checkpoints (lint, export, diff) and feedback loops ("rewrite the frontmatter and rerun validation until the category is emitted"), plus a final no-op deletion checklist.	5 / 5
Progressive Disclosure	No bundle files exist and the ~250-line body is a single monolithic document; the detailed format contract (canonical field lists, token-name regex, export-family verification) is reference-like material that is inlined rather than split into a one-level-deep reference file.	3 / 5
	Total	16 / 20 Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, third-person description that explicitly covers what the skill does and when to invoke it, with concrete actions and minimal conflict risk. It could add a few synonyms (design system, style guide) to push trigger-term coverage to fully comprehensive.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — "Create or update a DESIGN.md", "document an interface's design language", "reconstruct its visual system", "extract design tokens and guidance", "give coding agents persistent UI context" — giving comprehensive coverage of the skill's capabilities.	5 / 5
Completeness	Explicitly answers both what ("Create or update a DESIGN.md from an existing product repository or public website") and when ("Use when asked to document an interface's design language, reconstruct its visual system, extract design tokens and guidance...") with concrete trigger phrases.	5 / 5
Trigger Term Quality	Good coverage of natural phrases a user would say ("design language", "design tokens", "visual system", "DESIGN.md", "public website"), but a few common synonyms such as "design system", "style guide", or "theme" are absent, keeping it just below comprehensive.	4 / 5
Distinctiveness Conflict Risk	The DESIGN.md artifact and design-token/visual-system reconstruction framing carves a clear niche with distinct triggers; the only mild breadth ("persistent UI context") does not create meaningful conflict with other skills.	5 / 5
	Total	19 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: ibelick/ui-skills
Path: skills/create-design-md/SKILL.md
Commit: f5dd1de

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.