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.
In this repository5 other files it gives its agents.
- seo-planSkill
- seo-programmaticSkill
- seo-runSkill
- seo-toolSkill
- seo-writeSkill
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
- Very specific: line 10
Every other seo-* skill reads SEO.md at the project root before acting.
- Distinctive: line 28
Audience and voice: read 2-3 existing posts or the landing page and describe the implicit tone and reader.
- Distinctive: line 33
Data Sources: check available MCP tools for DataForSEO or Search Console access.
- Distinctive: line 37
Ask with AskUserQuestion, in batches of at most 4, grouped by theme.
- Very specific: line 60
Write SEO.md at the project root with exactly these 11 sections, in this order: ## Product, ## Audience, ## Positioning & Voice, ## Market …
- Very specific: line 68
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 …
- Very specific: line 71
Keep the battle-tested Editorial Rules defaults from SEO.template.md (word floor 1100 with the "Crawled - currently not indexed" rationale, …
- Very specific: line 79
Create .seo/backlog.json containing [] if it does not exist.
- Very specific: line 80
Create .seo/log.md with a one-line header: # SEO decision log if it does not exist.
- Distinctive: line 85
Never silently rewrite. Read the existing file, compare section by section against fresh scan findings and the user's answers, and propose …
- Distinctive: line 94
Leave a section empty to finish faster.
≈ “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.
Files
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:
- Product: one-liner, category, what the product must NEVER be said to do.
- Audience: who exactly, stage, what they already know, who is OUT of scope.
- Voice: tone reference ("write like..."), formal or informal address, banned words and patterns beyond the em dash default.
- Conversion: money page, primary CTA, conversion event, email infrastructure.
- Market & Language: content language, target country (drives keyword data).
- Keyword Strategy: seed keywords (offer 10 candidates from the scan), main competitors, head terms to avoid, the 1-3 money queries.
- Mix & cadence: confirm defaults (70/15/15, 3 per week, batch cap 10) or adjust.
- Publish mode:
pr(default, recommended),commit(full autopilot), orfiles-only. - 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 addcommand, or the copy-pasteexamples/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.mdis not present in the project (common when the skills were installed via the skills CLI), fetch the reference copy fromhttps://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. ## Statedefaults: backlog.seo/backlog.json, decision log.seo/log.md.
Step 4: Initialize state
- Create
.seo/backlog.jsoncontaining[]if it does not exist. - Create
.seo/log.mdwith a one-line header:# SEO decision logif 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.
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
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.

