What is the refero-design skill?
The refero-design skill is a research-first design methodology from the referodesign/refero_skill repository. Its SKILL.md requires an agent to gather references before implementing, using Refero's styles, screens and flows through MCP when connected, or bundled craft references when not, then lock a direction and validate the build.
Three research layers organize this skill: styles for visual direction, screens for concrete UI patterns, and flows for multi-step journeys. The README says live research draws on 150,000+ real app screens and 6,000+ user flows.
The skill's own rule is blunt: every design must be grounded in references before implementation, and the agent should not lean on generic model taste. The repository packages that rule with one read-only MCP connection.
How the research layers work
- Styles come from real web marketing and product pages and give a visual thesis, tokens, typography, spacing, surfaces and do and don't rules.
- Screens answer questions such as how a pricing toggle, a data table filter or a cancellation modal is usually built.
- Flows give step-by-step goals, actions, system responses and completion states for onboarding, checkout and similar journeys.
Reference lock before building
After retrieving three or four strong styles, the agent picks one primary foundation and borrows only one or two details from others. It then writes a lock that names what must survive, what to reject and each token's role.
The skill warns against averaging references into a safe middle and against moving a token outside its role. A CTA color stays CTA-only, and the finished build is checked against the lock.
Setup and limits
- Bundled craft references work without an account. Live Refero research connects over OAuth, and the README says it needs a paid Refero plan.
- Styles currently cover web marketing and product pages, not in-app dashboards, auth screens, settings or iOS screens as style systems.
- Image generation is optional and skipped for small fixes or code-native UI.
Who the refero-design skill suits
Best for
- Landing pages and redesigns where several plausible directions exist and you want evidence behind the choice.
- Agents that keep producing the same generic look. See anti-ui-slop for a related angle.
- Teams happy to pair a skill with a connected MCP server.
Not for
- Work where you want no research step. Even its direct build path for small UI fixes researches and locks a direction before coding.
- Offline work that needs live reference data. Without the MCP connection you get bundled references only.
- Running beside other design authorities. It tells agents to prefer it over generic frontend and product design skills.
Use it with UiChemy
Refero shapes the design direction and the build your agent produces, not a WordPress site. Take the locked direction into UiChemy Composer as a precise brief, or bring a finished build in with AI to WordPress. Click Get Started on uichemy.com.
Related reading: design-taste-frontend for taste rules and polish for a final visual pass.
How to install Refero Design Skill: Research-First UI Design
/plugin marketplace add referodesign/refero_skill
/plugin install refero@referoAdd the plugin in Claude Code
Run
/plugin marketplace add referodesign/refero_skill, then/plugin install refero@refero. The plugin carries both the skill and the Refero MCP connection.Sign in to Refero
For live research, the SKILL.md says to run
/mcpand sign in when prompted. Its typical setup line isclaude mcp add --transport http refero https://api.refero.design/mcp.Other agents
The README also lists Codex commands (
codex plugin marketplace add referodesign/refero_skill,codex plugin add refero@refero) and Gemini CLI (gemini extensions install https://github.com/referodesign/refero_skill).Manual copy
To install by hand, copy the entire skills/refero-design directory into your client's skills directory so the references folder stays beside SKILL.md.
Check that it loaded
Ask the agent to design a pricing page. It should form a short brief, search styles first, name its references, write a reference lock, and only then build.
Key features
- Research is mandatoryThe non-negotiables say every major visual, layout, content or interaction decision must trace to Refero research, the user's brief or a craft reference.
- Styles, screens and flowsThree layers split the research job: visual direction, concrete UI patterns, and journey logic for tasks with several steps.
- Style search toolsrefero_search_styles finds candidates and refero_get_style returns the full reference with tokens, typography, layout and implementation notes.
- Screen search toolsrefero_search_screens, refero_get_screen, refero_get_similar_screens and refero_get_screen_image cover layouts, components, copy patterns and states.
- Flow search toolsrefero_search_flows and refero_get_flow return step-by-step journeys for onboarding, signup, checkout, cancellation and password reset.
- Reference lockA fill-in block records the primary direction, traits to preserve, borrowed details, role rules, media strategy, rejected defaults and token commitments.
- Workflow routingDirect build, visual exploration with three options by default, audit with screenshots as evidence, and asset generation only when needed.
- Bundled craft referencesThe skill folder includes reference files for anti-ai-slop, color, copywriting, craft details, icons, motion and typography, plus MCP tools and a visual workflow.
- Works without the MCPIf Refero tools are unavailable, the agent uses bundled craft references and any references you provide, keeping the same lock workflow.
- Design brief templateA short brief format captures what, who, platform, goal, tone, main objection, hook, constraints, research needed and path before research begins.
Frequently asked questions
What is the refero-design skill?
It is the single skill in the referodesign/refero_skill repository. It makes research mandatory before design work, using Refero styles, screens and flows when the MCP is connected, and bundled craft references otherwise, then locks a direction and validates the build.
How do I install the refero-design skill?
Run the plugin marketplace add command for referodesign/refero_skill, then install refero@refero. The README has separate commands for Codex and Gemini CLI, and a manual route of copying the skills/refero-design directory into your skills folder.
Do I need a Refero account?
Not for the bundled craft references. Live research connects to the Refero MCP through OAuth sign-in, and the README states that live research requires a paid Refero plan. Without it, the skill still works as a methodology and reference set.
Which AI coding agents can use the refero-design skill?
The README gives install routes for ChatGPT and Codex, Claude Code, Gemini CLI and Cursor, with the Cursor listing noted as pending marketplace approval. The repository topics also list claude-code-plugin, codex-plugin and cursor-plugin.
What is the difference between a style, a screen and a flow?
A style is a semantic design reference extracted from a real web page, with tokens and rules, not a screenshot. A screen is a concrete UI example. A flow is a multi-step journey. The skill uses styles first for visual work, then screens and flows for detail.
Does it replace other design skills?
It says it should. The SKILL.md tells agents not to use generic frontend or product design skills as a parallel authority, and to use them only for implementation details after research. If you prefer a different approach, choose a generic design skill instead of this one.
What can styles not cover yet?
The SKILL.md states a current limitation: styles cover web marketing and product pages such as landing and pricing pages. They do not yet cover in-app dashboards, auth screens, settings screens or iOS screens, so screens and flows carry that load.
What license does the refero-design skill use?
The repository README ends with MIT and GitHub lists the same license. Check the repository again before you redistribute the folder inside a product, because the Refero service and its data are separate from the skill files.