design-md

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

Quality

50%

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

47%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.

This SKILL.md is a lean, well-sectioned catalogue entry rather than an operational skill: it advertises an upstream bundle but provides no executable install steps and defers all real content to an external GitHub repository. The result is a body that is easy to read but not actionable on its own.

Suggestions

Replace 'install the upstream bundle into your active agent's skills directory' with concrete, executable commands (e.g. a git clone command with the actual skills-directory path) so the core step can be performed without browsing the upstream README.

Either inline the essential upstream workflow (the minimal steps to create a DESIGN.md) or vendor the upstream references into local files, so the skill does not depend entirely on an external URL.

Drop the frontmatter-duplicating 'Source' and 'What it does' duplication (or merge them into one short line) to make the remaining body purely instructional.

Dimension	Reasoning	Score
Conciseness	The ~25-line body is short and sectioned with no concept explanations, respecting the token budget; the 'What it does' section repeats the frontmatter description verbatim and the Source section duplicates frontmatter metadata, which are minor trims. Not a 5 because that duplicated frontmatter content does not earn its place; not a 3 because there is no over-explanation or padding.	4 / 5
Actionability	Concrete guidance is minimal: 'install the upstream bundle into your active agent's skills directory' gives no actual install command or path, and the only code block (`open https://github.com/...`) merely opens a browser rather than executing the task. It rises above a 1 because it does give a URL and an explicit invocation instruction ('invoke this skill by name (`design-md`)'), but the steps needed to actually accomplish anything are missing.	2 / 5
Workflow Clarity	A rough sequence exists (inspect upstream README → install bundle → invoke by name), but the critical step — how to install the bundle — is undefined, and there are no checkpoints or validation of a successful install. Not a 1 because the three steps are at least loosely ordered and coherent; not a 3 because the gaps are not merely missing validation, the central step itself is unspecified.	2 / 5
Progressive Disclosure	The body has clear sections (What it does / Source / How to use) and one clearly-signaled external pointer (the upstream repo) with no nested local references; no bundle files exist to misorganize. Not a 5 because all substantive content is deferred to an external URL rather than an in-bundle reference, so the skill functions as a pointer with no locally disclosable detail.	4 / 5
	Total	12 / 20 Passed

Description

53%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.

The description states a clear, third-person "what" with a concrete artifact list, but has no explicit "use when" trigger guidance and only partial coverage of natural trigger vocabulary. It sits just above the midpoint: functional, but below the quality of the reference good examples.

Suggestions

Append an explicit 'Use when...' clause, e.g. "Use when the user mentions DESIGN.md, a design doc, design tokens, or capturing visual rules/style decisions in one place."

Fold natural trigger synonyms into the description (design doc, style guide, design system documentation) so the description itself — not just the frontmatter triggers list — carries discoverable keywords.

Sharpen the action verbs beyond 'create and manage' (e.g. 'scaffold, update, and audit DESIGN.md files').

Dimension	Reasoning	Score
Specificity	"Create and manage DESIGN.md files" plus "capturing design direction, tokens, and visual rules" names the domain and 1-2 concrete actions with specific outputs, but the verbs (create, manage, capture) stay generic and coverage is not comprehensive. It is not a 4 because it lacks the several distinct concrete actions of the anchor example (extracts text, fills forms, converts pages), and not a 2 because the enumerated artifacts (tokens, visual rules) go beyond a bare domain mention.	3 / 5
Completeness	The "what" is clear (create/manage DESIGN.md files capturing direction, tokens, visual rules), but there is no "when" guidance in the description at all — the "Useful for..." clause describes purpose, not triggering conditions, and the 'Use when' cap at 3 applies. It is not a 2 because the "what" half is concrete, not vague.	3 / 5
Trigger Term Quality	The description contains relevant keywords ("DESIGN.md", "design direction", "tokens", "visual rules") but misses common variations and synonyms users would naturally say, such as "design system", "design doc", "style guide", or "design tokens doc". Not a 4 because a user asking for a style guide or design-system documentation would not naturally match this text.	3 / 5
Distinctiveness Conflict Risk	DESIGN.md files and design tokens/visual rules documentation occupy a fairly distinct niche with little chance of firing for the wrong skill. Not a 5 because "design direction" and "tokens" could overlap with general branding/styling or design-system skills, leaving minor overlap risk.	4 / 5
	Total	13 / 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: nexu-io/open-design
Path: skills/design-md/SKILL.md
Commit: 1b47e60

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.