site-spec

A short interview before a new site gets built — how it should be laid out, how it should look, and what it needs to be able to do — written up as the plan everything after it follows.

WHEN TO USE

SCOPE

USE FOR

Settle whether a new site should be one scrollable page or several separate pages.
Pick a look and a layout for a site from guided visual options instead of guessing blind.
Find out which add-ons the site will need — a shop, a contact form, a newsletter — before building.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (5)

Site Spec Discovery

Before building a WordPress site, gather the user's basic preferences through a short interactive discovery phase. This produces a Site Spec that guides all subsequent design and development decisions.

Precondition: an active site

This skill works on the active site — the one announced at the top of the user's message. If there is no active site, stop and let the user know.

How to Run

AskUserQuestion constraints: Each call supports 1-4 questions, each with 2-4 options. An "Other" free-form option is automatically provided by the system — do NOT add one yourself. Keep option labels short (1-5 words). Only use AskUserQuestion for questions that have meaningful predefined options. For open-ended questions, just ask in your text output — the user will type their answer in the prompt.

Use AskUserQuestion for:

One-page site or multi-page site? (e.g., single scrollable page with sections vs. separate pages for each area)

The business/brand name is the active site's name unless the prompt gives a different one. Do not ask for it. The one exception: when the site name is clearly a placeholder (e.g. "test", "Site 1") and the prompt gives no brand, ask for the brand name in your text output and stop and wait for the reply — do NOT call any tools in that turn.

A new site's spec needs nothing from the site itself: do not search its files or list its plugins and themes before the design is settled.

The design

Load the visual-design skill first — the catalogs, the DESIGN.md format, and the sneak-peek rules live there — and follow its "Concept and Direction" runbook. The design is settled in two steps, the look and then the layout, each with one pick_design call, repeated only when the user asks for other options:

Pass options: 4 so the user picks, or options: 1 when there is nothing to pick — the user asked to be surprised or to skip the questions, or the brief names the entry. For a reference site, look at it once with take_screenshot (display: false) and choose its closest entries, with options set to their number: two when present_design_options is available, otherwise one.
With one entry, use it without asking. With more, ask once, one option per entry in the order returned, labelled with the entry's name, without describing the options in prose first. A typed answer ("2 but darker") is a preference to apply to the closest option; asking for other options, as a choice or in their own words, means drawing that step again and asking the same way.

The look: catalog: "directions", asking "Which look should I build?". Skip this step when the active-site line names a design system and the user did not ask for a new look.
- If present_design_options is available: when generate_images is available too, load the imagery skill and generate the look image first. Pass each option's DESIGN.md draft (see the visual-design skill) as its preview, with that image and a one-line description of the feel.
- Otherwise use AskUserQuestion, each option with a one-line description of the look.
- Write the picked look to DESIGN.md at the site root: the draft's front matter exactly as the user saw it, then every section. Then, when generate_images is available, generate the site's image set in that look (see the imagery skill) so the layout previews and the build have it.
The layout: catalog: "layouts", asking "Which layout should I build?".
- If present_design_options is available: pass one sneak peek per option, in the picked look and with the site's image set (see the visual-design skill), as its preview, with a one-line description of the layout.
- Otherwise use AskUserQuestion, each option with a one-line description of how its first screen would look.
- Add the picked layout to the Layout section of DESIGN.md, then build it.

After Gathering Answers

Use the layout preference to guide all subsequent design decisions.

State the plan as a short Site Spec summary before building. The summary MUST include a Concept line — the signature layout concept settled by pick_design or picked by the user, as Concept: <catalog name> — <one-line adaptation>, the entry's name verbatim so the user can find it, then the twist — followed by a Layout map (as the visual-design skill defines it: one line per section of the page saying what the concept does to it), a Direction line — the artistic direction behind DESIGN.md, as Direction: <catalog name> — <one-line adaptation> — and a Functionality & plugins line. A side designed from the brief rather than the catalog is stated as Concept: <the brief's words> — <how it is built> or Direction: <the brief's words> — <how it is built>. For the plugins line: review the requested features, load the plugin-recommendations skill, and list the specific plugins the site needs — e.g. WooCommerce for selling products, Jetpack Forms for a contact form, Jetpack Newsletter for email signups, Sensei LMS for courses, Crowdsignal for polls/surveys — or "None — core blocks only" when nothing beyond static content is required. Install the listed plugins while building (Workflow Step 3); do not silently hand-build static markup for a feature a plugin should provide.

When to Skip the Questions

Skipping means skipping the interactive questions only — each design step then returns a single entry, DESIGN.md is still written, and you still produce the Site Spec summary (including the Functionality & plugins line) before building. Do NOT ask questions if:

The user already provided the layout preference in the initial prompt.
The user says "just build something" or "surprise me". Pick a bold creative direction yourself and proceed.
The user explicitly asks to skip the setup or says they don't want questions.

Built into Studio Code, the AI agent in WordPress Studio. Nothing to install there: it comes with the Studio app and the Studio CLI. Studio Code is in beta and needs a WordPress.com login with a payment method on file. The npx skills add command copies the same instructions into another agent, but each one calls tools built into Studio, such as site_info or validate_blocks.

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add automattic/studio --skill "site-spec" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

View on GitHub

Site Spec Discovery

Precondition: an active site

How to Run

The design

After Gathering Answers

When to Skip the Questions

No requirements beyond installing this skill were found.

More skills

annotate

block-content

hosting-plans-helper

imagery

liberate

need-for-speed