Build Design Skill Package

Turn proven design practice into a compact decision system that an agent can route, execute, and evaluate. Keep the entry file short; place detailed knowledge and deterministic assets in the resource type that matches how they are consumed.

Load the base creator

Load and follow the environment's skill-creator Skill before creating or editing a Skill package. Use its naming, frontmatter, metadata, validation, and packaging rules as the base contract.

This Skill adds a design-specific knowledge architecture. It does not replace the base creator or authorize publishing, installing, or pushing a Skill unless the user requested that action.

Choose the package profile

Use the smallest profile that makes the design decision reproducible:

Do not create a directory until it contains a resource the Skill actually routes to.

Use the five-layer design model

Read architecture-contract.md before choosing the package structure.

Build these layers in order:

1. Source path — identify where the knowledge came from, who or what can approve it, its scope, version, license, privacy boundary, and conflicts.
2. Rule decomposition — translate implicit practice into WHY, WHEN, HOW, and WHAT, then add invariants, exceptions, prohibited moves, and proof.
3. Skill model — define triggers, inputs, precedence, routing, mutation boundary, outputs, and completion gates in SKILL.md.
4. Execution assets — add only the references, templates, code specimens, scripts, or static assets that make a recurring decision or output more reliable.
5. Evaluation — test representative normal, ambiguous, boundary, and regression cases with observable pass/fail evidence.

The source path and rule model must exist before writing a large instruction file. A folder tree alone does not create design judgment.

Build or refactor the Skill

1. Select core scenarios

Choose the smallest set of recurring, high-value scenarios. Prefer tasks where agent output quality varies because design intent, decision rules, or reusable patterns are implicit.

For each scenario, record:

• user language that should trigger the Skill;
• object and deliverable;
• decision that requires design judgment;
• protected content or scope;
• evidence that would prove success.

Exclude adjacent workflows that have a different primary outcome. Split them into separate Skills when they require different triggers, facts, mutation boundaries, or acceptance gates.

2. Map sources and authority

Use source-map-template.md when the Skill depends on an existing design system, approved screens, internal practice, public guidance, code, or another Skill.

Keep project identifiers and confidential artifacts out of reusable packages. Record a source class or safe public reference, then resolve private instances only inside the active task.

If adapting third-party material, retain attribution, license terms, and a clear statement of what changed. Do not copy assets or text that the license does not permit.

3. Decompose decision rules

Use rule-module-template.md for each independent rule family.

Write rules that let the agent answer:

• WHY: what user or design failure the rule prevents;
• WHEN: trigger, preconditions, and boundary;
• HOW: decision procedure and precedence;
• WHAT: output, template, component, or evidence produced.

Separate invariant, default, exception, prohibited move, and open decision. Convert aesthetic adjectives into observable hierarchy, density, alignment, interaction, content, or consistency conditions.

4. Translate rules into resources

Use this routing contract:

Route every resource from SKILL.md and state when it should be read or run. Keep one canonical home for each rule. References may contain detail; they may not hide essential trigger or safety conditions.

5. Add executable proof

Use evaluation-cases-template.md to define representative cases. Test at least:

• one normal case;
• one short or ambiguous user request;
• one boundary or out-of-scope case;
• one earlier failure pattern the Skill should prevent.

When the Skill changes visual or interactive output, validate a representative specimen at the target viewport or format before batch application. When it produces documents or presentations, render and inspect the final audience surface. When it is read-only, prove that no mutation occurred.

6. Validate and install only when authorized

Run the base creator validator, then run:

python scripts/audit_design_skill_architecture.py /absolute/path/to/skill

Resolve missing resources, orphaned files, placeholder text, unsafe local references, and duplicated routing before delivery. Install, commit, publish, or push only within the user's stated scope.

Refactor existing Skills without churn

Preserve working triggers, boundaries, and proven rules. Refactor only when it improves one of these outcomes:

• the entry file becomes easier to route and load progressively;
• source authority and conflicts become traceable;
• multiple rules gain a stable schema;
• a recurring artifact becomes reusable;
• a deterministic check becomes executable;
• evaluation can detect a known failure.

Keep a single-file Skill when splitting it would add indirection without improving decisions or execution.

Completion gate

Finish only when:

• the package profile matches real complexity;
• sources, rules, triggers, resources, and tests connect end to end;
• every local resource path resolves and every resource has a consumer;
• private project details and unsupported claims are absent;
• third-party adaptations are attributed and licensed correctly;
• representative cases distinguish pass from fail;
• the base creator validation and architecture audit pass.

Handoff

Return:

1. package profile and scope;
2. source and rule layers created or preserved;
3. files added, moved, or intentionally kept single-file;
4. evaluation cases and validation result;
5. installation, repository, and publishing status.