design-md

Analyze Stitch projects and synthesize a semantic design system into DESIGN.md files

Quality

45%

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/design-md/SKILL.md

Quality

Content

46%Scale 1-5

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

The skill provides a reasonably actionable workflow for analyzing Stitch projects and generating DESIGN.md files, with good specificity around MCP tool usage and output format. However, it suffers from significant verbosity with redundant sections (Goal repeats Overview, Tips/Pitfalls restate earlier guidance), and lacks validation checkpoints in the workflow. The monolithic structure would benefit from splitting reference material into supporting files.

Suggestions

Remove redundant sections: merge 'The Goal' into 'Overview', consolidate 'Best Practices', 'Tips for Success', and 'Common Pitfalls' into a single concise section or move to a separate reference file.

Add a validation checkpoint after generating DESIGN.md, such as verifying all extracted colors have both hex codes and descriptive names, and that all five output sections are populated.

Split the output format template and detailed analysis instructions into a separate reference file (e.g., DESIGN_TEMPLATE.md) to reduce the main skill's length and improve progressive disclosure.

Remove the 'When to Use This Skill' section entirely—it restates the skill description and adds no actionable value.

Dimension	Reasoning	Score
Conciseness	The skill is noticeably verbose with significant redundancy. 'The Goal' section repeats the Overview almost verbatim. 'Tips for Success' and 'Common Pitfalls to Avoid' sections explain things Claude already knows (e.g., 'Start with the big picture,' 'Look for patterns'). 'Best Practices' largely restates guidance already given in the Analysis & Synthesis section. The 'When to Use This Skill' section is also redundant with the description.	2 / 5
Actionability	The Retrieval and Networking section provides concrete, specific MCP tool calls with parameter details and field paths. The Analysis & Synthesis section gives clear extraction steps with examples. However, the Usage Example section is vague pseudo-instructions rather than executable commands, and there's no actual executable code—just descriptions of what to call. The output template is concrete and copy-paste ready.	4 / 5
Workflow Clarity	The retrieval steps (1-6) are clearly sequenced with specific tool calls and parameter formats. The analysis steps (1-5) provide a logical sequence. However, there are no validation checkpoints—no step to verify that retrieved data is complete, that color extraction is accurate, or that the generated DESIGN.md meets quality criteria before finalizing. For a document generation workflow, a review/validation step is missing.	3 / 5
Progressive Disclosure	The entire skill is a monolithic document with no bundle files or references to supporting materials (beyond an external URL). Content like the detailed output format template, common pitfalls, best practices, and tips could be split into separate reference files. The external prompting guide link is mentioned but not structured as a clear progressive disclosure reference. Everything is inlined in one long file.	2 / 5
	Total	11 / 20 Passed

Description

45%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 identifies a specific domain (Stitch projects) and a concrete output (DESIGN.md files), giving it reasonable distinctiveness. However, it lacks a 'Use when...' clause, provides minimal detail about what the analysis and synthesis actually involve, and misses natural trigger terms users might employ when requesting this kind of work.

Suggestions

Add an explicit 'Use when...' clause with trigger phrases like 'Use when the user asks to generate a design system, extract design tokens, or create a DESIGN.md from a Stitch project.'

Expand the capability description with specific actions, e.g., 'Extracts design tokens, documents component patterns, maps typography and color palettes from Stitch projects into a structured DESIGN.md file.'

Include natural synonyms and related terms users might say, such as 'style guide', 'design tokens', 'component documentation', 'UI system'.

Dimension	Reasoning	Score
Specificity	Names the domain ('Stitch projects', 'semantic design system') and two concrete actions ('analyze' and 'synthesize'), but doesn't elaborate on what analysis or synthesis entails—no mention of specific sub-tasks like extracting tokens, documenting components, mapping typography, etc.	3 / 5
Completeness	Provides a 'what' (analyze Stitch projects and synthesize a design system into DESIGN.md files) but has no explicit 'when' clause or trigger guidance. Per rubric guidelines, a missing 'Use when...' clause caps completeness at 3, and the 'what' itself is only moderately clear, placing this at a 2.	2 / 5
Trigger Term Quality	Includes some relevant keywords like 'Stitch projects', 'design system', and 'DESIGN.md', but misses natural user phrases and synonyms (e.g., 'design tokens', 'style guide', 'component library', 'UI patterns'). 'Stitch' is a niche term that helps with distinctiveness but limits discoverability if users phrase requests differently.	3 / 5
Distinctiveness Conflict Risk	The combination of 'Stitch projects', 'semantic design system', and 'DESIGN.md' creates a fairly distinct niche. There's minor overlap risk with general design system or documentation skills, but the specific tool name and output file format help differentiate it.	4 / 5
	Total	12 / 20 Passed

Validation

90%

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 — 10 / 11 Passed

Validation for skill structure

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

	Total	10 / 11 Passed

Repository: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: skills/design-md/SKILL.md
Commit: 57c135b

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.