Seo tool

seo-tool: build one free tool / lead magnet page

Before anything

1. Read SEO.md at the project root, in full. It is the only source of truth for product, audience, voice, rules, and paths. If it does not exist: stop and tell the user to run the seo-init skill (or fill SEO.template.md by hand).
2. Never invent product or audience facts that are not in SEO.md.
3. Default paths (overridable in SEO.md § State): backlog .seo/backlog.json.

Step 1: Pick and spec before building

Take the top-priority todo of type tool from the backlog (same jq pattern as seo-write, with .type == "tool"). If none: report and suggest seo-plan. STOP.

Write a 5-line spec first:

• Inputs: the 2-6 fields the visitor fills.
• Logic: how output derives from inputs (formula, rules, generation).
• Output: what the visitor sees, and why it feels personal, not generic.
• Value moment: the useful result must land in under 60 seconds. If it needs an account, a wait, or reading a manual first, the spec is wrong.
• Intent match: the tool answers the keyword's EXACT intent. A "refund cost calculator" keyword gets a calculator, not an article with a form.

Step 2: Build, on-brand, in the host stack

• Use the framework, components, and design tokens the project already has (SEO.md § Content System plus what you observe in the codebase). The tool page must look like every other page of the site. Hard requirement: brand consistency across all content types is the whole point of the system.
• No one-off styles, no new UI library, no new dependency without asking the user first.
• Prefer client-side logic. If the tool needs an LLM call or server logic, check what infrastructure the project already has; never hardcode secrets.
• Honest outputs only: results derive from the visitor's inputs and stated formulas or clearly labeled benchmark assumptions. Fabricated precision destroys the trust the tool exists to build.

Step 3: Make the page indexable

A bare tool is invisible to search. Around the tool, on the same page, write 600+ words of genuinely useful content: how it works, the methodology and its assumptions, how to interpret results, a short FAQ. Meta rules as in seo-write: title 50-60 chars with the primary keyword, description 140-160.

Step 4: Optional email gate

Only if SEO.md § Conversion declares an email infrastructure:

• Gate the DETAILED result (full breakdown, export, benchmark comparison), never the core value. The visitor gets the headline result ungated in under 60 seconds.
• Wire the capture into the declared infrastructure. A follow-up email sequence is out of scope: note it as a suggestion for the user.

If no email infrastructure: no gate. Do not invent one.

Step 5: Wire it into the site

• Add the page to the sitemap (or verify the framework does it automatically).
• Link to the tool from 1-2 related published articles (edit just those links, nothing else).
• Add it to the tools hub page if one exists.

Step 6: Quality gate (blocking)

• Project build passes (Build & validate command from SEO.md § Content System).
• On-page content >= 600 words (same sed + wc technique as seo-write).
• Banned-pattern grep clean (em dash default).
• The value moment works: walk the happy path once and confirm a real result renders.

Then mark the backlog entry done (same jq as seo-write Step 6) and publish per the SEO.md publish mode.

Never do

• Build in a stack or style foreign to the host project.
• Gate the entire tool behind an email form.
• Ship a tool page with no indexable content around it.
• Fake results, fake benchmarks, or precision the formula cannot justify.
• More than one tool per run.