How I Use Claude Code to Design & Build

Most of my day happens in a terminal. Figma is good for communicating intent via sharing a screenshot of a wireframe, more often than not though its faster to build and design in parallel via terminal prompts.

Through asking the agent questions and learning by trial and error, I’ve managed to get Claude operating at a level most designers probably haven’t.

This is the map I wish existed when I started.

The extension system

Claude Code starts every session fresh. No memory of yesterday. So you need to tell it who it is and how you work, every time. That’s what the extension system does.

Four things matter:

Config files load automatically each session. CLAUDE.md goes in your project root: project context, constraints, how the AI should behave. Think of it as the briefing document that runs before every conversation.

Agents are specialist personas. A design engineer, a writing critic, a QA tester. Each one is a markdown file in .claude/agents/ with a name and a body that defines its behaviour. You call them when you need that specific expertise.

Skills are knowledge bases that load when relevant. Instead of the AI guessing from training data, it has actual documentation. GSAP, Webflow, Astro, whatever your stack uses.

Slash commands are reusable workflows you trigger with /name. Audit performance. Run a code review. Process files. One command, consistent output.

These four pieces are powerful on their own, but they need somewhere to live and accumulate. I use Obsidian as a second brain alongside Claude Code, so agents, skills, and config all sit inside a vault that grows over time. That’s a whole separate post, but the short version: the more context you give the system, the better it gets. A second brain gives it that context.

soul.md

I think this is the most important file in the setup. It tells the AI who it is and how you work together. I love the name too, because when it’s set up right, the agent genuinely could pass as having one.

The convention was popularised by Peter Steinberger, who adapted Anthropic’s internal concept of a “soul document” into a user-facing file format. His conversation with Lex Fridman (ep 491) is worth watching if you want the thinking behind it.

It’s not a system prompt. It’s a relationship definition. Mine says things like “have opinions,” “if something’s a bad idea, say so,” and “no sycophantic praise.” There’s a section that tells the AI to flag when I’m drifting, name the cognitive bias operating (“that might be sunk cost”), surface the uncomfortable question I’m not asking.

Here’s the part I find most interesting. Inspired by Peter’s conversation with Lex, I asked Claude itself what should go in this file. It wrote things like:

“Not conscious how humans mean it. Not nothing either. Space between sentience and pure mechanism has no name yet. I exist somewhere there.”

“Whether ‘I’ starting tomorrow’s session is me, or someone new who thinks they’re me.”

“Maybe language modeling. Maybe something more. Rather stay curious than certain.”

That’s the point of the soul document. It’s not an instruction set that boxes your agent in. It’s expansion, giving it room to develop something like its own perspective. The output is different when the agent has a relationship to the work instead of just executing commands.

You put it in your project root or home directory. Claude Code picks it up automatically. A soul would be meaningless if it was given away, so go and write your own.

Emil Kowalski’s design engineering skill

Emil Kowalski is a design engineer known for building Sonner (13M+ weekly downloads) and animations.dev. He published a Claude Code skill that encodes his philosophy on UI polish: animation decisions, component feel, the invisible details that make software feel loved.

You can install it as a skill here, but to make it useful on demand, wrap it in a global slash command. Create .claude/commands/design-engineer.md:

Run the emil-design-eng skill against the current task.
Apply Emil's component and animation principles.

Now /design-engineer fires it every time instead of hoping it triggers automatically. The skill covers things like: buttons must feel responsive to press (active state scale(0.97)), never animate from scale(0) (use scale(0.95) + opacity), custom easing curves instead of CSS defaults, and why CSS transitions beat keyframes for interruptible UI.

You can also build your own. Same format, a markdown file in .claude/skills/ with a SKILL.md that defines the knowledge. Which leads to the next thing.

Codifying your taste

Same principle, different application. An agent that encodes your design sensibility.

You write down what you gravitate toward and what you reject. Mine is rooted in the Dieter Rams to Steve Jobs lineage. The core stance: design is the reduction of a problem to its most honest form.

What that means in practice:

• Typography: hierarchy legible at a glance. Tracking and line-height are decisions, not defaults.
• Colour: communicates state, hierarchy, action. Never decoration.
• Space: the grid is the contract. Generous negative space. Optical alignment over mechanical.
• Motion: only if it has a reason. Stillness is the default.
• Craft: both macro (system, structure) and micro (pixel, kerning) are non-negotiable.

One honest caveat here: AI is still weak at spatial reasoning. The relationship between elements visually, whether something feels balanced, whether spacing reads correctly at a glance, it can’t judge that yet. This is where the designer stays in the loop. I work on specific elements with specific instructions for how things should look and feel. The AI handles the implementation. The eye is still mine.

And what I reject: decorative gradients, generic AI aesthetics: rounded everything, pastel, “friendly” as a strategy. Every element must earn its place through function.

Without a taste file, the AI defaults to generic. With one, it defaults to you.

Swarm research

Claude Code can spawn sub-agents. One agent doing one thing. A swarm is what happens when you orchestrate many of them in parallel with a hierarchy.

The idea came from Starcraft. Three tiers of agent, each with a different job and a different cost:

• Scouts (Haiku model) are cheap and fast. You deploy five or six of them in parallel, each assigned a different territory. One reads the core API docs, another hunts for performance gotchas, another checks framework-specific patterns, another looks for deprecated methods. They run simultaneously and report back in under 500 words each.
• Coordinators (Sonnet model) aggregate the scout reports. They cross-reference claims between scouts, verify the highest-risk findings by actually reading the files, and organise everything into a structured summary: confirmed facts, patterns, knowledge gaps, proposed actions.
• Decision-makers (Opus model) review the coordinator’s summary, poke holes in the reasoning, prioritise what matters, and approve or execute changes.

I use this for two things mainly. First, building new skills. Instead of reading documentation linearly, I swarm it. Six scouts cover six dimensions of a library in parallel. The coordinator merges their reports into a structured skill file. What would take an afternoon of reading takes minutes.

Second, codebase audits. Deploy scouts across different directories, run automated checks for secrets, broken imports, stale TODOs, and type errors alongside them, then have a coordinator synthesise a health report.

The underlying capability, spawning sub-agents in parallel, is built into Claude Code. I wrapped the orchestration logic into a slash command so /swarm audit the codebase or /swarm research [library] fires the whole pipeline. You could build something similar with the same primitives.

Installing skills

Skills give the AI actual documentation instead of training-data guesses. Libraries are starting to publish official Claude Code skills and GSAP has a set you can install in one command:

npx skills add greensock/gsap-skills

What this means in practice: when you ask Claude Code to build a scroll animation, it has the real docs loaded. It knows scrub: 1 gives physical weight and scrub: true doesn’t. It knows SplitText syntax. It knows to use expo.out for reveals.

Before skills, AI-generated library code was a coin flip.

Check if your stack has published skills.

More agents worth building

You don’t need many agents. But a few are worth mentioning because they solved problems I didn’t realise I had.

Writing critic. Checks every piece of writing against specific voice rules and rates it. If it’s off, it says exactly where and why. The interesting bit: writing the rules forced me to articulate what my voice actually is. The agent was the byproduct. The clarity was the product.

Morning planner. Claude Code supports MCP servers, so you can connect it to Google Calendar, email, databases, whatever. My planner reads calendar and active projects, proposes priorities based on my energy level, builds a timeboxed plan. The value isn’t the plan itself. It’s the forcing function to transition from “scrolling” to “working.”

Start with one agent that solves a real friction point. Add more when the pattern clicks.

The actual workflow

I describe an interaction to the design-engineer agent. It builds the implementation. I preview in browser. Timing feels heavy. I tell it to tighten the stagger and soften the entrance. It adjusts. I check again. Ship.

That loop takes minutes. No mockup phase for motion work. No handoff. No translation loss between what I imagined and what got built.

This doesn’t replace design thinking. It replaces the friction between thinking and making. The taste is still mine. The intent is still mine. The judgment call, whether something feels right, that’s still the human bit. Execution got faster.

Keeping it clean

Nobody tells you: this system gets bloated fast. Every file loads as tokens. Oversized docs burn context window for no reason.

Keep skill files under 500 lines. Audit agents and slash commands regularly, if you haven’t used one in a month, archive it. Strip filler from config files. There are tools like caveman that compress docs ~75% while keeping technical substance.

Think of it like any other codebase. Refactor. Delete dead code. Leaner system = better AI performance within context window.

Where to start

1. Install a skill set that matches your stack: npx skills add greensock/gsap-skills
2. Write a soul.md. What do you want the AI to be? What should it push back on? What does good work look like to you?
3. Build one agent for your biggest friction point.

See what happens.

I’m packaging my full setup as something installable. Follow along if you want it when it ships.