Summary
Headless product design is the practice of designing how your product works: states, flows, edge cases, and permission matrices, before a coding agent writes application source. A headless product design skill is an agent skill with no UI that outputs machine-readable behavior contracts your agent implements from, then verifies the live build against those contracts. It pairs with UI skills; it does not replace them. You can roll your own with plan mode and specs, or use an open-source skill such as Lamina.
Lamina (lamina.dev) is one open-source implementation cited below. This page also covers vendor-neutral patterns you can use with plan mode, custom SKILL.md files, or other tools.
Key takeaways
- Designs how your product works (states, flows, permissions), not how it looks.
- Runs inside your coding agent as a portable SKILL.md folder.
- Writes behavior contracts to your repo, not application source.
- Composes with UI skills, plan mode, and spec tools; does not replace them.
- Worth reaching for when a feature has roles, gates, or multi-step flows.
Why behavior needs designing before code
Coding agents excel at generating screens quickly. Without a behavior contract, they optimize for plausible UI, not for what your domain actually permits. The gaps show up after merge: illegal state pairs, skipped gates, and flows that trap users.
Screens without a state model
Agents render UI that allows domain-invalid combinations (confirmed and cancelled, sold out and bookable) because no contract defined which states exist or which transitions are legal.
Flows that skip prerequisites
Publish before approval, pay before a hold, invite before a role exists. The happy path ships; the gates that define your product do not.
States with no exit
Users stall mid-flow with no cancel, retry, or handoff. Valid paths in; missing transitions out. The machine was generated, not designed.
A headless product design skill exists to spec the state machine, permission matrix, and recovery paths before your agent writes application source.
Industry observers describe this shift as specs replacing wireframes: code-generation tools need intent, behavior, edge cases, and correctness conditions, not layout boxes.
What does headless mean for product design skills?
In commerce and content, "headless" means separating the presentation layer from the data layer: headless CMS, headless commerce. In AI agent tooling, headless product design applies the same separation to product thinking.
The skill has no visual output of its own. It writes behavior contracts to a dedicated directory in your repo, not to app/, src/, or your UI layer.
Headless
No visual output, no styled components, no design files
Product design
Behavior, states, actors, invariants, recovery paths
Skill
A portable folder (SKILL.md + instructions) your agent loads on demand
| Layer | What it owns | Examples |
|---|---|---|
| UI / visual skill | Pixels, tokens, layout, a11y polish | Impeccable, UI Craft, frontend-design |
| Headless product design skill | States, flows, permissions, edge cases | DIY spec + tests, Lamina, custom SKILL.md |
| Coding agent | Application source implementation | Cursor, Claude Code, Codex |
| App builder | Full generated app (often stack-locked) | v0, Lovable, Bolt |
Your product's value is the data and the logic, not the screen wrapped around it.
How is a headless product design skill different from a headless AI agent?
Generic "headless AI agent" glossary pages describe backend automation agents with no UI that run via APIs. A headless product design skill uses "headless" in a different, narrower sense.
| Term | What it is | Interface | Example |
|---|---|---|---|
| Headless AI agent | Autonomous backend worker, API-driven | No chat UI, no design output | Marketing automation, data orchestration |
| Headless product design skill | Agent skill folder (SKILL.md) for coding agents | No visual output; writes contracts | Spec states/flows before your agent codes |
| UI design skill | Agent skill for visual craft | Produces/refines UI code and tokens | Impeccable, UI Craft, frontend-design |
| Conversational agent | Chat/voice interface | Full user-facing UI | ChatGPT, Claude.ai |
When search results say headless AI agent, they usually mean a background automation system: no screens, no chat, pure API execution. A headless product design skill is narrower: it is a skill your coding agent loads to design product behavior before implementation. It extends your agent; it does not run as a standalone background worker.
A headless agent has no face; it waits for a command from another piece of software, not from a human clicking a button.
Agent skills: portable expertise for coding agents
An agent skill is a standardized folder (at minimum a SKILL.md file with metadata and instructions) that extends what your coding agent knows how to do. Skills use progressive disclosure: the agent loads only the name and description at startup, reads full instructions when a task matches, then executes referenced templates and scripts.
- 1
Discovery
Agent sees skill name + description
- 2
Activation
Agent reads full SKILL.md when task matches
- 3
Execution
Agent follows instructions, writes contract files
Skills solve this by packaging procedural knowledge into portable, version-controlled folders that agents load on demand.
Progressive disclosure is the architectural foundation that makes Skills scalable.
What a headless product design skill actually produces
A headless product design skill structures product behavior into artifacts your coding agent can implement and verify against. Typical outputs include:
| Artifact | Location | Purpose |
|---|---|---|
| Domain charter | Contract directory (repo root) | Actors, scope, product boundaries |
| Behavior contract | Per-run folder | States, transitions, invariants, permissions |
| Implementation handoff | Per-run folder | Instructions for your coding agent to build |
| Verification findings | Per-run folder | Gaps found after live behavior walks |
| Session log | Per-run folder | Auditable design → verify trail |
What gets designed
- Product states and legal transitions
- Actor roles and permission matrices
- Multi-step flows with alternate paths
- Empty, error, loading, and recovery states
- Domain invariants that must never break
- Prerequisites and dependency gates
What it does not do
- Write React/Vue/Svelte/API/database code
- Choose colors, typography, or layout
- Replace your UI design skill or design system
A behavior contract specifies interaction contracts: the full state machine for non-trivial interactions. Not the happy path only, but the error state, the loading state, the empty state, the edge case.
Minimal booking behavior contract (illustrative; your format may differ)
# behavior-contract.yaml (illustrative only)
entity: Booking
states: [draft, hold, confirmed, cancelled]
transitions:
- from: draft
to: hold
when: inventory_available AND guest_verified
- from: hold
to: confirmed
when: payment_captured
- from: [draft, hold]
to: cancelled
when: actor_may_cancel
invariants:
- cancelled_bookings_cannot_be_confirmed
- hold_expires_after: 15m
permissions:
guest: [create_hold, cancel_own]
partner: [confirm, cancel_any]How does a headless product design skill verify your build?
Design-time specs are not enough. A headless product design skill checks the live build after your coding agent implements, the same way code review checks merged code, not the original ticket.
- 1
Load the contract
Read states, transitions, invariants, and permission rules from the behavior spec in your repo.
- 2
Persona walks
Parallel subagents or scripted browser sessions act as different roles (guest, admin, partner) and attempt the flows the contract defines, including illegal transitions that should be blocked.
- 3
Gap report
Failures are written to a verification handoff file in the contract directory for your coding agent to patch.
- 4
Re-verify
Repeat until invariants hold or you accept documented exceptions.
Persona walks are end-to-end behavior checks in a running app, not unit tests. Unit tests prove functions return the right values; persona walks prove the product only permits legal state transitions through real UI paths.
In practice, verification uses your coding agent's browser or automation tools (Playwright, MCP browser, subagents) to navigate the live build, assert gates block illegal actions, and compare observed states against the contract.
Headless product design vs everything else in your stack
Most tools around your agent are complementary. A headless product design skill adds product-behavior specs; it does not replace your agent, UI skill, or engineering workflow.
| Category | Examples | What they do | What a headless skill adds |
|---|---|---|---|
| UI skills | Impeccable, UI UX Pro Max | Polish pixels, a11y, hierarchy | Designs states, flows, invariants |
| Product-design skill | product-design (mblode) | Interaction decisions before UI | Structured behavior contracts, permission matrices, post-build persona verification |
| Design craft | BMAD, ai-ux-skills | Heuristics, critique, PRDs | Structured behavior specs and verification |
| Plan mode / prompts | Cursor plan, ad-hoc | Structured thinking, often detailed when prompted well | Durable behavior contracts in-repo, permission matrices as first-class artifacts, post-build persona walks |
| Spec tools | Spec Kit, Kiro | Engineering task structure and acceptance criteria | Product-level state machines and actor flows before the engineering spec; live UI verification against behavior invariants |
| App builders | v0, Lovable, Bolt | Generate full apps | Fits your repo, stack, and agent, with no lock-in |
| Design system contracts | agentic-spec, nib | Component/token enforcement | Product-level state machines and actor flows |
These layers overlap. Plan mode plus a thorough engineer can cover much of the design thinking. Spec tools can encode acceptance criteria. A headless product design skill adds when you want behavior contracts checked into the repo and verified against the live build after every implementation pass.
Full comparison guides: Lamina vs Impeccable, plan mode, v0, and more
You can do this without a dedicated skill
A headless product design skill is a convenience layer, not a prerequisite. Teams already ship behavior specs with the tools below. The tradeoff is structure and repeatability.
Plan mode + SPEC.md
Use Cursor or Claude plan mode, then commit a detailed spec to your repo.
- Strength
- Low overhead; familiar workflow.
- Gap
- Specs drift from implementation; no automated post-build walk against invariants.
State machine in code
Model states in XState, a custom enum layer, or database constraints; cover transitions with integration tests.
- Strength
- Enforced at runtime; testable.
- Gap
- You design the machine while coding, not before the agent writes screens.
Spec Kit / Kiro / similar
Structured engineering specs with acceptance criteria your agent implements against.
- Strength
- Durable artifacts; fits existing SDLC.
- Gap
- Focused on tasks and APIs; permission matrices and multi-role flows need extra prompting.
Custom SKILL.md
Write your own agent skill that outputs a behavior contract template and verification checklist.
- Strength
- Tailored to your domain; version-controlled like any skill.
- Gap
- You maintain the skill and verification loop yourself.
Open-source headless product design skill
Install a skill such as Lamina that encodes the design → implement → verify loop.
- Strength
- Opinionated structure, slash commands, persona verification built in.
- Gap
- Another dependency; contract format is tool-specific.
Where it fits in your agent stack
A headless product design skill is not a replacement for your coding agent, framework, or UI layer. It is an optional skill folder your agent loads when you need product behavior specced before implementation.
| Layer | Role |
|---|---|
| Coding agent | Writes application source, runs tools, loads skills on demand |
| Agent skills | Optional expertise: UI polish, domain patterns, behavior design, etc. |
| Behavior contracts | Machine-readable specs the skill writes; your agent implements from them |
| Application source | Your app/, src/, API routes; unchanged ownership model |
It composes with UI skills (visual craft), plan mode (exploratory thinking), codebase indexing, memory tools, and engineering spec workflows. None of those need to change; this adds a behavior layer when a feature warrants it.
Pull it in per feature when states, roles, or multi-step flows matter, not for every typo or component tweak. Stack and agent choice stay yours.
When should you use headless product design?
A good fit when
- You build with AI coding agents and care about product correctness
- Features have multi-step flows, roles, or permission-sensitive actions
- You have hit impossible states or skipped prerequisites in agent builds
- You want a contract in-repo that survives beyond one chat session
- You need verification against the live app, not just a plan document
Skip when
- You only need a landing-page skin or visual polish (use a UI skill)
- You want a no-code app builder to choose your stack
- You do not want behavior contracts checked into your repo
- Your feature is a pure backend API with no user-facing flow
What a contract changes in practice
The HavenStay demo builds the same hotel booking app twice with the same AI coding agent: once with a behavior contract specced first, once without. Both produce screens; only one enforces the rules below.
We started with checkout hold rules in the contract: timed inventory hold, email verification, and policy consent before payment. The coding agent implemented from implement.md. /lamina-verify walked the live UI as a guest persona and caught a bare confirm button that skipped the hold; gaps landed in fix.md, the agent patched, and we re-verified until illegal transitions were blocked. The contract never wrote application source; it defined which behaviors had to hold.
The contract did not write application source. It defined which behaviors had to hold; verification then checked the live build against that spec.
Implementation example
Lamina: an open-source headless product design skill
Lamina (lamina.dev) is one open-source implementation of the pattern above, licensed under Apache-2.0, for developers who use AI coding agents.
Lamina writes only to .lamina/ in your repo. It never touches app/, src/, or your UI layer. Your coding agent implements from implement.md; Lamina verifies the live build with persona walks.
Not affiliated with uselamina.ai, a separate creative media API.
npx skills install aryaniyaps/lamina- /lamina-initDomain charter in .lamina/
- /lamina-designBehavior contract → run.yaml + implement.md
- /lamina-verifyPersona walks against live build → fix.md if gaps
| Artifact | Location | Purpose |
|---|---|---|
| run.yaml | .lamina/runs/<id>/ | Behavior contract: states, transitions, invariants |
| implement.md | .lamina/runs/<id>/ | Handoff for your coding agent |
| fix.md | .lamina/runs/<id>/ | Verification gaps for your agent to patch |
- 1./lamina-init: Scope your domain
- 2./lamina-design: First feature contract
- 3.Implement: From implement.md
- 4./lamina-verify: Walk the live build
Can I use Lamina with a UI design skill?
Yes. Lamina specs behavior; a UI skill handles pixels. They are designed to compose.
What is run.yaml in Lamina?
The per-run behavior contract: entities, states, legal transitions, invariants, and actor permissions.
What does /lamina-verify do?
It walks your live build with persona subagents, checks behavior against the contract, and writes gaps to fix.md.
Is Lamina free?
Yes. Licensed under Apache-2.0 and open source on GitHub.
Lamina-specific terms
- run.yaml
- Lamina's per-run behavior contract in .lamina/runs/<id>/: entities, states, transitions, invariants, permissions
- implement.md
- Lamina's implementation handoff for your coding agent
- fix.md
- Lamina's verification findings for your coding agent to patch
Common questions
Answers about headless product design skills and how they fit agent workflows.
What is the difference between a headless product design skill and a UI skill?
A UI skill polishes how your app looks: layout, typography, accessibility, visual hierarchy. A headless product design skill designs how your app works: states, roles, permission matrices, and flow recovery. They pair; they do not compete.
Does a headless product design skill write my code?
No. It writes behavior specs and verification findings to a contract directory in your repo. Your coding agent implements application source.
How is this different from plan mode in Cursor or Claude?
Plan mode is conversational and ephemeral. A headless product design skill produces durable, machine-readable artifacts in your repo and can verify the live build after implementation.
What files does it add to my repo?
A contract directory with a domain charter and per-run artifacts: behavior spec, implementation handoff, and verification findings. Exact layout depends on the implementation.
What is the difference between a headless AI agent and a headless product design skill?
A headless AI agent is an autonomous backend system that runs via APIs with no user interface. A headless product design skill is a skill folder your coding agent loads to spec product behavior before writing code. It extends your agent; it does not run standalone.
What is the difference between DESIGN.md and a headless product design skill?
DESIGN.md (or a UI skill) tells your agent how UI should look: tokens, typography, components. A headless product design skill tells your agent how the product should work: states, permission matrices, flow recovery.
Who is this for?
Developers who build with AI coding agents, not designers or PMs looking for a visual design tool.
Glossary: headless product design terms
- Headless product design skill
- An agent skill with no visual output that specs product behavior before code is written
- Agent skill
- A portable folder (SKILL.md + instructions) extending what a coding agent can do
- Behavior contract
- Machine-readable spec of states, transitions, invariants, and actor permissions
- Implementation handoff
- Document your coding agent implements from (format varies by tool)
- Verification findings
- Gaps between the live build and the behavior contract, written for your agent to patch
- Persona walk
- End-to-end browser session where subagents or scripts act as a specific role (guest, admin, partner) and attempt flows the contract defines, including transitions that should be blocked
- Invariant
- A product rule that must never break (e.g. "cancelled bookings cannot be confirmed")
- Permission matrix
- Map of which actor roles can trigger which operations in which states
- Progressive disclosure
- Agent skills load metadata first, full instructions only when task matches
About this page
Educational reference on headless product design for AI coding agents. Lamina (lamina.dev) is one open-source example cited on this page.
By Aryan Iyappan, built lamina of Lamina.
Published 2026-07-12 · Last updated 2026-07-12 · Review every 90 days