agentleFS
lsidorelsidore/seo-md/skills/seo-tool/SKILL.md

seo-tool

Skill1 starsChanged 4 months agoMITView on GitHub

Use when the backlog's top opportunity is a tool-intent keyword (calculator, generator, checker, template, quiz), typically invoked by seo-run. Builds one free interactive tool page in the host project's own stack and design system.

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 9 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read SEO.md at the project root, in full.

    line 10
  2. Distinctive:

    Never invent product or audience facts that are not in SEO.md.

    line 13
  3. Very specific:

    Default paths (overridable in SEO.md § State): backlog .seo/backlog.json.

    line 14
  4. Distinctive:

    Write a 5-line spec first:

    line 21
  5. Distinctive:

    Use the framework, components, and design tokens the project already has (SEO.md § Content System plus what you observe in the codebase).

    line 32
  6. Distinctive:

    No one-off styles, no new UI library, no new dependency without asking the user first.

    line 36
  7. Distinctive:

    Prefer client-side logic. If the tool needs an LLM call or server logic, check what infrastructure the project already has.

    line 37
  8. Distinctive:

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

    line 52
  9. Distinctive:

    If no email infrastructure: no gate.

    line 58
  10. Distinctive:

    Add the page to the sitemap (or verify the framework does it automatically).

    line 62
  11. Distinctive:

    Add it to the tools hub page if one exists.

    line 64

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.