substack-ui-skills
Substack's UI design system. Use when building interfaces inspired by Substack's aesthetic - light mode, Inter font, 4px grid.
70
62%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/substack/SKILL.mdQuality
Discovery
75%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 has strong completeness with an explicit 'Use when' clause and is highly distinctive due to the Substack brand specificity. However, it lacks concrete action verbs describing what the skill actually does (e.g., generates components, styles layouts) and could benefit from additional natural trigger terms users might use when seeking this skill.
Suggestions
Add specific concrete actions the skill performs, e.g., 'Generates UI components, styles layouts, and applies typography following Substack's design system.'
Expand trigger terms to include variations users might say, such as 'newsletter-style UI', 'Substack-like design', 'clean minimal publishing interface', or 'reading-focused layout'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (UI design system) and mentions some specific elements (light mode, Inter font, 4px grid), but doesn't list concrete actions like 'create layouts', 'style components', or 'generate CSS'. It describes attributes rather than actions. | 2 / 3 |
Completeness | Clearly answers both what ('Substack's UI design system') and when ('Use when building interfaces inspired by Substack's aesthetic') with explicit trigger guidance including specific parameters. | 3 / 3 |
Trigger Term Quality | Includes 'Substack' and some design terms like 'light mode', 'Inter font', '4px grid', but misses common user terms like 'newsletter design', 'Substack-style', 'clean typography', 'minimal UI', or 'publishing platform design'. | 2 / 3 |
Distinctiveness Conflict Risk | Highly distinctive - 'Substack' is a very specific brand reference, and the combination of 'Substack's aesthetic', 'Inter font', and '4px grid' creates a clear niche that is unlikely to conflict with other design system skills. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
50%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides a structured design system reference with clear semantic tokens, typography rules, and interaction guidelines using MUST/SHOULD/NEVER conventions. However, it appears to contain auto-extracted values with obvious errors (0px input height, orange as card background, light teal as heading color) that would lead Claude to produce incorrect implementations. The lack of executable code examples and the presence of raw detection artifacts reduce its practical value.
Suggestions
Fix clearly incorrect values: surface-raised should not be #FC5013 (orange) for cards/modals, input height should not be 0px, and heading-1 color #BCDBD7 (light teal) seems wrong for a Substack-style design.
Add 1-2 executable code snippets showing how to compose a typical component (e.g., a card or button) using these tokens, either in Tailwind or CSS.
Remove raw detection artifacts ('currently 15 colors detected', 'used 43x', 'Count' column) that don't provide actionable guidance.
Consider splitting the detailed token tables and text style references into a separate REFERENCE.md file, keeping SKILL.md as a concise overview with the most critical constraints.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill contains useful design tokens and constraints, but includes redundant information (e.g., listing RGB alongside HEX, the 'Count' column in text styles, repeating border-radius scale twice, listing all detected font sizes including 5px/9px which seem irrelevant). The raw detection artifacts ('currently 15 colors detected', 'currently 4 detected', 'used 43x') add noise without actionable value. | 2 / 3 |
Actionability | Provides concrete values (hex codes, pixel sizes, specific CSS properties) which is good, but lacks executable code examples showing how to implement these patterns. Some values seem auto-extracted and contradictory (e.g., input height of '0px', surface-raised being orange #FC5013 which is clearly wrong for cards/modals, heading-1 color #BCDBD7 which is a light teal). These errors undermine trust and actionability. | 2 / 3 |
Workflow Clarity | The 'When to Apply' section provides clear triggers, and the MUST/SHOULD/NEVER convention creates clear priority levels. However, there's no workflow for how to actually build a component or page using these guidelines - it's purely a reference document with no sequencing or validation steps for ensuring design consistency. | 2 / 3 |
Progressive Disclosure | Content is organized into logical sections with clear headers, which is good. However, the document is quite long and monolithic - the detailed token tables, text style references, and component specifications could be split into separate reference files. No external file references are provided for deeper dives. | 2 / 3 |
Total | 8 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- ihlamury/design-skills
- Commit
126714e
- Reviewed
Table of Contents
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.