01 · Skills: a capability is a folder

Skills are the heart of OpenDesign. A skill is a folder containing a SKILL.md that says how this kind of work gets done.

What matters isn't how many ship. It's the shape: plain Markdown, which you can add to and take away.

What ships

In the plugin library's own taxonomy, "Skills" currently numbers 23 — pure instruction: copywriting, colour theory, creative direction, brainstorming. The output depends entirely on your input.

Alongside them are 292 "Templates" — runnable starting points, each shipping an example.html. The difference:

	Skills	Templates
Contents	SKILL.md prose	Instructions plus a runnable example
Output	Depends on your input	Has a visual starting point
Count	23	292
Suits	Work that needs judgement	Work that needs a starting shape

In practice you rarely have to care — they're all in the same library in the UI.

What a skill looks like

A SKILL.md usually holds:

---
name: saas-landing
description: Landing pages for B2B SaaS. Use when…
craft: [accessibility-baseline, state-coverage, typography-hierarchy]
---

## When to use this
(Describe the case so the agent can decide whether to load it)

## What must be established first
(This section drives the discovery form — its questions come from here)

## Structure
(The standard skeleton for this kind of artifact)

## Hard constraints
(What must not happen)

## Acceptance
(How you know it's done)

Note the craft line: a skill declares which craft rules it requires, and loading the skill loads those rules into the system prompt. Quality floors travel with the capability, so you don't restate them in every prompt.

When to write your own

One test: you've done this kind of job three times and the prompt was nearly the same each time.

At that point your prompt already carries your judgement — you know which sections this thing needs, what to ask the client, which approaches never work. Write it down and call it next time.

The reverse — writing a skill after one good result — usually produces something too general to beat just describing the job.

Reverse-engineer it from a good run

The cheap way isn't writing from scratch. It's having the agent work backwards:

I'm happy with what that last generation produced. Turn the approach
into a SKILL.md.

Include:
1. When this skill applies, and when it doesn't.
2. What must be established before generating (this drives the
   discovery form).
3. The standard structure for this kind of artifact.
4. The specific judgement calls we got right this time, written as rules.
5. Hard constraints — what must never happen.
6. Acceptance criteria.

Then tell me which parts you inferred from this one run and might not
generalise.

That last question matters. A skill reverse-engineered from a single success tends to treat coincidence as law. Have it flag its own inferences and decide for yourself what stays.

Taking a skill elsewhere

A skill is a folder, so it travels.

Lift one out of OpenDesign and drop it into your own Claude Code or Codex session as context. Useful when the capability you want has no button in the UI, or when you're scripting and don't want a GUI at all.

This is also what "switching agents costs nothing" means concretely — skills aren't bound to an agent, and they aren't tightly bound to OpenDesign either.

A worked example

Say you write a product monthly report with a fixed shape: headline metrics, three things shipped, two problems, next month's plan.

The first time, you wrote a long prompt and liked the result. By the third, write it down:

The skill

---
name: monthly-product-report
description: Internal product monthly. Fixed four-part structure, for
  leadership who won't read detail.
craft: [accessibility-baseline, typography-hierarchy, state-coverage]
---

## When to use
Internal monthly, weekly, or fortnightly reports. Not for external material.

## What must be established
- Which headline metrics, and whether the values are real or pending
- Of the things shipped, which one mattered most
- Whether problems are being surfaced or presented with fixes attached
- Whether readers need context (a new exec vs someone who's followed along)

## Structure
1. One-sentence summary — a judgement, not a log
2. Headline metrics, max 4, each with a period-on-period change
3. Things shipped, max 3, ordered by importance
4. Problems, max 2, each with a next step
5. Next month, max 3 lines

## Hard constraints
- Missing metrics are marked pending, never estimated
- No content-free phrases ("continued optimisation", "steady progress")
- Every section must be removable without breaking the others

## Acceptance
- Can someone who attended no meetings follow it?
- Can every number be sourced?

After that, each month you supply the month's data and nothing else.

Where it goes wrong

Trap	How it shows	Fix
Skill too general	No better than not using one	Write specific judgements, not a generic process
One-off details baked in	None of it applies next time	Make it flag what was specific to that run
Skill too long	The agent loses the thread	One skill per kind of job
No craft declared	The quality floor isn't there	List the rules in frontmatter

Related

• 02 · Systems — skills govern process, systems govern looks
• 04 · Craft — what those declared rules actually are