design-md

Create and manage DESIGN.md files. Useful for capturing design direction, tokens, and visual rules in a single source of truth.

Quality

53%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

57%

Reviews 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-organized but thin catalogue stub: structurally clean (strong progressive disclosure) yet low on substance, deferring all real workflow to an upstream repo with only a URL-opening command and vague install guidance. It reads cleanly but does not instruct the agent how to actually create or manage a DESIGN.md.

Suggestions

Replace the verbatim-duplicated 'What it does' line and tighten the catalogue meta-prose to earn the conciseness anchor 3.

Add a minimal concrete starting point inline (e.g., a short DESIGN.md token/rule template or a real install command with actual paths) instead of deferring entirely to the upstream README.

Make the install-to-invoke sequence explicit and unambiguous by giving the exact bundle path and the concrete invocation step, raising workflow clarity.

Dimension	Reasoning	Score
Conciseness	The body is brief and does not explain concepts Claude already knows, but 'What it does' verbatim-duplicates the frontmatter description and 'How to use' spends tokens on catalogue meta-explanation, so it is mostly efficient rather than the every-token-earns-its-place anchor 3.	2 / 3
Actionability	It provides one concrete command ('open https://github.com/...') and a concrete invocation instruction ('invoke this skill by name (`design-md`)'), but the actual task guidance (creating/managing DESIGN.md files) is deferred to the upstream README with no executable code, matching 'some concrete guidance but incomplete; missing key details'.	2 / 3
Workflow Clarity	A loose install-then-invoke sequence is present, but step one ('install the upstream bundle ... Inspect the upstream README for exact paths') is vague and deferred, so the sequence exists without being unambiguous; not anchor 1 because a sequence is given, not anchor 3 because it is not concrete and checkpointed.	2 / 3
Progressive Disclosure	The body is under 50 lines with well-organized sections (What it does, Source, How to use), no local bundle files to mis-organize, and a single clearly-signaled one-level-deep external reference, satisfying the simple-skill allowance for a top score on organization.	3 / 3
	Total	9 / 12 Passed

Description

50%

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

The description is clear and domain-specific but moderate across the board: it states what the skill does without an explicit 'when to use' trigger clause and without comprehensive action or keyword coverage. Adding explicit trigger guidance and more concrete actions would lift it toward the top anchors.

Suggestions

Add an explicit 'Use when...' clause (e.g., 'Use when the user mentions DESIGN.md, design tokens, or visual rules') to satisfy the completeness and distinctiveness anchors.

Expand the action list beyond 'Create and manage' to specific concrete actions (e.g., 'capture design tokens, define visual rules, audit an existing DESIGN.md') to reach the specificity anchor 3.

Surface a broader set of natural trigger terms in the description itself rather than relying solely on the separate frontmatter triggers list.

Dimension	Reasoning	Score
Specificity	Names the domain ('DESIGN.md files') and two concrete verbs ('Create and manage') plus concrete content ('design direction, tokens, and visual rules'), but the 'Useful for capturing...' clause is a purpose statement rather than an additional action, so it is not the comprehensive multi-action list of anchor 3.	2 / 3
Completeness	It clearly answers 'what' ('Create and manage DESIGN.md files') but 'when' is only implied via 'Useful for capturing...'; there is no explicit 'Use when...' clause, which caps completeness at 2 per the guideline.	2 / 3
Trigger Term Quality	The description surfaces relevant natural terms ('DESIGN.md files', 'design direction', 'tokens', 'visual rules') but offers only moderate coverage of common variations; it is not the broad keyword set of anchor 3, yet well above the jargon-only anchor 1.	2 / 3
Distinctiveness Conflict Risk	It carves a niche around a specific artifact (DESIGN.md) and design-system domain, but without explicit triggers it could still overlap with general documentation or design skills, matching 'somewhat specific but could still overlap'.	2 / 3
	Total	8 / 12 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: nexu-io/open-design
Path: skills/design-md/SKILL.md
Commit: f2760fd

Reviewed: about 15 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.