design-system

Section-by-section GDD authoring for one system — walks through each required section, cross-references dependencies.

Quality

63%

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

Quality

Content

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

An extremely actionable, well-validated workflow whose main weaknesses are token efficiency and file organization: heavy repetition of guard blocks, narrative justification of past fixes, and monolithic inlining of material that belongs in reference files. The tier/mode conditional logic is thorough but resolved through prose patches rather than a single decision table, which taxes the reader.

Suggestions

Define the review-mode check once (e.g. a short table mapping section → specialist → solo/lean/full behavior) and reference it from each section instead of repeating the block seven times.

Move the GDD skeleton template and the specialist routing tables into references/ files (e.g. references/gdd-skeleton.md, references/agent-routing.md) and link them, cutting SKILL.md to an orchestration overview.

Compress the post-mortem blockquotes to the operative rule ('X happened; therefore do Y') and consolidate the tier-conditional logic into a single decision table near §1 so §3, §4, and §5a can cite it instead of restating and patching it.

Dimension	Reasoning	Score
Conciseness	The body is noticeably verbose: the review-mode-check block is repeated nearly verbatim in Sections B, C, D, E, G, H and the optional-sections block; long post-mortem blockquotes recount past agent failures to justify rules; and the tier rules of §1 are restated in §3, §4, and §5a. It is operational rather than filler, so it is not severely verbose — but the padding is pervasive rather than occasional.	2 / 5
Actionability	Fully executable guidance throughout: exact AskUserQuestion prompts and option texts, ready-to-run Grep invocations with patterns, globs, and flags, a precise Edit old_string/new_string pattern with an anti-ambiguity rule, the complete skeleton template, category-keyed routing tables, and exact status strings to write.	5 / 5
Workflow Clarity	Phases 1–7 are clearly sequenced with explicit validation (registry conflict check, 5a self-check, feasibility pre-check, per-section approval gates, fail-fast error messages) and a Recovery & Resume section. However, the nested tier/automation/override logic is reconciled through scattered prose corrections ('read every list below as...', '§1 wins: at minimal both drop to optional'), so a reader must untangle conditionals the base workflow does not itself encode.	4 / 5
Progressive Disclosure	The skill has good internal structure (numbered phases, per-section headers) and its project-file references are one level deep, but there are no bundle files at all — the 77-line skeleton template, per-section guidance, and specialist routing tables are inlined content that clearly belongs in references/ files for a ~1,280-line skill.	3 / 5
	Total	14 / 20 Passed

Description

50%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 communicates a clear, moderately specific 'what' but entirely omits the 'when'. A user asking to design a system or write a game design document would not be reliably routed here on these trigger terms alone.

Suggestions

Add an explicit trigger clause, e.g. 'Use when the user asks to design a game system, write or fill out a GDD (game design document), or retrofit an existing GDD's missing sections.'

Spell out 'GDD (game design document)' at least once so users and skill-matching are not dependent on knowing the acronym.

Include one or two distinguishing boundaries (e.g. 'for authoring one system at a time — not for reviewing or mapping systems') to reduce overlap with the adjacent /design-review and /map-systems skills.

Dimension	Reasoning	Score
Specificity	The description names its domain ('GDD authoring') and two concrete actions ('walks through each required section', 'cross-references dependencies'), but coverage is not comprehensive — skeleton creation, registry updates, feasibility checks, and specialist routing are absent, and 'GDD' is never expanded.	3 / 5
Completeness	The 'what' is clear (section-by-section GDD authoring with dependency cross-referencing), but the 'when' is entirely missing — there is no 'Use when...' clause or equivalent trigger guidance, which caps completeness at 3.	3 / 5
Trigger Term Quality	It contains some relevant keywords ('GDD', 'system', 'authoring'), but misses the natural phrases a user would actually say — 'design a system', 'write a game design document', 'game design doc' — and offers no synonyms or variations.	3 / 5
Distinctiveness Conflict Risk	'GDD authoring for one system' carves a niche versus review or mapping skills, but with no usage boundary stated it could plausibly trigger for adjacent GDD-related skills (/design-review, /map-systems, /consistency-check) in the same suite.	3 / 5
	Total	12 / 20 Passed

Validation

81%

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 — 13 / 16 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (1289 lines); consider splitting into references/ and linking	Warning
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	13 / 16 Passed

Repository: Donchitos/Claude-Code-Game-Studios
Path: .claude/skills/design-system/SKILL.md
Commit: b21fa0f

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.