The anatomy of a design skill

The sections ours ended up with, in the order they pay for themselves: palette as hex values with one line on each colour’s purpose · typography with actual sizes and minimums · layout with margins and a safe text area · decoration with geometric conditions · text mechanics · a narrow never-list · bundled assets · two or three worked examples, including a bad one.

On the assets, one trick above all: write the logo’s SVG path data directly into the skill text instead of only attaching an .svg — the model can then emit the geometry straight into code without a file lookup. And describe the outer contour and the inner subpath separately — otherwise the fill rule punches a hole through the shape the day the mark is scaled up as a background.

Written down, it is smaller than the guideline it replaced. The difference is that this one gets better with every presentation — ten minutes at a time.

We wanted a model to produce presentations that look like they were made by a human with taste. It only started working the day we stopped correcting slides and started correcting the rules.

We built two skills for Claude: one that distils a meeting transcript into structured content, one that designs slides by the brand’s rules. The emphasis here is on the design part — that was the hard one.

A skill is not a document

There must be one source, and it is the design guideline. The skill is built from it — when something changes, change the guideline and update the skill to match. Never maintain the two separately by hand: if they drift, the model follows the skill, not the document.

The form is not optional: without YAML frontmatter carrying a name and a description, the file is rejected at upload. This is how ours opens:

---
name: design-a-slide
description: The brand's design system for presentations — the colour palette
  and product colours, typography, the logo with its proportions and inline SVG,
  cover and inner-slide graphics, and how to structure a deck. Use when designing,
  building or reviewing any slide, deck, PowerPoint or presentation. Version 1.1.
---

# Slide design

**Version 1.1** · 26 August 2026

The version line is voluntary — and indispensable. Skills do not sync across surfaces (desktop, CLI, web and API each hold their own copy), so sooner or later someone runs a three-week-old version and reports a bug fixed long ago. Which is why the instruction sits in the skill itself: “Keep the version line current”. The number in the text makes it diagnosable in a minute instead of an hour.

Split by the verb, not the topic

Do not build one skill covering everything from transcript to finished slide. Split by the verb: one skill extracts, one skill designs. Two verbs, two skills — and two descriptions that each do three things: name the contents, list the triggers, carry the version number:

description: Turns a meeting transcript, recording or interview into a slide
  plan, extracting what matters and discarding the rest. Use for transcripts,
  meeting recordings, minutes, interviews, workshops, customer calls. Version 1.0.

description: The brand's design system for presentations — palette, typography,
  logo geometry, cover and inner-slide graphics. Use when designing, building
  or reviewing any slide, deck or presentation. Version 1.1.

The description is the only thing the model sees when choosing a skill — the “Use for …” list is not documentation, it is the trigger mechanism. A skill that does two things gets an imprecise description and gets called wrong. And a skill is read into the turn: if you only need to design, an entire extraction method is dead weight. The split halves the price of most tasks.

The price is a contract between them: a defined slide format that one writes and the other reads. Each entry is key-value, ready for layout:

SLIDE 03 · What it costs today
Type: figure
Eyebrow: WHAT IT COSTS TODAY
Title: Checking the time data by hand costs a working day every month
Figure: 8 hours
Figure label: Per payroll run, every month
Quote: "she just made a printout and typed it in"
Source: SAID

Change the format in one skill and the other breaks silently, with no error message. In return, the design skill accepts anything that speaks the format: a report, a roadmap, three bullets written by hand.

Write the rule, not the fix

The most valuable instruction along the way: don’t fix the slide — fix the guideline so it is right the next time.

A rejection fixed only in that one slide comes back in the next deck. The only durable fix is the rule.

The routine: after every presentation, review the corrections. Is a correction specific to this slide, or is it a rule? If it is a rule, it goes in the skill and the version number goes up. Ten minutes — and the only thing that makes a skill better instead of just older.

Rules must be checkable

Compare: “Use tasteful background graphics” with “A radial glow must sit on a shape larger than the slide itself, or its own circular edge shows.” The second can be verified by looking at the result. The first can only be debated.

Every rule should have a number in it: the 60/30/10 colour split, a 96 px margin, the footer at 30% opacity. None of the numbers are interesting in themselves — but every mistake they cover repeated until it was written down.

Even the orphan rule — never a single word alone on the last line — became three ranked interventions: cut the title, bind the last two words with a non-breaking space (U+00A0), or set the line break yourself. Never by shrinking the type.

One size rule matters more than it looks: 16:9 renders as 960 × 540 points, so body copy drawn at 22 px becomes 11 pt — unreadable when projected. The skill carries its own type scale for presentation use (body never below 18 pt) instead of inheriting the brand canvas.

And the negative list must be narrow: a negative rule states exactly what it bans, and where. Never generalise a single objection into a principle nobody asked for — write the rule at the level of the complaint.

Make the geometry explicit

The surprise that matters most. Visual direction arrives as an image: “make something like this”. Beneath the image there is almost always a geometric condition the image hides — and until you have found it, you iterate blindly.

Example: a ring framing a heading. The hidden condition: a ring’s thickness is a fixed share of its radius, so scaled up the curve flattens and the tones wash out. Find the window where the shape actually works, and write it into the skill as two numbers — diameter and visible part. That closes the discussion.

// Arc drop: radius needed to fall s px across a half-width w
r = (w² + s²) / 2s
// 120 px across 960 px  →  r ≈ 3,900 px

// Does the arc reach the frame edge? (depth d, radius R)
reach = √(R² − (R − d)²)   // must be ≥ half the frame width

If you guess the radius, you always guess too small — the calm sweeps in good keynote graphics are sections of enormous circles.

The most reusable rule we found: which way the arc curves decides whether the decoration fights the heading. A shape with its mass in the middle of the edge collides with the text — because that is exactly where the text is. A shape with its mass in the corners frames it. Same shape, same size, opposite result.

Gradients have a coordinate system

Learn the transform matrices by heart, or they cost time every single time:

// horizontal, left to right
gradientTransform: [[1, 0, 0], [0, 1, 0]]

// vertical, top to bottom
gradientTransform: [[0, 1, 0], [-1, 0, 1]]

The vertical one is not intuitive and is by far the most common cause of “why is my gradient sideways”. And if you rotate a shape half a turn, the fill rotates with it, mirroring the gradient — stops are authored in the shape’s own coordinate system, not the frame’s.

A radial glow has a trap of its own: on a shape smaller than the slide, its own circular edge shows, no matter how soft the last stop is. The rule in the skill: the ellipse gets a diameter of roughly twice the slide width, so the edge falls outside the canvas — and four stops instead of two, or you get banding:

gradientStops: [
  { position: 0,    color: { ...accent, a: 1    } },  // peak at the centre
  { position: 0.20, color: { ...mid,    a: 0.33 } },  // down to a third
  { position: 0.42, color: { ...deep,   a: 0.05 } },  // near nothing
  { position: 1,    color: { ...ground, a: 0    } }   // zero — in the ground's hue
]

End on any other hue than the background and you get a grey halo.

The content skill, briefly

Four rules carry it. The most important: work in two passes. Pass one reads the transcript once and builds a claim list, nothing else. Pass two writes the slide plan from the list — and never goes back into the transcript for phrasing, because that is where the errors in proper nouns and figures creep in. Every claim gets a type:

SAID      · stated as fact               → may appear on a slide
AGREED    · both sides accepted it        → may appear on a slide
ASKED     · raised and left unanswered    → the open questions slide
DISPUTED  · pushed back on, contradicted  → must appear somewhere
OBSERVED  · your inference, nobody said it → appendix only, labelled

DISPUTED is the one that gets dropped — and dropping it is what makes a summary misleading. If someone was reluctant, said no, or quietly contradicted a colleague, it belongs in the output: a recap that reads smoother than the meeting felt is a recap nobody trusts.

The last two: late corrections win — a figure given in the first minute and revised in the fortieth counts in its late version. And one verbatim quote per deck, the sentence that states the problem in the other side’s own words: the cheapest proof that you listened, and it survives being forwarded.

Test by using it, not by reading it

Reading a skill through finds no gaps — only use does. Produce two finished presentations with it: everything it has no answer for (diagrams, tables of figures, slides with no content but a statement) becomes a new section.

For everything visual: render and look at the result, every time — code that runs without errors can still produce something entirely different from what was intended. That is the human check. The model’s check is different: have the build script verify its own conditions and return the answer as numbers:

return { mutatedNodeIds: [...], notes: [
  'D=' + D + ' depth=' + DEPTH + ' reach=±' + reach + ' (requires 960)',
  'text ' + y + '..' + (y + h)
]};

The numbers are not for humans — nobody looks at design that way. They are for Claude, who reads them in the same turn and catches that the arc never reached the edge, without asking for a screenshot.

A skeleton to start from

To finish: the skeleton of a design-manual skill, ready to fill in. The sections are the same as in the anatomy up top — here as a file:

---
name: design-manual
description: [The brand's design system for presentations — what it covers.]
  Use when [the triggers: designing, building or reviewing slides ...]. Version 1.0.
---

# [Brand] design manual
**Version 1.0** · [date] — keep the version line current

## Palette
Hex values + one line on each colour's purpose. A split (e.g. 60/30/10).

## Typography
Faces and weights. Actual sizes — and a minimum for projection.

## Layout
Margins, safe text area, grid.

## Decoration
Geometric conditions as numbers. Gradient directions as matrices.

## Text mechanics
Line breaks, orphans, truncation — ranked interventions.

## Never
A narrow list. Exactly what and where — do not generalise.

## Assets
The logo's SVG path data inline. Fonts attached.

## Examples
Two or three worked ones — including a bad one.

Fill it in with your own numbers, produce two decks with it — and correct the rules, not your slides.