Skip to Content
For AI & agentsAgent Skill (SKILL.md)

Agent Skill (SKILL.md)

The StyleRef Agent Skill is an instruction layer that teaches any agent when to fetch StyleRef styles and how to apply them per tool. It pairs with the MCP server: the server provides the data and actions, the skill provides the judgment.

Two skills ship together. styleref is the general one — it covers ChatGPT, Claude, Gemini, Midjourney, FLUX, Stable Diffusion, and a repo’s STYLE.md. styleref-figma is built for the Figma agent, where a style becomes real variables and styles on the canvas rather than text in a prompt. Install either on its own; they don’t depend on each other.

What it teaches

The skill (SKILL.md) gives an agent:

  • When to reach for a style — the user wants a consistent aesthetic or brand look for generated content, asks for consistency across generations, or names a style or a styleref.io link.
  • How to fetch one — prefer the MCP tools when available, otherwise the REST API; which format maps to which tool.
  • How to apply it per tool — placement rules for ChatGPT, Claude, Gemini, Midjourney, FLUX, and Stable Diffusion, and the STYLE.md convention for repos.
  • The honest-claims rules — never claim before/after improvement, never claim outputs are “the same across tools,” attribute the style. See below.

Install it

The skill lives at github.com/StyleRef/styleref-skill .

Two commands — the first registers the catalog, the second installs from it:

/plugin marketplace add StyleRef/styleref-skill
/plugin install styleref@styleref

This installs the skill and connects the MCP server at https://styleref.io/api/mcp, so there’s no separate connection step. Reading public styles is anonymous; saving, forking, extracting, and publishing prompt you to connect your account.

On Claude Cowork, Claude.ai, and Claude Desktop, add StyleRef as a connector as well — see the Claude.ai / Cowork / Desktop tab. Those surfaces take the skill from the plugin but not the server it bundles, so without the connector the agent knows how to apply a style and has no way to fetch one.

In Figma

styleref-figma is a separate skill for the Figma agent . Figma takes a skill as a single Markdown file: open the chat prompt box, choose Skills → Add skill → Upload a file, and pick skills/styleref-figma/SKILL.md from the repository. Invoke it with /styleref-figma. Creating and using skills needs a paid Figma plan and a Full seat.

It works differently from the general skill because Figma is a different kind of target — the agent can author real file objects, so a style stops being prompt text:

  • Apply a style to a file. The palette becomes local color variables, the type rules become text styles, and the interface rules become the things they describe: surface levels, elevation, borders, button shapes, icons, navigation, focus rings. The full specification stays in context so anything generated afterwards holds the same look. Where a style sets an accessibility level, contrast pairs are checked against it and reported.
  • Capture the style already on the canvas. Point it at a selection and it reads the colors, type, radii, spacing, and light that are actually there — and, when the selection is an interface, the surface levels, elevation, borders, buttons, icons, navigation, and focus states too. The result is a portable specification you can reuse in another file or in an AI image tool.

Neither needs an account, a plugin, or a connector: the skill reads the public gallery through the agent’s own web fetch. Saving a style to your library, extracting one from an image, and publishing need the MCP server added as a custom connector — in the prompt box, Add context → Connectors → Manage → Created by you → Create, with the server URL from Connect your client.

A style carries one palette, and therefore one theme — light or dark, not both. The skill builds a single-mode variable collection. If you want light and dark modes, it will say the style defines one theme and offer to build the other from values you supply, rather than inverting the palette into a brand you never specified.

A published Figma library with components and variables is a better source of truth than any style specification. Use styleref-figma for looks a library doesn’t cover yet — a brand direction you’re still exploring, or a file that has no library behind it.

When to prefer it over MCP alone

  • MCP alone gives an agent the tools, but not the judgment about when and how to use them. An agent may fetch a style and then paraphrase it, or make claims the results don’t support.
  • The skill plus MCP adds the instruction layer: the agent knows when a request calls for a style, applies the spec verbatim, and describes results accurately.

Use the skill when you want consistent, correct StyleRef behavior across many conversations — not just the raw capability.

The honest-claims rules

The skill enforces the same rules these docs follow:

  • No before/after claims — there’s no unstyled baseline to compare against.
  • No “same across tools” claims — different models render the same spec differently. The accurate claim is consistency per generation within each tool, because every generation receives the same explicit constraints.
  • Attribute the style — keep the Generated by StyleRef.io line and canonical URL, and credit the author’s @handle for gallery styles.

styleref-figma adds two more, because writing to a canvas invites claims a prompt never could:

  • Say which decisions were the agent’s. A specification names a type category — “Display / Decorative” — never a licensed font. The agent picks the actual typeface, and has to say so.
  • No “this matches the reference” claims — applying a specification is not reproducing an image.

Next steps

Last updated on
CLI (npx styleref)llms.txt & markdown endpoints