Skip to main content

Agent skills

This page shows you how to install the Unblock skills in your AI client and use them to build a site over MCP.

What a skill is​

A skill is a set of instructions your AI client loads for one job: plan a site, set its design system, build a page, audit it. Each one says what to do, in which order, and when to ask you.

The skills work with an AI client connected to your site over MCP, such as Claude Code, Cursor or Codex. They are not the skills of the chat in the editor, the / commands of Unblock AI: see Chat skills.

Each skill starts by calling unblock/get-instructions, which holds the rules of Unblock's tools, and adds its method on top. The instructions come from the plugin and change with it, so the skills stay right from one version of Unblock to the next.

Requirements​

  • An AI client connected to your site over MCP: see MCP Bridge.
  • Unblock 1.0 or later.
  • A browser tool, such as Chrome DevTools MCP, is optional for building. With one, the agent looks at each page once at phone and desktop width and fixes what's broken. Without one, you are the eye: the art directions and each page land on a draft whose link the agent gives you. The audits need one for the keyboard, contrast and performance checks.
  • For unblock-from-figma, a Figma MCP server as well.

The skills use tools your client may not list, such as unblock/get-site-settings or unblock/list-media. They run them through execute-ability: see MCP tools.

Install the skills​

With the skills installer:

npx skills add unblockwp/skills

As a Claude Code plugin:

/plugin marketplace add unblockwp/skills
/plugin install unblock-skills@unblock

If your client has no skills support, paste the SKILL.md of the skill you need into the conversation or into your project's instructions. Each skill is a folder of the repository, such as skills/unblock-build-page/SKILL.md.

The skills​

Plan and build​

SkillWhat it does
unblock-site-briefInterviews you and writes the project kit (brief, sitemap, voice, AGENTS.md), then waits for your confirmation before anything is built
unblock-design-systemDraws a visual direction from your site's subject, then writes the tokens, fonts and base styles every page shares
unblock-build-pagePlans a page from its purpose, writes real copy, composes it in one pass on the design system, reviews it before writing, then checks it
unblock-contentWrites and rewrites a page's text in the site's voice: headlines, body, buttons, forms, alt text, title, excerpt, SEO title and meta description. It never changes the layout or the styles
unblock-dynamic-dataConnects pages and templates to WordPress data: post lists, custom fields, terms, pagination, empty states, blog and archive templates
unblock-from-figmaTurns a Figma design into responsive sections, its variables into tokens, its images into the media library

Check​

SkillWhat it reviews
unblock-audit-accessibilityThe pages against WCAG 2.2 AA
unblock-audit-performanceThe Core Web Vitals, measured from a trace, and their causes
unblock-audit-seoIndexing, titles, headings, links, images and structured data
unblock-audit-codeThe markup, the design tokens, the CSS selectors, the scripts and the Twig

The audits change nothing. See Audit your site.

Build a new site​

Run the skills in this order:

  1. unblock-site-brief: the brief, the sitemap and the voice.
  2. unblock-design-system: the look of the site.
  3. unblock-build-page, once per page, then unblock-content and unblock-dynamic-data where a page needs them.
  4. The four audits.

A new site has three stops for you:

  1. The brief. You confirm or correct the kit. Nothing is built before.
  2. The art direction. You pick one of three directions, or mix them.
  3. The draft of the first page. You open its preview link, with the agent's screenshots when it has a browser tool, and give your go before the details.

Between the stops, the skills decide with their defaults and tell you what they chose.

Confirming the brief also approves the header and footer. The agent builds them with the first page, and they show on the site at once: a template has no draft.

Name the skill in your prompt​

An agent does not always load a skill on its own. Start your prompt with the skill's name:

Use the unblock-build-page skill.
Build the About page from its entry in sitemap.md, on the site's design system.
Real copy from brief.md and voice.md; mark anything missing as [To confirm].
Show me the plan first. Build it as a draft, check it at phone and desktop width, and report.

You'll find a prompt for each job in Prompts.

Run your sessions​

  • Connect a browser tool if you can. The agent then looks at each page itself and fixes what's broken before you see it. Without one, open the drafts it links and tell it what you see.
  • Ask for a critique when you want a second eye. With a browser tool, a subagent with a fresh context judges the page against the art direction and names its three worst problems. It runs only when you ask: otherwise your review of the draft is the critique.
  • On a live site, say how you want to review. The skills change a published page or a template only once you agree. Before a redesign, they offer a draft copy you preview before it goes live, or an editor session you open on the page.
  • Give references, not adjectives. When the brief asks for sites you like, answer with links or screenshots.
  • Start with a medium reasoning effort, and a fast output mode when your client has one. In the sessions we measured, most of the time went to the model's reasoning, not to the tools.
Common mistake

Running the whole site in one long session. A session that mixes design, code and audits drifts toward a generic page. Plan and design the site, its pages and their text in one session, then start a new one to connect the dynamic data and run the audits.

Next steps​