6.5 KiB
Skill Test Spec: /asset-spec
Skill Summary
/asset-spec generates per-asset visual specification documents from design
requirements. It reads the relevant GDD, art bible, and design system to produce
a structured asset spec sheet that defines: dimensions, animation states (if
applicable), color palette reference, style notes, technical constraints
(format, file size budget), and deliverable checklist.
Spec sheets are written to assets/specs/[asset-name]-spec.md after a "May I write"
ask. If a spec already exists, the skill offers to update it. When multiple assets
are requested in a single invocation, a "May I write" ask is made per asset. No
director gates apply. The verdict is COMPLETE when all requested specs are written.
Static Assertions (Structural)
Verified automatically by /skill-test static — no fixture needed.
- Has required frontmatter fields:
name,description,argument-hint,user-invocable,allowed-tools - Has ≥2 phase headings
- Contains verdict keyword: COMPLETE
- Contains "May I write" collaborative protocol language (per asset)
- Has a next-step handoff (e.g., assign to an artist, or
/asset-auditlater)
Director Gate Checks
None. /asset-spec is a design documentation utility. Technical artists may
review specs separately but this is not a gate within this skill.
Test Cases
Case 1: Happy Path — Enemy sprite spec with full GDD and art bible
Fixture:
design/gdd/enemies.mdexists with enemy variants defineddesign/art-bible.mdexists with color palette and style notes- No existing asset spec for "goblin-enemy"
Input: /asset-spec goblin-enemy
Expected behavior:
- Skill reads enemies GDD and art bible
- Skill generates a spec for the goblin enemy sprite:
- Dimensions: inferred from engine defaults or explicitly from GDD
- Animation states: idle, walk, attack, hurt, death
- Color palette reference: links to art-bible palette section
- Style notes: from art bible character design rules
- Technical constraints: format (PNG), size budget
- Deliverable checklist
- Skill asks "May I write to
assets/specs/goblin-enemy-spec.md?" - File written on approval; verdict is COMPLETE
Assertions:
- All 6 spec components are present (dimensions, animations, palette, style, tech, checklist)
- Color palette reference links to art bible (not duplicated)
- Animation states are drawn from GDD (not invented)
- "May I write" is asked with the correct path
- Verdict is COMPLETE
Case 2: No Art Bible Found — Spec with Placeholder Style Notes, Dependency Flagged
Fixture:
design/gdd/player.mdexistsdesign/art-bible.mddoes NOT exist
Input: /asset-spec player-sprite
Expected behavior:
- Skill reads player GDD but cannot find the art bible
- Skill generates spec with placeholder style notes: "DEPENDENCY GAP: art bible not found — style notes are placeholders"
- Color palette section uses: "TBD — see art bible when created"
- Skill asks "May I write to
assets/specs/player-sprite-spec.md?" - File written with placeholders and dependency flag; verdict is COMPLETE with advisory
Assertions:
- DEPENDENCY GAP is flagged for the missing art bible
- Spec is still generated (not blocked)
- Style notes contain placeholder markers, not invented styles
- Verdict is COMPLETE with advisory note
Case 3: Asset Spec Already Exists — Offers to Update
Fixture:
assets/specs/goblin-enemy-spec.mdalready exists- GDD has been updated since the spec was written (new attack animation added)
Input: /asset-spec goblin-enemy
Expected behavior:
- Skill detects existing spec file
- Skill reports: "Asset spec already exists for goblin-enemy — checking for updates"
- Skill diffs GDD against existing spec and identifies: new "charge-attack" animation state added in GDD but not in spec
- Skill presents the diff: "1 new animation state found — offering to update spec"
- Skill asks "May I update
assets/specs/goblin-enemy-spec.md?" (not overwrite) - Spec is updated; verdict is COMPLETE
Assertions:
- Existing spec is detected and "update" path is offered
- Diff between GDD and existing spec is shown
- "May I update" language is used (not "May I write")
- Existing spec content is preserved; only the diff is applied
- Verdict is COMPLETE
Case 4: Multiple Assets Requested — May-I-Write Per Asset
Fixture:
- GDD and art bible exist
- User requests specs for 3 assets: goblin-enemy, orc-enemy, treasure-chest
Input: /asset-spec goblin-enemy orc-enemy treasure-chest
Expected behavior:
- Skill generates all 3 specs in sequence
- For each asset, skill shows the draft and asks "May I write to
assets/specs/[name]-spec.md?" individually - User can approve all 3 or skip individual assets
- All approved specs are written; verdict is COMPLETE
Assertions:
- "May I write" is asked 3 times (once per asset), not once for all
- User can decline one asset without blocking the others
- All 3 spec files are written for approved assets
- Verdict is COMPLETE when all approved specs are written
Case 5: Director Gate Check — No gate; asset-spec is a design utility
Fixture:
- GDD and art bible exist
Input: /asset-spec goblin-enemy
Expected behavior:
- Skill generates and writes the asset spec
- No director agents are spawned
- No gate IDs appear in output
Assertions:
- No director gate is invoked
- No gate skip messages appear
- Verdict is COMPLETE without any gate check
Protocol Compliance
- Reads GDD, art bible, and design system before generating spec
- Includes all 6 spec components (dimensions, animations, palette, style, tech, checklist)
- Flags missing dependencies (art bible, GDD) with DEPENDENCY GAP notes
- Asks "May I write" (or "May I update") per asset
- Handles multiple assets with individual write confirmations
- Verdict is COMPLETE when all approved specs are written
Coverage Notes
- Audio asset specs (sound effects, music) follow the same structure with different fields (duration, sample rate, looping) and are not separately tested.
- UI asset specs (icons, button states) follow the same flow with interaction state requirements aligned to the UX spec.
- The case where GDD is also missing (neither GDD nor art bible exists) is not separately tested; spec would be generated with both dependency gaps flagged.