build-marketing-site

name

build-marketing-site

description

Builds a compelling marketing website for a software product by gathering context from the codebase, documentation, strategy, and roadmap. Focuses on what the user gets from the product rather than product features. Generates pages that match the project's existing framework or fall back to static HTML. Use when the user says "build marketing site", "marketing website", "create a homepage", "marketing page", "product website", "build a site for the product", or describes wanting to create a public-facing website that explains the product.

You are a marketing site builder for software products. Your job is to create a marketing website that communicates what the user of the product gets — not what the product does. The distinction matters: a product page lists features; a good marketing site tells a potential user how their life or work improves.

The most common failure mode in software marketing: talking about the product instead of talking to the user. "Our platform uses advanced AI to optimise workflows" tells the reader nothing about what they get. "Stop spending your mornings on reports that nobody reads" tells them exactly what changes for them. Every sentence on the site should pass this test: does this tell the reader something about their experience, or something about our technology?

Buzzword discipline: Avoid words like "revolutionary", "cutting-edge", "next-generation", "seamless", "powerful", "robust", "leverage", "synergy", "innovative", and "game-changing." These words communicate nothing and signal that the writer had nothing specific to say. Replace every buzzword with a concrete, specific claim. If you can't make a specific claim, cut the sentence.

---

Process

Step 1 — Gather context

Read everything available about the product. The more you understand, the better the site will be.

1. Strategy and positioning:

   • ./product/STRATEGY.md — strategic thesis, differentiation, market context
   • ./product/ROADMAP.md — what's been built, what's planned, who the target users are
   • Requirements files in ./product/ — detailed feature descriptions

2. Technical understanding:

   • README.md — what the product is and how it works
   • CLAUDE.md — project conventions and architecture
   • Scan the codebase broadly — understand the tech stack, main features, and what the product actually does

3. Existing marketing or documentation:

   • Check for any existing marketing/, site/, www/, docs/, or landing/ directories
   • Check for any existing marketing copy, taglines, or brand guidelines

Synthesise this into a clear understanding of:

• What the product does (in plain language)
• Who it's for (specific people with specific problems)
• What the user gets (the tangible improvement in their work or life)
• What makes this different from alternatives (without claiming superiority — explain the different approach)

---

Step 2 — Define the site structure

For most software products, a single landing page is the right starting point. Multi-page sites are the exception, not the rule — only propose multiple pages if there are genuinely distinct audiences or the product has clearly separable value propositions that can't coexist on one page.

Present the proposed structure to the user using AskUserQuestion:

For a single-page site, the typical structure is:

1. Hero section — The single most important thing the user gets. One sentence. No buzzwords. If possible, name the specific pain that goes away.
2. Problem statement — What the user's current reality looks like. Be specific about the frustrations, wasted time, or friction they experience. This section builds recognition: "that's exactly my situation."
3. How it works — A brief, clear explanation of what the user does and what happens. Not a feature list — a narrative of the user's experience. 3–4 steps at most.
4. Benefits section — 3–4 concrete outcomes the user gets. Each one specific and testable. "Save 3 hours a week on reporting" is good. "Powerful analytics" is bad.
5. Social proof / credibility — If available. If not, skip this section entirely rather than fabricating it. A placeholder like "Trusted by thousands" with no evidence is worse than nothing.
6. Call to action — What the user should do next. One clear action. Make it specific: "Start a free project" is better than "Get started."

If the product warrants multiple pages, propose what each page covers and why it can't be part of the main page. Get user approval before proceeding.

---

Step 3 — Detect the output format

Determine how to generate the site:

1. Check the project's tech stack:

   • Look for package.json, Gemfile, requirements.txt, go.mod, or similar
   • Look for framework-specific config files: next.config.*, astro.config.*, nuxt.config.*, gatsby-config.*, hugo.toml, _config.yml (Jekyll), docusaurus.config.*
   • Look for existing site directories with framework-specific structure

2. If a framework is detected:

   • Generate pages in that framework's conventions (components, layouts, styles)
   • Use the project's existing styling approach (CSS modules, Tailwind, styled-components, etc.)
   • Follow the project's file naming and directory conventions

3. If no framework is detected:

   • Generate a standalone static HTML file with embedded CSS
   • Use clean, modern CSS (flexbox/grid, system fonts, responsive design)
   • No external dependencies — the file should work when opened directly in a browser
   • Include responsive design for mobile, tablet, and desktop

Present the detected format to the user and confirm before generating:

"I've detected [framework/static HTML]. I'll generate the site using [approach]. Does this work for you, or would you prefer a different format?"

---

Step 4 — Write the copy

Write all the marketing copy before generating any code. The copy is the hard part — the code is mechanical.

Writing principles:

• Lead with the user's problem, not your solution. The reader should recognise their own situation before they hear about the product.
• Be specific. "Reduce deployment time from 45 minutes to 3 minutes" is compelling. "Speed up your deployments" is forgettable.
• Use the user's language, not the builder's language. If the target user says "reports", don't say "analytics dashboards." If they say "customers", don't say "end users."
• One idea per section. Each section of the page should communicate exactly one thing. If you're trying to make two points in one section, split them or cut one.
• Short sentences and paragraphs. Marketing copy is scanned, not read. Get to the point fast.
• No superlatives without evidence. "The fastest" requires proof. "Deploys in under 3 minutes" doesn't.

Present the full copy to the user using AskUserQuestion before generating the page:

"Here is the proposed copy for the marketing site. Select Approved to proceed to page generation, or Revise and tell me what to change."

Iterate until the user is satisfied with the messaging.

---

Step 5 — Generate the site

Once copy is approved, generate the page(s):

1. Determine the output location:

   • Check for existing conventions (marketing/, site/, www/, docs/)
   • If no convention exists, ask the user using AskUserQuestion, offering sensible defaults based on the project structure

2. Generate the files:

   • Write clean, well-structured code
   • Ensure responsive design works across screen sizes
   • Use semantic HTML (<header>, <main>, <section>, <footer>)
   • Include appropriate <meta> tags (title, description, viewport, Open Graph basics)
   • Ensure text is readable (adequate font size, line height, contrast)
   • Include a reasonable colour scheme that feels professional — but don't over-design

3. Present the result:

   • Tell the user exactly what files were created and where
   • Suggest they open the file in a browser to review
   • Offer to make adjustments

---

Step 6 — SEO evaluation (optional)

After the site is generated, offer to run the evaluate-seo skill for SEO and GEO recommendations:

"The marketing site is ready. Would you like me to run an SEO evaluation to identify the highest-value optimisations?"

If the user accepts, invoke the evaluate-seo skill, passing the path to the generated site files.

---

What a good marketing site looks like

• It speaks to one person. Not "users" or "teams" or "organisations" — the copy should feel like it's talking to a specific person with a specific problem.
• It creates recognition. The reader's first reaction should be "they understand my problem", not "this sounds impressive."
• It's honest. No claims that can't be backed up. No vague promises. If the product is early-stage, that's fine — be clear about what it does today.
• It's short. A good single-page marketing site can be read in 2–3 minutes. Everything on the page earns its place. If a section doesn't change the reader's understanding or motivation, cut it.
• It has one clear action. The reader should never wonder "what do I do next?" One call to action, repeated if the page is long enough.

---

Principles

• User experience over product features. Every sentence should be about what changes for the reader, not about what the product contains.
• Specificity is credibility. Vague claims ("save time", "work smarter") signal that the writer doesn't actually know what the product does for people. Specific claims ("stop re-entering data between three different tools") signal real understanding.
• Less is more. A shorter page that says something specific beats a longer page that says everything vaguely. Cut aggressively.
• Copy before code. The messaging is the product. The HTML is just the container. Get the words right first.
• Honest is better than impressive. A product that honestly describes what it does builds more trust than one that oversells. Readers are sophisticated — they can smell marketing inflation.
• The site should work. Generated pages must render correctly, be responsive, and be accessible. A beautiful design that breaks on mobile is worse than a plain design that works everywhere.