referodesign/refero_skill instruction manual

1. Purpose, scope, and Claude Code classification

Refero instruction manual

Refero packages one canonical design skill, `refero-design`, together with one read-only Refero MCP connection. Its purpose is to make interface work research-first: establish visual direction from styles, inspect real screens for concrete interface patterns, study flows for multi-step journeys, synthesize those findings, and only then design or implement. The repository says the live service covers curated visual styles, more than 150,000 real application screens, and more than 6,000 user flows.

**Claude Code classification:** this is a **Claude Code plugin combining context injection and a read-only MCP tool surface**. The skill injects a design methodology and bundled craft guidance; `.mcp.json` connects the plugin to Refero’s production MCP endpoint. It is not a standalone design application and does not intercept Claude Code lifecycle or shell operations. Installation mode is `claude_extension`, and setup effort is low for the plugin path. Confidence is high because the supplied Claude plugin manifest, skill, README, and MCP setup all explicitly describe this mechanism.

The package contains `skills/refero-design/` as the canonical skill, `.mcp.json` for Claude Code and Codex, `mcp.json` for Cursor, platform manifests for Claude Code, Codex, Cursor, and Gemini CLI, plus `server.json` for the MCP Registry. All connection manifests reportedly use the same production endpoint and contain no access tokens.

Live research requires OAuth sign-in to Refero. The README states that live research requires a paid Refero plan, while no account is required to use the bundled craft references. The repository is public, Python is its GitHub metadata language, release manifest version is `1.0.2`, and the license is MIT.

2. Installing and connecting with Claude Code

The recommended Claude Code route installs both the skill and the configured MCP connection. Enter these commands inside Claude Code:

/plugin marketplace add referodesign/refero_skill
/plugin install refero@refero

The first command adds the repository as a plugin marketplace; the second installs the `refero` plugin from that marketplace. The package’s Claude manifest identifies the plugin as Refero version `1.0.2`. Because the plugin includes MCP configuration, the README does not require a separate MCP command for this installation path.

If you already installed only the skill, or otherwise need to configure Refero MCP directly, the skill documents this command:

claude mcp add --transport http refero https://api.refero.design/mcp

Then run the following inside Claude Code and sign in when prompted:

/mcp

This registers an HTTP MCP server named `refero` at the documented production URL. Authentication occurs through OAuth; access tokens are not embedded in the repository manifests.

To install only the methodology as a standalone Agent Skill, use:

npx skills add https://github.com/referodesign/refero_skill --skill refero-design

This is appropriate when Refero MCP is already configured or when only the bundled research and craft methodology is wanted. For a manual installation, copy the entire `skills/refero-design/` directory—not only `SKILL.md`—into the client’s skills directory so all adjacent `references/` files remain available.

Older clones put `SKILL.md` at repository root. Remove that older installation before reinstalling the current standalone skill. Keeping both the root layout and `skills/refero-design/SKILL.md` creates duplicate skills. No source-supported removal command is supplied, so use your client’s normal file-management interface rather than an invented shell command.

3. Installation in Codex, ChatGPT, Gemini CLI, and Cursor

Refero also packages the same skill-and-MCP concept for several other clients. These paths do not change the documented research workflow.

For the Codex app or CLI, add the GitHub marketplace and install the plugin:

codex plugin marketplace add referodesign/refero_skill
codex plugin add refero@refero

Restart the application after installation. On the first connection, Refero opens in a browser for OAuth sign-in. The Codex package declares read capability and points its skills and MCP server entries at `./skills/` and `./.mcp.json`.

For ChatGPT/Codex, the README also provides a first-party installation link in the OpenAI Plugins Directory:

<https://chatgpt.com/plugins/plugin_asdk_app_6a72258e6f18819183e5c4d8a56b78d9>

That plugin includes both Refero MCP and Refero Skill. Sign in to a Refero account when prompted; no manual MCP configuration or separate skill installation is documented for this route.

For Gemini CLI, install the GitHub repository as an extension:

gemini extensions install https://github.com/referodesign/refero_skill

For Cursor, the README says marketplace installation depends on listing approval. Once available, open Cursor’s plugin marketplace or enter:

/add-plugin

Then search for **Refero**. The Cursor manifest points to `./skills/` and `./mcp.json`.

Do not substitute undocumented package-manager, cloning, or authentication commands. Across supported manifests, the connection is intended to use the same production MCP endpoint without committed access tokens. Live service use still depends on OAuth and the stated paid-plan requirement; bundled craft references remain usable without an account.

4. Starting a design task: brief and workflow selection

Activate `refero-design` for UI, product, web, landing-page, dashboard, redesign, frontend styling, design-system, responsive, typography, color, spacing, motion, icon, accessibility, copywriting, conversion, and anti-generic-design work. Its central rule is to research before implementation, even when live MCP tools are unavailable. Without MCP, use bundled craft references and user-provided references while preserving the same reference-lock process.

Begin with a short brief. Ask only about missing facts that would materially alter the result; otherwise state reasonable assumptions and continue. The documented copy-paste format is:

Designing [WHAT] for [WHO] on [PLATFORM].
Goal: [PRIMARY USER GOAL].
Tone: [DESIRED FEELING].
Main objection/risk: [OBJECTION].
Must remember: [HOOK OR DISTINCTIVE IDEA].
Constraints: [CONSTRAINTS].
Research needed: [styles/screens/flows].
Path: [direct build / visual exploration / audit / asset generation].

Choose the lightest suitable route:

• **Direct build:** small fixes, clear production edits, existing design-system work, or a concrete source to match. Research, lock the direction, then code.
• **Visual exploration:** new visual language, major redesign, landing page, high-visibility surface, or requested variants. The skill defaults to three reference-locked options and user selection.
• **Audit:** critique from captured screenshots, Refero screens, or flows rather than memory.
• **Asset generation:** generate bitmap imagery only when the selected direction requires media that code, icons, or existing assets cannot represent faithfully.

Before building, lock either a user-supplied visual source, an existing product or design-system target, a selected generated mockup, or an explicit research-backed direction approved for direct implementation. Image generation is optional: use it when it changes the result, but skip it for small fixes, obvious production edits, or code-native UI.

5. Complete guide to the documented Refero MCP tools

Refero exposes three research layers. **Styles** establish taste and visual language; **screens** reveal concrete interface decisions; **flows** explain journey sequence. The documented MCP functions are:

• `refero_search_styles`: search semantic style references for visual work. Start here for design, redesign, polish, or any visual component. Search several angles, including broad aesthetic, domain, and relevant product or brand queries.
• `refero_get_style`: retrieve a full selected style, including its visual thesis, tokens, typography, layout, rhythm, spacing, surfaces, components, imagery, implementation notes, and do/don’t guidance. Full records are large, so retrieve strong candidates in manageable batches.
• `refero_search_screens`: find real screens by page type, component, state, company, product, or visible text. Use it for dashboards, settings, tables, modals, forms, pricing, authentication, empty states, copy, and CTA patterns.
• `refero_get_screen`: retrieve full details for a promising screen.
• `refero_get_similar_screens`: expand research outward from one strong screen.
• `refero_get_screen_image`: obtain the raw screenshot only when direct image inspection is needed.
• `refero_search_flows`: find multi-step journeys such as onboarding, signup, checkout, cancellation, account deletion, password reset, profile changes, or subscription management.
• `refero_get_flow`: retrieve a selected flow’s step-by-step goals, user actions, system responses, and completion states.

Styles currently cover web marketing and product pages—such as landing, pricing, editorial brand, SaaS, and product-marketing sites—not in-app dashboards, settings, authentication, or iOS screens as style systems. For product UI, still use styles to set visual language, then screens and flows for product details.

No supplied file documents tool argument syntax, so do not invent MCP calls. Use plain search phrases such as `editorial monochrome SaaS landing page`, `dashboard empty state`, or `signup onboarding` through the client’s exposed MCP interface.

6. Research, reference locking, synthesis, and decision records

For visual work, search three to five angles, retrieve three or four strong full styles, compare their contributions, choose one dominant foundation, and borrow only one or two bounded details from secondary references. Never copy a single source or average conflicting references into a generic middle. Preserve source roles: a CTA color remains CTA-only, syntax color remains inside code, and a decorative gradient remains decorative.

Use this documented reference lock before implementation:

Primary reference/direction: [one dominant source]
Preserve: [3-5 traits that must survive: canvas, type, accent, layout, density, media]
Borrow only: [1-2 specific secondary details]
Role rules: [source token/component meanings to preserve, e.g. CTA-only, code-only, decorative-only]
Media strategy: [real/generated/stock/code-native/placeholder, with aspect ratio and art direction]
Reject: [defaults/averages that would collapse the direction]
Token commitments: [background, type, accent, radius, border/shadow, imagery treatment, with roles]

From screens, extract layout, hierarchy, components, CTA and copy patterns, states, edge cases, trust tactics, and details worth adapting. From flows, extract entry and exit states, step count, decisions, friction reducers, confirmations, recovery, errors, persuasion moments, and each system response. If flow results are sparse, broaden the query; if still sparse, use screens to reconstruct the journey.

Match depth to risk. A quick visual improvement uses two or three style searches and full styles. A major redesign uses three to five searches, three or four full styles, and screen research. A product workflow combines all three layers. Ambiguous or high-stakes work should compare multiple angles and document tradeoffs.

Before implementation, separate findings into visual direction, product pattern, and journey logic. Present a concise summary rather than dumping results. Then record every major choice in the documented ledger:

| Decision | Source | Source rule / role | Why | |----------|--------|--------------------|-----| | [palette/type/layout/media/content choice] | [style/screen/flow/user constraint/craft rule] | [token/component/media role to preserve] | [specific rationale] |

Research again, justify, or remove any major choice that has no source.

7. Craft execution, media handling, and quality assurance

After synthesis, define implementation tokens for type scale, colors, spacing, radius, and shadows. Preserve the dominant reference’s distinctive traits rather than normalizing them. The skill links separate bundled references for typography, color, motion, icons, forms, focus, images, touch, performance, accessibility, copywriting, persuasion, visual workflow, and anti-AI-slop checks. Load only the references relevant to the task.

Use colors justified by research instead of defaulting to indigo or violet. Avoid unsupported generic structures such as hero → feature grid → pricing → FAQ → CTA. Likewise, do not default to warm cream canvases, olive/clay/terracotta palettes, or decorative serif, italic, script, or accent-color word swaps merely to signal “calm editorial.” Use product evidence for section order, copy, trust signals, and objection handling. Include at least one memorable visual, interaction, layout, or copy detail.

Respect media roles. If a direction depends on photography, illustration, product imagery, or graphics, retain that role. Prefer suitable real, generated, or stock assets when available. If an asset cannot be produced, preserve a stable slot with dimensions, aspect ratio, alt text or caption, and a short art-direction note. Do not imitate complex media with weak CSS boxes. Use simple diagrams, icons, code windows, or geometry only when they fit the source.

For text, apply `text-wrap: balance` to headings and short display copy, and use `text-wrap: pretty` selectively for prose. Inspect important breakpoints for orphaned words and awkward last lines. Accessibility and responsive behavior belong in the initial design rather than a final patch.

After substantial visual implementation, compare the rendered result with the locked reference or target. Correct drift in canvas, typography, accent use, layout, density, media, token roles, responsive behavior, and accessibility. Confirm that styles informed taste, screens informed concrete UI where needed, flows informed sequences, multiple references were synthesized without copying, every major decision is traceable, and the result fits the audience and constraints.

8. Release validation, security, and evidence limits

Repository maintainers can run the one documented release check from the repository root:

scripts/check-release

The README says this validates manifests, versions, local links, the canonical MCP URL, package boundaries, and common secret leaks. It does **not** replace platform-native validation or clean-profile installation tests; those are reportedly performed before a release tag. No additional build, test, publish, update, or uninstall commands are documented in the supplied files, so none should be inferred.

Report vulnerabilities privately rather than opening a public issue:

support@refero.design

The security policy states that Refero will respond within 48 hours and work to address the issue promptly. The plugin manifests also identify Refero’s support, privacy-policy, and terms pages, while the repository itself is MIT-licensed.

Operational boundaries matter. MCP access is described as read-only, but live searches still communicate with the external Refero production service and require OAuth. The supplied files do not describe retention, request contents, rate limits, availability guarantees, offline caching, minimum Claude Code versions, or a host compatibility matrix. Consult the linked Refero privacy policy and terms before submitting sensitive design context.

The repository documents methodology and tool routing; it does not claim to edit Figma files, generate production assets automatically, deploy code, or guarantee design quality. Generated imagery may be unavailable in a coding environment. Style coverage is currently centered on web marketing/product pages. Visual QA, accessibility, responsive behavior, copy claims, and implementation correctness still require rendered inspection and human judgment.

Finally, this manual is limited to the supplied README, security policy, plugin manifests, canonical skill, OpenAI agent interface file, and GitHub metadata. Referenced craft and visual-workflow files were named but not supplied, so their undocumented details are intentionally not reconstructed.