design-philosophy

The VS Code design philosophy — a shared Values→Principles→Moves vocabulary for reasoning about UI in design terms instead of raw pixels. Use when designing, building, reviewing, or giving feedback on any visual surface; when deciding a radius, spacing, type role, icon size, border, color, or motion; or when translating a "this feels off" observation into a concrete, principled fix.

Quality

90%

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

Quality

Content

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

The body is highly actionable and well-structured, with concrete tokens, ramps, a do/don't phrasebook, and a clearly sequenced feeling→principle→move workflow reinforced by worked examples. Its main weakness is conciseness: the central framing is restated several times across sections, and implementation detail relies on external file references rather than a bundled reference file.

Suggestions

Tighten conciseness: the feeling→principle→move ordering is explained in the intro, the three-layers table, and the feedback section — consolidate to one canonical statement and reference it, cutting ~80-120 lines.

Move the full token tables/ramps into a references/ file (e.g. design-tokens.md) and keep SKILL.md as a lean overview with one-level-deep links, improving progressive_disclosure toward a 5.

Consider trimming the repeated 'What makes feedback hard to act on' and 'Lead with the feeling' subsections, which restate the phrasebook's guidance; a single feedback section would reduce redundancy.

Dimension	Reasoning	Score
Conciseness	The body is detailed and largely avoids explaining generic concepts Claude already knows, but at ~480 lines it repeats its core message many times — the feeling→principle→move ordering is restated in the intro, the three-layers table, worked examples, the phrasebook, and the feedback section — making it noticeably more padded than a lean reference; tightening the repetitive framing would earn a 4.	3 / 5
Actionability	It gives concrete, executable guidance: exact token names (--vscode-cornerRadius-small=4px, etc.), the spacing ramp values (0,2,4,6,8,10,12,16,20,24,28,32,36,40), the type roles and two-weight rule, icon sizes (16/12, 14 is a bug), the phrasebook of do/don't phrasings, and file paths — copy-paste ready and covering the common cases.	5 / 5
Workflow Clarity	The diagnostic workflow is explicitly sequenced with clear checkpoints: name the feeling → name the surface → name the principle broken → name the move → only then the number, reinforced by repeated worked examples (busy panel, boxed-in toolbar, flat settings row, mismatched dialogs, bouncing panel) that act as validation-style feedback loops for design review.	5 / 5
Progressive Disclosure	Structure is good — well-organized Values/Principles/Moves sections with clear headers and anchored cross-links, plus pointers to the real token files (baseSizes.ts, sizes.ts) and design-tokens.instructions.md at one level deep — but no references/scripts/assets bundle exists here, so the implementation detail (the full token reference) is pointed to externally rather than split into bundled files, leaving minor organization gaps versus a 5.	4 / 5
	Total	17 / 20 Passed

Description

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

This is an exemplary description: it explicitly states both what the skill is (a Values→Principles→Moves design vocabulary) and a rich set of natural 'Use when' triggers, with concrete UI terms users would actually say. It is concise yet comprehensive and uses appropriate third-person voice throughout.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions and design surfaces — 'designing, building, reviewing, or giving feedback on any visual surface' plus enumerating 'a radius, spacing, type role, icon size, border, color, or motion' and 'translating a this feels off observation into a concrete, principled fix' — giving comprehensive, specific coverage rather than generic verbs.	5 / 5
Completeness	Explicitly answers both what ('a shared Values→Principles→Moves vocabulary for reasoning about UI in design terms') and when ('Use when designing, building, reviewing, or giving feedback on any visual surface; when deciding a radius… ; or when translating a this feels off observation') with concrete trigger phrases, matching the 5-anchor example.	5 / 5
Trigger Term Quality	Includes the natural phrases a user would actually say ('designing', 'reviewing', 'giving feedback', 'this feels off') alongside concrete UI terms (radius, spacing, type role, icon size, border, color, motion), with good synonym coverage for visual-surface work.	5 / 5
Distinctiveness Conflict Risk	It carves a clear niche — VS Code design philosophy with a named Values→Principles→Moves vocabulary — and its triggers (radius/spacing/type role/icon tier decisions, 'this feels off' design feedback) are distinctive enough to avoid firing for unrelated skills.	5 / 5
	Total	20 / 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
relative_links	Relative link issues: 4 suspicious	Warning

	Total	15 / 16 Passed

Repository: posit-dev/positron
Path: .github/skills/design-philosophy/SKILL.md
Commit: b0258bc

Reviewed: 5 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.