4.1 What a Skill Is

Skills as Recipes

Before I ran Open Design with explicit skills, I did what most people do: I wrote long, detailed prompts and hoped the agent would produce something consistent. Sometimes it did. More often, the same prompt produced a different layout, a different color treatment, and a different component style on every run. Skills fix that. A skill is a recipe the agent follows: it constrains structure, applies a brand system, and fixes the output format, so the same prompt produces reliable results across runs.

The skill is the recipe in exactly the way a kitchen recipe works. A recipe doesn't just list ingredients---it specifies quantities, sequence, temperature, and the expected result. A good recipe is repeatable: the same cook, the same kitchen, the same result. Open Design skills do the same thing for design artifacts. They tell the agent how to lay out a dashboard, which brand tokens to pull, how many KPI cards to render, and what self-check to run before returning the artifact.

Without a skill, generation is raw-prompt generation. With a skill, it's recipe-driven generation. The difference shows immediately.

Use the dashboard skill with the Stripe brand system
to build an analytics overview with four KPI cards
and a revenue chart.

Build an analytics dashboard with four cards
and a revenue chart.

A skill file is small---most are under 80 lines of YAML frontmatter plus Markdown prose. The frontmatter declares the skill's identity, triggers, and Open Design extensions. The prose body is the workflow the agent reads verbatim: what to do first, how to classify the request, how to lay out the regions, and what to check before calling the artifact done.

As of June 2026, Open Design ships with 100+ skills (the repository contains 157 total items across the skills/ and design-templates/ directories; the README uses the conservative "100+" figure).

4.2 The Skill Catalog

Seven artifact modes, hundreds of variations

Skills are organized by artifact mode. Each mode corresponds to a distinct type of output: prototype, deck, template, design-system, image, video, or audio. Most teams use the prototype and deck modes daily; the rest exist for specific pipelines. Knowing which mode covers your artifact lets you route a prompt to the right skill immediately instead of guessing.

The prototype mode is the highest-volume category by a wide margin. Most bundled skills target prototype with platform: desktop or platform: mobile. Decks come second, with several magazine and Swiss International variants. The remaining five modes cover specialized pipelines: design system documentation, image generation, video, audio.

One distinction the catalog makes explicit is that design templates and functional skills are not the same thing, even though both use SKILL.md and appear in the picker. Functional skills (under skills/) describe complete workflows. Design templates (under design-templates/) are reference implementations of a specific visual layout. Both use the same API shape, but templates are more like examples than instructions.

4.3 How Agents Select and Compose Skills

From prompt to skill to artifact

When you submit a generation request in Open Design, the daemon doesn't immediately hand it to the agent. It first resolves which skill to apply. That resolution is brief-matching: the daemon scans skill description and triggers fields against your prompt and surfaces the best match in the skill picker. You confirm it---or pick a different skill---before the agent reads the skill body and begins generating.

Skill Discovery and Precedence

Open Design scans three locations for skills, in priority order:

When two skills share the same name, the higher-priority location wins. This lets you override a bundled skill at the project level---write a project-private version of dashboard in .claude/skills/ and it shadows the bundled one for that project alone.

Brand Injection

Skills that declare od.design_system.requires: true get the active DESIGN.md injected automatically at the top of their context window before the agent reads any prompt content. The sections list controls which parts of DESIGN.md are injected---a dashboard skill that only needs color and typography requests those two sections, keeping the context tight.

od:
  mode: prototype
  design_system:
    requires: true
    sections: [color, typography, layout, components]

Skills that don't declare requires: true don't see the DESIGN.md at all. Image-generation and audio skills often skip it because their output format can't consume CSS tokens directly.

Craft References

As of June 2026 (v0.9.0), Open Design supports a third input axis alongside the skill body and DESIGN.md: craft references, stored under craft/. Craft references are brand-agnostic rules---things like letter-spacing conventions, accent color frequency rules, and anti-AI-slop typography checks. They shipped with v0.8.0 and are documented in skills-protocol.md §5.5. A skill can request specific craft references in its frontmatter:

od:
  craft:
    requires: [state-coverage, accessibility-baseline, laws-of-ux]

Craft references (shipping since v0.8.0) are a newer concept and are likely to evolve. Think of them as a quality layer below brand: they ensure the artifact meets baseline design principles regardless of which brand system is active.

4.4 Anatomy of a Skill File

What every skill is made of

Every skill is a single file: SKILL.md. It combines YAML frontmatter with Markdown prose. The frontmatter is machine-read by the daemon and the skill picker; the prose is agent-read during generation. The split is important---you design the frontmatter for the machine, and you write the prose for the agent.

File Structure

my-skill/
├── SKILL.md          # required: frontmatter + workflow prose
├── example.html      # required if od.preview.type is "html"
├── assets/           # optional: static files referenced by example.html
└── references/       # optional: extra documents the agent should read

The minimum viable skill is just SKILL.md with an example.html when the skill produces HTML output. Everything else is optional. The references/ folder is useful when a skill needs the agent to consult supplementary material---a data schema, a component spec, a copywriting guide.

The SKILL.md Frontmatter Fields

A Real Skill: The Dashboard

The dashboard skill in the Open Design repository is the clearest example of a well-authored skill. Its frontmatter is precise, its triggers are concrete, and its workflow prose is explicit about what the agent must do at each step. The excerpt below is reproduced for commentary from design-templates/dashboard/SKILL.md in the Open Design repository (Apache-2.0 licensed; source: github.com/nexu-io/open-design, as of June 2026). The workflow steps are abbreviated here; the full prose is in the source file.

---
name: dashboard
description: |
  Admin / analytics dashboard in a single HTML file. Fixed left sidebar,
  top bar with user/search, main grid of KPI cards and one or two charts.
  Use when the brief asks for a "dashboard", "admin", "analytics", or
  "control panel" screen.
triggers:
  - "dashboard"
  - "admin panel"
  - "analytics"
  - "control panel"
od:
  mode: prototype
  platform: desktop
  scenario: operations
  preview:
    type: html
    entry: index.html
  design_system:
    requires: true
    sections: [color, typography, layout, components]
  craft:
    requires: [state-coverage, accessibility-baseline, laws-of-ux]
---

# Dashboard Skill

Produce a single-screen admin / analytics dashboard.

## Workflow

1. Read the active DESIGN.md (injected above). Colors, typography,
   spacing, component styling all come from it. Do not invent new tokens.
2. Classify what the dashboard monitors...
3. Lay out required regions...
4. Write one self-contained HTML document...
5. Charts: inline SVG only...
6. Self-check:
   - Every color comes from DESIGN.md tokens.
   - Accent used at most twice...

Notice what the skill enforces: tokens come from DESIGN.md (never invented), the output is a single HTML file, SVG charts are inlined, and a self-check runs before the artifact is returned. The recipe is the recipe---no run should skip those steps.

The Trigger Quality Bar

Triggers are the most commonly mis-authored part of a skill. The Open Design merge checklist (in docs/skills-contributing.md, Apache-2.0) explicitly rejects vague triggers. The concrete trigger examples below are illustrative of the accepted/rejected pattern documented in docs/skills-protocol.md §5 (Apache-2.0):

triggers:
  - "magazine deck"
  - "杂志风 PPT"
  - "horizontal swipe presentation"

triggers:
  - "design something cool"
  - "make a nice layout"
  - "creative design"

Vague triggers match too broadly and surface the wrong skill. Concrete triggers match the actual language users reach for when they know what they want. Writing good triggers means reading a week's worth of your team's actual generation prompts and extracting the phrases that reliably predict this artifact type.

4.5 Authoring Your Own Skill

Step-by-step: from blank file to working recipe

Custom skills are where the skills system pays back the most. A house skill encodes your team's standards once and applies them on every run---every artifact from that skill will follow the same layout rules, use the same component patterns, and run the same self-checks. The barrier is low; the maintenance is real. Here's how to build one correctly.

---
name: pricing-table
description: |
  Pricing page with three tiers and a monthly/annual toggle.
  Use when the brief asks for a "pricing page", "pricing table",
  or "subscription plans" screen.
triggers:
  - "pricing page"
  - "pricing table"
  - "subscription plans"
  - "three tiers"

od:
  mode: prototype
  platform: desktop
  preview:
    type: html
    entry: index.html
  example_prompt: "Build a pricing page with three tiers and an annual toggle."
  design_system:
    requires: true
    sections: [color, typography, components]
---

# Pricing Table Skill

Produce a single-page pricing component.

## Constraints
- Three tiers only (Starter, Pro, Enterprise)
- Monthly/annual toggle with JS state
- Highlighted "recommended" tier

## Workflow
1. Read the active DESIGN.md. All colors come from it.
2. Build the toggle: monthly default, annual shows 20% off.
3. Three columns; each gets: tier name, price, feature list,
   CTA button.
4. Self-check: every color from DESIGN.md; toggle works
   without external dependencies.

## Output
Single self-contained index.html with inline CSS and JS.

4.6 When to Write a Skill vs Tweak a Prompt

The skill/prompt boundary

Not every generation problem needs a new skill. Tweaking a prompt handles one-off customizations; a skill handles structural patterns you repeat. The skill/prompt boundary is a judgment call, but it's not an arbitrary one. There are four signals that tell you when a skill is the right answer.

The practical rule: if you've added the same constraint to three different prompts for the same artifact type, move that constraint into a skill. Three is the threshold where the maintenance cost of prompting exceeds the cost of authoring a skill.

Composition Over Forking

When a bundled skill is close but not quite right, the instinct is to fork it---copy the whole skill directory, edit the copy. Resist this. Forked skills diverge from upstream as Open Design updates its bundled skills. You'll be maintaining your own version of a skill that the repo is actively improving.

The better pattern is composition: create a new skill that augments a bundled one rather than replacing it. Reference the bundled skill by name in your prompt, then add the custom constraints in your own skill's prose. Or use the skill picker to select the bundled skill and add your constraints as a follow-up prompt in the iterate beat.

Invoking a Skill Directly

You can invoke a named skill explicitly in your prompt without relying on the picker's brief-matching:

Use the dashboard skill with the Stripe brand system to build
an analytics overview with four KPI cards and a revenue chart.

Naming the skill directly is useful when you know exactly which skill you want and don't want the picker to surface alternatives. It also makes prompts more auditable---a prompt that names its skill is easier to review and reproduce than one relying on implicit matching.

The Merge Checklist (For Contributors)

If you intend to contribute a skill back to the Open Design repository, the merge checklist is the quality bar to clear. The key criteria from the checklist as of June 2026:

Even if you're writing a private house skill that will never be contributed, these criteria are the right bar to hold yourself to. The merge checklist distills what makes a skill reliable versus one that only works when conditions are perfect.