design-system

Captures the user's brand identity once via a 10-question onboarding wizard (primary/accent HEX + heading + body Google Fonts + design style editorial/technical/minimal/playful + default output directory + syntax theme + TOC behavior + optional logo/company), validates body-text and link contrast against WCAG 2.2 AA, derives 12 CSS custom properties in HSL space, and stores the result for every markdown-html converter to consume. Use before any markdown-html conversion. Triggers on first-run onboarding ("set up the brand", "configure markdown-html", "run onboarding"), on explicit reset ("reset the design system", "re-onboard"), and is checked by every converter via config_loader.py before rendering. Refuses to save if body-text contrast fails AA 4.5:1 or the output dir isn't writable. Precedence is project (./.markdown-html/) > global (~/.config/markdown-html/) > built-in defaults; MARKDOWN_HTML_NO_CONFIG=1 bypasses.

Quality

85%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

—

The risk profile of this skill

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 body with strong validation checkpoints and copy-paste commands. Its weaknesses are verbosity from restating the question set as a forcing-question library and orphaned reference bundle files that the body never points to.

Suggestions

Link the three references/*.md files from the body (e.g., a '## References' entry like '**WCAG canon**: See [references/wcag_accessibility.md]') so the bundled canon docs are discoverable rather than orphaned.

Collapse the 'Forcing-question library' section into the 'Onboarding question set' table or move it to a reference file — it restates the same 10 questions with book citations and adds length without new executable guidance.

Trim the 'Distinct from' section to one line per sibling skill; the current paragraph-level detail on token taxonomies is more than the overview needs.

Dimension	Reasoning	Score
Conciseness	The body is information-dense and mostly earns its tokens, but ~155 lines include redundant layers — the 10-question table is restated as a 'forcing-question library' with book citations, and the 'Distinct from' section disambiguates sibling repos — that could be tightened without losing guidance.	3 / 5
Actionability	Fully executable throughout: exact commands like 'python3 .../onboard.py --set brand.primary=#FF6B35 --set design_style=editorial', concrete exit codes (3, 4), specific defaults, and a copy-paste worked-example block covering the common cases.	5 / 5
Workflow Clarity	Clear sequence via the 'When to invoke' table and 'Hard rules' with explicit validation checkpoints and feedback loops — contrast validation after every change, writable-dir check, refuse-to-save with recovery guidance — so the destructive/batch cap does not apply.	5 / 5
Progressive Disclosure	Section structure is clear, but three bundle files in references/ (design_token_canon.md, typography_pairing.md, wcag_accessibility.md) are present yet never linked or signaled from the body — the bottom 'References' list points to external books and sibling-repo scripts instead, leaving the local canon docs orphaned.	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 dense, specific description that names concrete actions, explicit triggers, and guard conditions (WCAG contrast, writable output dir, env bypass). It clearly answers both what and when with minimal conflict risk; the only soft spot is trigger-term breadth, which favors quoted phrases over plain synonyms.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'Captures... via a 10-question onboarding wizard', 'validates body-text and link contrast against WCAG 2.2 AA', 'derives 12 CSS custom properties in HSL space', 'stores the result', 'Refuses to save if body-text contrast fails' — covering capture, validation, derivation, storage, and guard behavior comprehensively.	5 / 5
Completeness	Explicitly answers both what (capture/validate/derive/store brand identity) and when ('Triggers on first-run onboarding...', 'on explicit reset', 'checked by every converter via config_loader.py before rendering'), with concrete trigger phrases throughout.	5 / 5
Trigger Term Quality	Includes natural trigger phrases users would say — 'set up the brand', 'configure markdown-html', 'run onboarding', 'reset the design system', 're-onboard' — giving good coverage, though it leans on quoted phrases and omits plain synonyms or file extensions that would push it to a 5.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear niche as the shared brand owner for the markdown-html plugin with distinct triggers ('set up the brand', 'configure markdown-html'), minimizing overlap with other skills.	5 / 5
	Total	19 / 20 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: alirezarezvani/claude-skills
Path: markdown-html/skills/design-system/SKILL.md
Commit: 19392f7

Reviewed: ~2 hours 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.