What is the design-brief skill?
The design-brief skill turns a design idea into a written brief. The agent asks for a description, scans your codebase for tokens and components, interviews you about every open decision, then saves DESIGN_BRIEF.md in a .design folder. It is one of eight skills in the designer-skills collection.
A request like write a brief for the onboarding flow starts this skill. It runs an interactive interview, explores your codebase and records experience design decisions in .design/<feature-slug>/DESIGN_BRIEF.md, ready for the build step.
How the brief gets written
- The agent asks for a detailed description of what you want to design.
- It explores the codebase for existing tokens, themes, components and fonts.
- It interviews you about every branch of the design tree, offering a recommended answer to each question.
- It writes the brief from a fixed template.
What the brief contains
- Problem and Solution.
- Experience Principles, limited to three.
- Aesthetic Direction: philosophy, tone, reference points and anti-references.
- Existing Patterns and a Component Inventory table marking each part as Exists, Modify or New.
- Key Interactions, Responsive Behavior, Accessibility Requirements and Out of Scope.
The interview covers the user's job to be done, what success means, emotional tone, a reference and an anti-reference, hard constraints, and whether content is real or placeholder. Later skills in the same collection read the saved brief.
Who the design-brief skill is for
Best for
- Designers who prototype with AI tools and want decisions written down first.
- Features that must fit an existing codebase, since the scan prevents duplicate components.
- Work split across sessions, because the brief persists in the project.
Not for
- Generating the interface itself. For building, see frontend-design.
- Producing a full token system. See design-token.
- Screen-level layout detail. wireframe-spec goes further there.
Use it with UiChemy
A brief gives a Figma designer or an agent the same decisions to work from. UiChemy Figma to WordPress then converts the finished Figma design into a WordPress site, and Composer edits it. Click Get Started on uichemy.com. Hand-off is covered in design-handoff.
How to install Design Brief Skill: Interview Before You Build
/plugin marketplace add julianoczkowski/designer-skillsAdd the marketplace
In Claude Code, run
/plugin marketplace add julianoczkowski/designer-skills.Install the plugin
Run
/plugin install designer-skills@designer-skills. This installs all eight skills, not only design-brief. Update later with/plugin update designer-skills@designer-skills.Call it by name
Invoke it as
/designer-skills:design-brief, or describe the task and let the skill description match it.Try it locally first
The README suggests
claude --plugin-dir /path/to/designer-skillsto test the plugin before installing it.
Check that it loaded
Ask for a brief on a feature. The agent should scan the project, ask you interview questions and save DESIGN_BRIEF.md in a .design folder named for the feature.
Key features
- Interactive interviewThe agent questions you on each design branch and proposes a recommended answer, so you confirm or change a decision.
- Codebase scanIt checks CSS variables, Tailwind config, framework themes, component folders, Storybook, token JSON, UI dependencies, font loading and existing pages.
- Brief templateA fixed template covers Problem, Solution, Experience Principles, Aesthetic Direction, Existing Patterns, Component Inventory and more.
- Three principle limitExperience Principles are capped at three, which forces priorities instead of a long wish list.
- Component inventory tableEach component is marked Exists, Modify or New, so the build step reuses what the project already has.
- Reference and anti-referenceThe interview asks for something to resemble and something to avoid, then records both under Aesthetic Direction.
- Per feature folderBriefs are saved at .design/<feature-slug>/DESIGN_BRIEF.md, so each feature keeps its own brief.
- Real versus placeholder contentThe interview asks which content is real and which is a stand-in, which affects how the interface is judged later.
- Part of a flowIt sits between grill-me and information-architecture in an eight skill sequence, and other skills read the same folder.
Frequently asked questions
What is the design-brief skill?
It is one of eight skills in julianoczkowski/designer-skills. It interviews you, explores your codebase and writes a structured design brief to .design/<feature-slug>/DESIGN_BRIEF.md. The brief records the problem, principles, aesthetic direction, components and interactions before any building starts.
How do I install the design-brief skill?
In Claude Code, add the marketplace with /plugin marketplace add julianoczkowski/designer-skills and run /plugin install designer-skills@designer-skills. That installs all eight skills. Then call /designer-skills:design-brief or describe the task, for example writing a brief for an onboarding flow.
What does the codebase scan look for?
It looks for CSS variables and token files, Tailwind theme settings, framework themes such as MUI, Chakra or shadcn, component directories, Storybook, design token JSON, UI dependencies in package.json, font loading and existing pages. The aim is to reuse what exists.
Where does the brief get saved?
In .design/<feature-slug>/DESIGN_BRIEF.md inside your project. Each feature gets its own subfolder, so a second feature does not overwrite the first. Later skills such as information-architecture, design-tokens, brief-to-tasks and design-review read from the same folder.
How long is the interview?
The README gives no question count. The skill interviews you about every branch of the design tree and offers a recommended answer to each question, covering user goals, success, tone, references, constraints and content. Expect it to continue until open decisions are resolved.
Which AI agents work with design-brief?
The README says the interactive install route, the skills CLI add command pointed at julianoczkowski/designer-skills, works with Claude Code, Cursor, Codex, Windsurf and 40 or more other agents. Plugin commands are given for Claude Code only. The README also advises reviewing skills before using them in sensitive contexts.
Do I need the other seven skills?
No. Each skill can be used on its own, and the README also offers a design-flow skill that runs the whole sequence. The plugin install does bring all eight, so you can ignore the ones you do not need.
What license does the designer-skills repo use?
GitHub lists the repository license as Apache-2.0, so the skill text can be read, copied and adapted under that license. Review the skill text before using it in a sensitive or production context, as the README's security note advises.