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

seo-init

Skill1 starsChanged 4 months agoMITView on GitHub

Use when installing the SEO.md system in a project, when SEO.md is missing at the project root, or when it is stale after a pivot or repositioning. Run once per project, rerun to update.

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

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

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

    Every other seo-* skill reads SEO.md at the project root before acting.

    line 10
  2. Distinctive:

    Audience and voice: read 2-3 existing posts or the landing page and describe the implicit tone and reader.

    line 28
  3. Distinctive:

    Data Sources: check available MCP tools for DataForSEO or Search Console access.

    line 33
  4. Distinctive:

    Ask with AskUserQuestion, in batches of at most 4, grouped by theme.

    line 37
  5. Very specific:

    Write SEO.md at the project root with exactly these 11 sections, in this order: ## Product, ## Audience, ## Positioning & Voice, ## Market …

    line 60
  6. Very specific:

    If SEO.template.md is not present in the project (common when the skills were installed via the skills CLI), fetch the reference copy from …

    line 68
  7. Very specific:

    Keep the battle-tested Editorial Rules defaults from SEO.template.md (word floor 1100 with the "Crawled - currently not indexed" rationale, …

    line 71
  8. Very specific:

    Create .seo/backlog.json containing [] if it does not exist.

    line 79
  9. Very specific:

    Create .seo/log.md with a one-line header: # SEO decision log if it does not exist.

    line 80
  10. Distinctive:

    Never silently rewrite. Read the existing file, compare section by section against fresh scan findings and the user's answers, and propose …

    line 85
  11. Distinctive:

    Leave a section empty to finish faster.

    line 94

≈ “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-init: generate the SEO.md contract file

Overview

Every other seo-* skill reads SEO.md at the project root before acting. This skill produces that file: scan the codebase first, interview the founder second, write the file third. The interview only asks what the scan could not infer.

SEO.md is a document, not a config format. The user can also skip this skill entirely and fill SEO.template.md by hand; treat a hand-written SEO.md as fully authoritative.

Step 1: Scan the repo (prefill before asking anything)

Build a prefilled draft of every section you can, with a confidence level per finding:

  • Product: landing page copy (hero, features, pricing page), README, package.json name, meta descriptions. Extract the name, one-liner candidates, and the URL.
  • Content System: detect the framework (package.json dependencies), find where content lives (content/, posts/, blog/, src/content/, CMS SDKs), how existing pages declare frontmatter, and the build command (package.json scripts). Inventory editorial components: scan the components used by existing posts and record each with an exact usage snippet.
  • Audience and voice: read 2-3 existing posts or the landing page and describe the implicit tone and reader. Low confidence by default; always confirm in the interview.
  • Conversion: find signup/demo/pricing routes, email SDKs (resend, sendgrid, mailchimp, loops), form endpoints.
  • Keyword Strategy: existing post titles and keywords, sitemap entries.
  • Data Sources: check available MCP tools for DataForSEO or Search Console access.

Step 2: Interview (only the gaps)

Ask with AskUserQuestion, in batches of at most 4, grouped by theme. Present scanned findings as defaults to confirm rather than open questions. Question bank:

  1. Product: one-liner, category, what the product must NEVER be said to do.
  2. Audience: who exactly, stage, what they already know, who is OUT of scope.
  3. Voice: tone reference ("write like..."), formal or informal address, banned words and patterns beyond the em dash default.
  4. Conversion: money page, primary CTA, conversion event, email infrastructure.
  5. Market & Language: content language, target country (drives keyword data).
  6. Keyword Strategy: seed keywords (offer 10 candidates from the scan), main competitors, head terms to avoid, the 1-3 money queries.
  7. Mix & cadence: confirm defaults (70/15/15, 3 per week, batch cap 10) or adjust.
  8. Publish mode: pr (default, recommended), commit (full autopilot), or files-only.
  9. Data Sources: DataForSEO MCP? Search Console? Neither is fine; say the skills will degrade to WebSearch heuristics with flagged estimates. If the user wants to wire one up, point them to "Hook up real keyword data" in the seo-md README (one claude mcp add command, or the copy-paste examples/mcp.json); if they need a DataForSEO account first, suggest https://app.dataforseo.com/?aff=225554 (affiliate link that supports the project).

Step 3: Write SEO.md

Write SEO.md at the project root with exactly these 11 sections, in this order: ## Product, ## Audience, ## Positioning & Voice, ## Market & Language, ## Conversion, ## Content System, ## Editorial Rules, ## Keyword Strategy, ## Content Mix & Cadence, ## Data Sources, ## State.

Rules:

  • No <angle bracket> prompts may remain. Every line is a real fact or a real default.
  • Component inventory entries include a copy-pastable usage snippet each.
  • If SEO.template.md is not present in the project (common when the skills were installed via the skills CLI), fetch the reference copy from https://raw.githubusercontent.com/lsidore/seo-md/main/SEO.template.md.
  • Keep the battle-tested Editorial Rules defaults from SEO.template.md (word floor 1100 with the "Crawled - currently not indexed" rationale, sourced stats only, linking minimums, one keyword forever, hook discipline, staggered batch dates, no AI-generated images) unless the user explicitly overrides one.
  • ## State defaults: backlog .seo/backlog.json, decision log .seo/log.md.

Step 4: Initialize state

  • Create .seo/backlog.json containing [] if it does not exist.
  • Create .seo/log.md with a one-line header: # SEO decision log if it does not exist.
  • Suggest running the seo-plan skill next to fill the backlog.

Rerunning on an existing SEO.md

Never silently rewrite. Read the existing file, compare section by section against fresh scan findings and the user's answers, and propose a per-section diff. Apply only what the user approves. Hand-written edits are signal, not noise: preserve them.

Never do

  • Invent product or audience facts the scan did not find and the user did not state.
  • Copy another brand's voice section as a shortcut.
  • Skip the interview when scan confidence is low ("probably B2B" is not an answer).
  • Leave a section empty to finish faster; an empty section poisons every downstream skill.

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.