referodesign/refero_skill installation guide

Install Refero for Claude Code on macOS Tahoe (Apple silicon)

What you are installing

**Repository:** `referodesign/refero_skill` **License:** MIT **Claude Code classification:** **Claude Code extension** using **context injection** and a **tool surface** **Setup effort:** Low

This classification is supported by the repository’s Claude plugin manifest and README. The plugin adds two related pieces to Claude Code:

1. **Refero Design**, a Markdown skill that gives Claude a research-first workflow for UI, UX, product, web, landing-page, dashboard, frontend styling, design-system, accessibility, and copywriting work.
2. **Refero MCP**, a read-only connection through which Claude can research Refero’s visual styles, real product screens, and user flows.

The skill supplies methodology and bundled craft references as context. The MCP connection supplies additional research tools. This is not a standalone design application and does not replace Claude Code.

The supplied repository files do not state a minimum Claude Code version, require Rosetta, or identify any Apple-silicon-specific dependency. They also do not document how to install Claude Code itself. This walkthrough therefore assumes that Claude Code is already installed and working on your Mac. Do not invent or substitute Terminal installation commands from third-party sources.

Accounts and cost

The bundled design methodology and craft references do **not** require a Refero account. Live research through Refero MCP uses browser-based OAuth sign-in. The README says live Refero research requires a **paid Refero plan**.

All supplied connection manifests point to the production endpoint:

`https://api.refero.design/mcp`

The repository says its manifests contain no access tokens. Authentication happens when the MCP connection opens Refero in your browser.

Recommended installation: the Claude Code plugin

Use the plugin route when you want both the design skill and the preconfigured, read-only Refero MCP connection. The repository explicitly documents these two Claude Code commands.

Step 1: Open Claude Code

Start Claude Code normally on your Mac and open its interactive prompt. The next entries are **Claude Code slash commands**, not macOS Terminal commands. Enter each command separately and wait for it to finish before entering the next one.

Step 2: Add Refero’s plugin marketplace

Copy and paste this into Claude Code:

/plugin marketplace add referodesign/refero_skill

This registers the public GitHub repository as a plugin marketplace source.

Step 3: Install the Refero plugin

Copy and paste this into Claude Code:

/plugin install refero@refero

The first `refero` is the plugin name; the second identifies the marketplace added in the preceding step. The repository’s Claude plugin manifest identifies the plugin as **Refero**, version **1.0.2**, and describes it as a way to research real product interfaces and design with evidence.

No separate skill-copying command or manual MCP configuration is documented as necessary for this plugin path. The README states that `.mcp.json` provides Refero MCP for Claude Code plugin installations, while `skills/refero-design/` contains the canonical skill and its supporting references.

Connect Refero MCP

After installation, copy and paste the following slash command into Claude Code:

/mcp

Use Claude Code’s resulting MCP interface to connect or authenticate Refero. When prompted, complete the OAuth sign-in in the browser. The supplied files do not document the exact labels or buttons shown by Claude Code, so follow the on-screen prompts rather than looking for an undocumented menu name.

If you do not have a paid Refero plan, the skill remains useful with its bundled references, but the README says live Refero research requires a paid plan.

Confirm that it is working

There is no repository-documented installation-test command specifically for Claude Code, so do not run an invented diagnostic. Instead, make a normal design request in Claude Code. For example, ask Claude to research references before designing an interface.

A working installation should make the Refero Design skill available for relevant design tasks. With an authenticated MCP connection, it can also use Refero research for:

• visual direction and taste through styles;
• concrete interface patterns through screens;
• multi-step journey logic through flows.

The repository describes the connection as read-only. The skill instructs Claude to research and synthesize references before implementation, establish a reference lock and decision ledger, and compare substantial visual work with the selected direction before handoff.

Do not expect a separate macOS application window from this repository. Its functionality appears within Claude Code as a skill and MCP-backed tools.

Optional alternative: install only the standalone skill

Use this alternative only when you want the design methodology without the full Claude plugin, or when your client already has Refero MCP configured. This path requires `npx`, but the supplied files do not state how to install Node.js or npm. If `npx` is not already available, use the recommended Claude plugin route rather than following undocumented setup commands.

In macOS Terminal, copy and paste:

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

This is the only documented standalone installation command. It installs the canonical skill from `skills/refero-design/`, including references used for typography, color, motion, icons, accessibility, copywriting, visual workflow, and related craft guidance.

An older repository layout placed `SKILL.md` at the repository root. The README warns that retaining both old and current layouts creates duplicate skills. It says to remove the old installation and run the standalone command again, but it does not provide a safe, exact removal command or identify the old local path. For that reason, this guide cannot supply a copy-paste deletion command. Inspect your existing skills and remove an old root-layout copy through the client’s documented interface before reinstalling.

Do not combine the standalone installation with the plugin unless you deliberately need both and have confirmed that Claude Code will not expose duplicate copies of the skill.

Optional alternative: manually add only the MCP connection

The skill file documents a manual MCP setup command. Use this only if you installed the standalone skill, skipped the plugin, and want live Refero research. In macOS Terminal, copy and paste:

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

Then return to Claude Code and run:

/mcp

Complete Refero sign-in when prompted. Do not run this manual MCP command after a normal plugin installation unless the plugin-provided connection is absent: the plugin already includes `.mcp.json`, and the repository does not recommend creating a duplicate connection.

What not to run

The repository documents this command for maintainers validating a release:

`scripts/check-release`

It checks manifests, versions, links, the canonical MCP URL, package boundaries, and common secret leaks. It is **not** part of end-user installation, so do not run it for this setup.

The supplied files provide no documented Claude Code commands for updating, uninstalling, clearing OAuth credentials, or removing the marketplace. This guide therefore does not invent any. Use Claude Code’s first-party plugin management interface if you later need those operations.

Privacy, permissions, and troubleshooting

Refero MCP connects to an external production service. Queries and authentication are therefore subject to Refero’s privacy policy and terms linked from the plugin metadata. Review them before submitting confidential product details, screenshots, flows, or design briefs. The repository characterizes the MCP capability as read-only, meaning its stated purpose is research rather than modifying Refero data.

If the skill works but live searches do not, first run `/mcp` and check the displayed connection or authentication state. Confirm that browser sign-in completed and remember that the README requires a paid plan for live research. If the standalone skill is missing its detailed guidance, reinstall it with the documented `npx skills add` command so the whole skill directory and its `references/` files remain together.

For a suspected security vulnerability, do not open a public issue. The repository’s security policy asks users to report it privately to `support@refero.design` and says the maintainers will respond within 48 hours.