design-md

Author/validate/export Google's DESIGN.md token spec files.

Quality

73%

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

Fix and improve this skill with Tessl

tessl review fix ./skills/creative/design-md/SKILL.md

Quality

Content

88%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 well-constructed skill body: executable commands with exit-code semantics, validation-gated authoring steps, a complete lint-rule reference, and genuinely non-obvious spec knowledge throughout. The only real costs are scattered version/date callouts and some duplication that could be tightened, plus inline reference material that could be split into bundle files.

Dimension	Reasoning	Score
Conciseness	The body is efficient and almost entirely spec-specific knowledge Claude would not already know (token formats, section order, lint rules, pitfalls), but time-sensitive callouts ("as of CLI 0.3.0", "as of Jul 2026") are scattered inline rather than isolated, and the typography sub-property list appears twice (token-types table and the pitfall entry). Anchor 4 (efficient, minor instances that could be trimmed) fits better than 5.	4 / 5
Actionability	All CLI commands are complete, copy-paste-ready npx invocations with comments and exit-code semantics, the authoring workflow gives concrete steps ("Write DESIGN.md in their project root"), and the lint rule reference enumerates all 9 rules with severities. Fully executable guidance covering the common cases — anchor 5.	5 / 5
Workflow Clarity	The authoring workflow is a clear numbered sequence with an explicit validation checkpoint and fix loop ("Lint it (see below). Fix any broken references or WCAG failures before returning"), and the lint/diff/export workflow documents exit codes (errors exit 1, regressions exit 1) so results can be gated. The operations are non-destructive, so the validation cap does not apply — anchor 5.	5 / 5
Progressive Disclosure	No bundle files exist and the single file is cleanly sectioned (anatomy, token types, section order, workflows, rules, pitfalls), but at ~205 lines the full anatomy template and the 9-rule lint reference are inlined core material that could arguably live in reference files. Anchor 4 (good structure, minor organization gaps) fits; not 5 since the body is well over the 50-line simple-skill threshold.	4 / 5
	Total	18 / 20 Passed

Description

58%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 terse, third-person, appropriately specific description that names concrete actions on a niche format. Its main weakness is the total absence of trigger guidance ("Use when..."), which both caps completeness and leaves its keyword coverage thin relative to the natural terms users would say.

Suggestions

Add a 'Use when...' clause (e.g. 'Use when the user asks for a DESIGN.md file, design tokens, or a design system spec, or wants to lint, diff, or export an existing one.') to answer 'when' explicitly and lift the completeness cap.

Include the natural synonyms users actually say — 'design system', 'design tokens', 'accessibility/WCAG contrast', 'Tailwind' — to improve trigger-term coverage.

Mention the diff capability ('diff two versions for regressions') so the action list matches what the skill actually does.

Dimension	Reasoning	Score
Specificity	"Author/validate/export Google's DESIGN.md token spec files" names the domain and three concrete actions (author, validate, export), matching anchor 4. Not 5 because coverage has minor gaps — the diff capability documented in the body is omitted.	4 / 5
Completeness	The "what" is clear (author/validate/export DESIGN.md files) but there is no "Use when..." clause or equivalent explicit trigger guidance, which per the judging guidelines caps completeness at 3. Anchor 3 (clear what, when missing) is a better fit than 4, which requires both present.	3 / 5
Trigger Term Quality	"DESIGN.md", "token spec", "validate", and "export" are relevant keywords, but common natural phrasings users would say — "design system", "design tokens", "accessibility", "WCAG", "Tailwind" — are missing, matching anchor 3 (some relevant keywords, missing variations and synonyms).	3 / 5
Distinctiveness Conflict Risk	"Google's DESIGN.md token spec files" is a clear niche format with mostly distinct triggers, but "token spec files" carries minor overlap risk with general design-system/design-token skills (e.g. claude-design, popular-web-designs), matching anchor 4 rather than 5.	4 / 5
	Total	14 / 20 Passed

Validation

81%

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 — 13 / 16 Passed

Validation for skill structure

Criteria	Description	Result
metadata_version	'metadata.version' is missing	Warning
metadata_field	'metadata' should map string keys to string values	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	13 / 16 Passed

Repository: NousResearch/hermes-agent
Path: skills/creative/design-md/SKILL.md
Commit: 68fa7e9

Reviewed: 3 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.