seo-toolkit-template
CLAUDE.md1 starsChanged 6 months agoApache-2.0View on GitHub
This is the SEO toolkit repo. It is not a website — it is a Claude Code workspace that operates on multiple existing websites the user manages. The toolkit applies a consistent SEO workflow across every managed site, regardless of platform (WordPress, Lovable, Webflow, Next.js, Shopify, custom, etc.). The websites themselves live in their own repos / hosting — this toolkit never touches their codebases unless explicitly told to push changes. The toolkit does not deploy websites. For each site,…
- Reads credentials
- Installs packages
In this repository20 other files it gives its agents.
- alternativeSkill
- auditSkill
- blogSkill
- broken-backlinksSkill
- case-studySkill
- clusterSkill
- comparisonSkill
- competitor-backlinksSkill
- glossarySkill
- haroSkill
- integrationsSkill
- lovable-deploySkill
- pricingSkill
- programmatic-batchSkill
- refreshSkill
- semrush-baselineSkill
- serp-featuresSkill
- serviceSkill
- triageSkill
- wireframeSkill
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
28 rules. About 0 are common, 19 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈19
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 65
When writing any blog post, service page, or customer-facing copy, the skill resolves voice files in this order (BOTH apply, the per-site …
- Distinctive: line 85
Open with the answer: Add context after, not before.
- Very specific: line 94
Before any draft ships, run the universal anti-AI checklist from references/voice.md → "Universal anti-AI checklist." Delete anything that …
- Very specific: line 149
Every page on a multilingual site includes a <link rel="alternate"> cluster in the head:
- Distinctive: line 171
Every page on every managed site targets exactly one search intent (informational OR commercial — never both, never two of either).
- Very specific: line 175
Before adding any keyword to a cluster, run the SERP-comparison test (SEO_GUIDE.md Section 2.4):
- Distinctive: line 177
Search both keywords incognito in the target region.
- Very specific: line 189
Every new page goes through /wireframe first.
- Very specific: line 203
Read on-page-seo.md at the toolkit root.
- Distinctive: line 228
Before any page ships, the skill runs both validators:
- Distinctive: line 293
Before any action, read in this order:
- Distinctive: line 307
Write the plan to a temporary draft (or state inline if short).
- Distinctive: line 309
Wait for approval before generating final output.
- Distinctive: line 313
Before creating any new file or content:
- Very specific: line 314
Check if it already exists (search _drafts/, the live site URL, GSC, used-keywords.md).
- Distinctive: line 315
If it exists, edit / refresh it.
- Distinctive: line 316
If it doesn't exist, create it.
- Distinctive: line 320
Before any draft is marked complete:
- Distinctive: line 328
If any check fails, the skill refuses to ship and reports what needs fixing.
- Very specific: line 387
When you change references/, on-page-seo.md, SEO_GUIDE.md, CLAUDE.md, or any SKILL.md:
- Distinctive: line 389
Run a smoke test on a known-good site (regenerate one short piece of content).
- Distinctive: line 390
Don't claim "done" without the smoke test.
- Very specific: line 453
After any edit to a skill's SKILL.md:
- Very specific: line 465
After creating a new sites/[name]/:
- Distinctive: line 474
Never claim a change is done if:
- Distinctive: line 484
Only build what's requested.
- Distinctive: line 493
Refactoring the toolkit itself without explicit request: Do exactly what's asked.
- Distinctive: line 497
Ask. The toolkit is opinionated about *how* SEO work happens, not about *what* gets done.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md 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
Project Overview
This is the SEO toolkit repo. It is not a website — it is a Claude Code workspace that operates on multiple existing websites the user manages.
The toolkit applies a consistent SEO workflow across every managed site, regardless of platform (WordPress, Lovable, Webflow, Next.js, Shopify, custom, etc.). The websites themselves live in their own repos / hosting — this toolkit never touches their codebases unless explicitly told to push changes.
What the toolkit does
| Skill | Purpose |
/blog | Generate a long-form, SEO-optimized, voice-matched blog post for a chosen site |
/service | Generate a service page (footprint-aware: single-location / multi-location / service-area / national-online) |
/refresh | Upgrade an existing blog post — re-do SERP analysis, refresh stats, fix on-page gaps, update internal links |
/audit | Run a technical SEO audit on a chosen site, log results to its site-info.md |
/triage | Score every site in sites/ by SEO opportunity, recommend top 3 to focus on |
/wireframe | Produce a wireframe doc for a new page before content generation (mandatory pre-content step; invoked by /blog and /service) |
/cluster | Plan a topic cluster (pillar + N cluster pages + internal-link graph + wireframes in one pass) |
/programmatic-batch | Generate N service pages from a matrix CSV with anti-doorway-page enforcement |
/comparison | Head-to-head "[X] vs [Y]" page generator |
/alternative | "Alternatives to [X]" listicle generator |
/case-study | Real-story client outcome page (pulls from stories.md, refuses if no eligible story) |
/pricing | Transparent pricing page (refuses to invent if pricing data missing from stats.md) |
/integrations | "[Site] + [Tool]" integration page |
/glossary | Glossary entry or full index with DefinedTermSet schema |
/lovable-deploy | Drive Lovable IDE round-trip via Chrome DevTools MCP |
/serp-features | SERP feature gap analyzer (featured snippet, PAA, image pack, video, knowledge panel, AIO, local pack, sitelinks) |
/haro | Daily journalist-query monitor (source-pluggable) |
/broken-backlinks | Monthly broken-backlink reclamation finder |
/competitor-backlinks | Monthly competitor backlink reverse-engineering |
/semrush-baseline | Quarterly SEMrush snapshot |
How it's organized
- Toolkit root — shared assets used across all sites:
references/→ default voice (universal procedural rules)on-page-seo.md→ 80+ signal checklist.claude/skills/→ the 20+ skills aboveSEO_GUIDE.md→ the canonical playbookCLAUDE.md→ this file
sites/[site-name]/— per-site folders, one per managed website:site-info.md→ URL, platform, footprint, NAP, GSC/GA4 setup, voice override flag, etc.keywords.csv→ informational keywords (for/blog)service-keywords.csv→ commercial keywords (for/service)used-keywords.md→ tracker preventing keyword cannibalizationnotes.md→ conversion winners, audit history, anything site-specificreferences/(optional) → per-site voice override_drafts/[slug]/→ working drafts before publish (gitignored)
How publishing works
The toolkit does not deploy websites. For each site, site-info.md records the publishing method:
repo-commit→ Claude commits markdown to the site's GitHub repo, deploys via Vercel/Netlify.cms-paste→ Claude generates clipboard-ready output; user pastes into WordPress/Webflow/Shopify.lovable-prompt→ Claude generates a Lovable-ready prompt + content; user pastes into Lovable.headless-api→ Claude pushes via configured API (Sanity, Contentful, Strapi).
What this CLAUDE.md controls
This file sets the rules every skill follows: voice handling, on-page SEO, technical SEO, content cadence, testing, scope. The skills themselves (SKILL.md files in .claude/skills/) reference these rules rather than restating them.
Voice — read before writing any content
When writing any blog post, service page, or customer-facing copy, the skill resolves voice files in this order (BOTH apply, the per-site file CANNOT relax universal rules):
references/[file].md— universal procedural rules that apply to every site (banned words, anti-AI checks, structural requirements). NO persona content here.sites/[site-name]/references/[file].md— the actual persona/numbers/stories/opinions for that site. REQUIRED for content skills to run.
The per-site file can ADD restrictions (more banned words, stricter humor, etc.) but cannot REMOVE universal rules.
The five reference files
| File | Root has | Per-site has |
voice.md | Universal banned words, anti-AI checklist, structural rules | The persona, sentence rhythm, sample writing, brand-specific bans |
humour.md | Universal hard bans (puns, sarcasm at reader, etc.), zero-humor contexts | The site's actual humor style or "none" |
stats.md | Procedural rules (never round, never invent), required structure | Real numbers — pricing, response times, customer counts |
stories.md | Procedural rules (one per post max, anonymize unless consented) | 5–10 real anecdotes from this business |
opinions.md | Procedural rules (one per post max, must be backed by stat) | The site's actual hot takes |
Universal voice rules (always apply, regardless of site)
- Banned words/phrases: "unlock", "leverage", "seamless", "world-class", "cutting-edge", "revolutionary", "in today's fast-paced world", "delve", "navigate the complexities of", exclamation marks, emojis. Per-site can ADD bans, never remove.
- Open with the answer. Add context after, not before.
- Real numbers only — pulled from the site's
stats.md. Never round. If a needed stat isn't there, ask before fabricating. - One story per post max — pulled from the site's
stories.md. Never invent. - One strong opinion per post max — pulled from the site's
opinions.md. Must be backed by a number fromstats.md. - Tell readers when NOT to hire / use the product. Biggest single tell that this isn't AI slop.
- Banned generic phrases for endings: "In conclusion", "At the end of the day", "Hope this helps."
Pre-ship anti-AI check
Before any draft ships, run the universal anti-AI checklist from references/voice.md → "Universal anti-AI checklist." Delete anything that matches. The /blog and /service skills run this check automatically and refuse to ship a draft that fails.
When reference files are missing
- Root
references/(universal rules): required — every file must exist. Without these, the skill has no anti-AI checklist to enforce. - Per-site
references/voice.mdandstats.md: required for any site that runs/blog,/service, or/refresh. Skills refuse to run on a site missing these. - Per-site
references/stories.md,opinions.md,humour.md: optional. If missing, the skill ships content without stories/opinions/humor (more generic, but functional).
Multilingual sites — fan-out everything when more than one language is declared
Some sites serve content in multiple languages. When a site is multilingual, every page-generating skill produces a draft per language and every audit verifies hreflang reciprocity across them. A "page" on a multilingual site is the set of language versions, not any single URL.
How a site declares multilingual status
The site's site-info.md Languages section is the source of truth. Required fields when Multilingual: true:
## Languages
- **Multilingual:** true
- **Primary language:** en
- **Declared languages:**
| Code | Primary | URL pattern | Hreflang code | Voice file |
|------|---------|-------------------------|---------------|-------------------------|
| en | yes | `/[slug]` | en | `references/voice.en.md`|
| es | no | `/es/[slug]` | es | `references/voice.es.md`|
- **x-default language:** en
- **Hreflang strategy:** path-prefix | subdomain | country-tld
- **Translation philosophy:** native rewrite | machine translationA monolingual site uses Multilingual: false and the rest of the rules in this section don't apply.
Universal multilingual rules
- Native rewrite per language, not translation. Each language's draft is written using that language's voice file (
voice.[lang].md). - All canonical pages mirror across all languages by default. Opt-out is per-page via explicit
languages: [en]frontmatter, and the skill must confirm the opt-out before generating only one version. - URL pattern is read from
site-info.md, not assumed. Path-prefix (/es/...), subdomain (es.example.com), and country TLD (example.es) are all supported. - Hreflang link cluster on every page — self-referencing, all sibling languages, x-default, reciprocal across all pages.
- Schema
inLanguagematches<html lang>and the served language. - Visible navigation per language. Headers/footers/dropdowns in each language must list every page that exists in that language.
Per-language voice file resolution
- Root
references/voice.md— universal procedural rules. Language-agnostic. - Per-site
references/voice.[lang].md— the persona / sample paragraphs / banned words for that site in that language. REQUIRED for every declared language. - Same pattern for
humour.[lang].md,stories.[lang].md,opinions.[lang].md. stats.mdis shared across languages — numbers are universal.
If a multilingual site is missing voice.[lang].md for any declared language, every page-generating skill refuses to run.
Hreflang link cluster
Every page on a multilingual site includes a <link rel="alternate"> cluster in the head:
<link rel="alternate" hreflang="en" href="https://example.com/services/x" />
<link rel="alternate" hreflang="es" href="https://example.com/es/services/x" />
<link rel="alternate" hreflang="x-default" href="https://example.com/services/x" />Required:
- Self-referencing — the page links to itself with its own language code.
- All sibling languages — every other declared language gets a link.
- x-default — points to the primary language version. Always present.
- Reciprocal — if EN links to ES, ES must link back to EN. Asymmetric hreflang is invalid.
Keyword research — applies to every keyword, every cluster, every commercial site
The full methodology lives in SEO_GUIDE.md Section 2. The three rules every skill enforces:
Rule: one page = one search intent
Every page on every managed site targets exactly one search intent (informational OR commercial — never both, never two of either). Two keywords sit on the same page only when their SERPs overlap.
Rule: cluster validity is verified by SERP comparison
Before adding any keyword to a cluster, run the SERP-comparison test (SEO_GUIDE.md Section 2.4):
- Search both keywords incognito in the target region.
- Count shared URLs in the top 10.
- ≥ 4 shared → cluster (same page). 2–3 shared → borderline. ≤ 1 shared → split (different pages).
Wording similarity doesn't determine grouping; SERPs do.
Rule: service-business sites with > 3 commercial keywords require an architecture.md
Any site with service-business: true AND more than 3 rows in service-keywords.csv needs sites/[name]/architecture.md (SEO_GUIDE.md Section 2.6). Template at templates/architecture.md.
Rule: wireframe before content
Every new page goes through /wireframe first. Skills enforce this:
/blogStep 4.5 — generate wireframe, get user approval, then content/serviceStep 5.5 — same
The wireframe lives at sites/[site]/_drafts/[slug]/wireframe.md.
Rule: catalog footprint sites use hierarchical URLs
Sites declared with catalog footprint follow /[category]/[subcategory]/[product-or-page]/. Flat URL patterns (/services/[name]) are reserved for non-catalog footprints.
On-page SEO — applies to every page generated by every skill
Read on-page-seo.md at the toolkit root. Every item applicable to the page type must be satisfied.
Tier 1 (non-negotiable on every page)
These 16 items must pass before any draft ships. Skills validate Tier 1 automatically:
- Title tag — 50–60 chars, primary keyword near the start, unique per page
- Meta description — 150–160 chars, primary keyword + benefit + soft CTA
- One H1 containing the primary keyword
- Primary keyword in first 100 words, reads naturally
- URL slug — short, lowercase, hyphenated, contains primary keyword
- Canonical URL — self-referencing
- Open Graph + Twitter Card meta
- Image alt text + descriptive hyphenated filenames
- 3–5 internal links with descriptive anchor text
- 2–3 external links to authoritative sources,
rel="noopener" - Schema (JSON-LD) per page type
- FAQ section with
FAQPageschema (4–8 Q+A on every blog post + service page) - Author byline + bio with
Personschema (blog posts, IFF site policy allows person-author) - Mobile-friendly — responsive, 16px+ body font, 48×48px touch targets
- Loads fast — Lighthouse mobile ≥ 90 performance, LCP < 2.5s, CLS < 0.1, INP < 200ms
- Semantic HTML5
Schema validation (mandatory)
Before any page ships, the skill runs both validators:
- Google Rich Results Test (search.google.com/test/rich-results)
- Schema.org Validator (validator.schema.org)
Schema content (FAQ Q+A, breadcrumb labels) must match the visible page exactly.
Technical SEO — applies to every site
The 8 non-negotiables (every site)
- Sitemap at
/sitemap.xml— submitted to GSC robots.txtat/robots.txt— allows crawlers, references the sitemap- Canonical URL on every page — self-referencing
- Open Graph images (1200×630) — present and resolve
- Image width/height attributes specified — prevents CLS
- Semantic HTML5
- Mobile viewport meta
- HTTPS everywhere — no mixed content warnings
Performance targets (Core Web Vitals — mobile-first)
Core Web Vitals (hard targets — real ranking signals from field data):
| Metric | Target |
| LCP (Largest Contentful Paint) | < 2.5s |
| INP (Interaction to Next Paint) | < 200ms |
| CLS (Cumulative Layout Shift) | < 0.1 |
Lighthouse mobile (lab tests):
- Stretch goal: 100 across all four — Performance, SEO, Accessibility, Best Practices.
- Realistic floors: see
SEO_GUIDE.mdSection 6.2.
Design — for content the toolkit generates
The toolkit itself has no UI. But the content it generates renders on each site.
Universal rules
- No emoji icons in body copy, headings, CTAs, or UI elements. Emoji are an AI-content tell. Use real icon sets (Lucide, Heroicons, Phosphor) or no icons at all.
- No generic gradients (purple-to-pink, blue-to-cyan). If gradients are used, they must come from the site's documented brand palette.
- No inline styles in generated HTML.
- Subtle animations only — fade-ins, gentle reveals. Meets
prefers-reduced-motion. - Mobile-first sizing — body 16px+, touch targets 48×48px+.
- Dark-mode contrast non-negotiable — every interactive element passes WCAG AA contrast (4.5:1) in BOTH light and dark mode.
Per-site brand override
Each site has its own brand. Record visual rules in sites/[site-name]/site-info.md under "Brand assets location":
- Accent color (single primary brand color, hex)
- Typography (heading font + body font)
- Logo location (URL or path)
- Image style (photographic / illustrated / hand-drawn / mixed)
- Existing component library
Development Rules
Rule 1: Always read first
Before any action, read in this order:
CLAUDE.md(this file)SEO_GUIDE.mdon-page-seo.mdsites/[site-name]/site-info.md- Resolved
references/— root files + per-site overrides if present sites/[site-name]/keywords.csv+service-keywords.csv+used-keywords.mdsites/[site-name]/architecture.md— when generating commercial pages on a service-business sitesites/[site-name]/notes.md
Rule 2: Define before you build
For any non-trivial action:
- Write the plan to a temporary draft (or state inline if short).
- Show the plan to the user.
- Wait for approval before generating final output.
Rule 3: Look before you create
Before creating any new file or content:
- Check if it already exists (search
_drafts/, the live site URL, GSC,used-keywords.md). - If it exists, edit / refresh it. Don't duplicate.
- If it doesn't exist, create it.
Rule 4: Validate before you ship
Before any draft is marked complete:
- ✅ Tier 1 on-page check — all 16 items pass.
- ✅ Schema validation — both Google Rich Results Test and Schema.org Validator pass.
- ✅ Voice anti-AI check — re-read resolved
voice.mdand delete matches. - ✅ Cadence check — verify the publish wouldn't exceed
site-info.md→ Content cadence. - ✅ Cannibalization check — primary keyword not already in
used-keywords.md. - ✅ Lighthouse spot-check — for
repo-commitsites, run mobile Lighthouse on the staged URL.
If any check fails, the skill refuses to ship and reports what needs fixing.
Core Rule: Do exactly what is asked
Nothing more, nothing less. If anything is unclear, ask before starting.
Tech Stack
Toolkit itself
| Layer | What it uses |
| Format | Markdown for guides, references, site-info, notes; CSV for keyword lists; YAML/Markdown frontmatter inside SKILL.md files |
| Scripts | TypeScript (.mjs) in scripts/. Run via node or tsx. |
| APIs (optional) | Pexels, Unsplash, PageSpeed Insights, GSC OAuth, SEMrush, GBP, GA4. Keys in .env. |
| Runtime | Local Mac/Linux/Windows (Claude Code). |
| Version control | Private or public GitHub repo. |
Per-site stacks
Each managed site runs on its own platform. The toolkit adapts based on sites/[site-name]/site-info.md:
- Platform (Lovable / WordPress / Webflow / Next.js / Shopify / Squarespace / Wix / Framer / custom)
- Rendering (SSG / SSR / CSR / Hybrid)
- Hosting (Vercel / Netlify / SiteGround / Cloudflare / platform-native)
- Repo (GitHub URL or "no repo")
- Publishing method (
repo-commit/cms-paste/lovable-prompt/headless-api)
Using the Toolkit
The toolkit runs entirely inside Claude Code. There is no dev server, no build step, no deploy.
First-time setup
- Clone or download the toolkit.
- Install script dependencies (one-time):
npm install - Configure
.envat toolkit root from.env.example. Fill in API keys for the integrations you want. - Open in Claude Code.
Daily workflow
Invoke any of the 20+ skills via /skill-name. Each skill asks for any inputs not already in site-info.md.
Adding a new managed site
cp -r templates/new-site sites/[site-name]Then fill in the {TODO} markers in each file, especially site-info.md. Run /audit on the site to record its baseline. See templates/new-site/README.md for the full checklist.
Updating the toolkit itself
When you change references/, on-page-seo.md, SEO_GUIDE.md, CLAUDE.md, or any SKILL.md:
- Edit the file.
- Run a smoke test on a known-good site (regenerate one short piece of content).
- Don't claim "done" without the smoke test.
File Structure
seo-toolkit/ ← top of the workspace
│
├── CLAUDE.md ← this file
├── SEO_GUIDE.md ← canonical playbook
├── WORKFLOWS.md ← cross-site platform patterns
├── on-page-seo.md ← 80+ signal checklist
├── README.md
├── package.json
├── .env ← gitignored
├── .gitignore
│
├── references/ ← default voice — universal rules
│ ├── voice.md
│ ├── humour.md
│ ├── stats.md
│ ├── stories.md
│ └── opinions.md
│
├── .claude/
│ └── skills/ ← 20+ skill definitions
│
├── scripts/ ← helper scripts + cron-fired routines
│
├── templates/
│ ├── new-site/ ← skeleton for adding new sites
│ ├── architecture.md ← transactional SEO architecture template
│ ├── outreach/ ← outreach email templates
│ └── programmatic/ ← matrix-driven batch template
│
└── sites/
└── [site-name]/ ← one folder per managed site (you create these)
├── site-info.md
├── keywords.csv
├── service-keywords.csv
├── used-keywords.md
├── notes.md
├── references/ ← per-site voice override (optional)
└── _drafts/ ← gitignoredOrganization rules
- One file per concern.
- No new top-level folders without asking.
- Shared assets at toolkit root; per-site overrides under
sites/[name]/. _drafts/is gitignored..envis never committed.
Testing
Rule 4 covers ship validation for individual content drafts. This section covers everything else.
Per-skill smoke tests
After any edit to a skill's SKILL.md:
| Skill | Smoke test |
/blog | Generate one short post (~800 words) on a non-priority site |
/service | Generate one service page on a service-business site |
/refresh | Refresh a known-stale post |
/audit | Run on a site with a known issue |
/triage | Run across all sites |
Per-site setup verification
After creating a new sites/[name]/:
- ✅
site-info.mdexists and parses - ✅
keywords.csvandservice-keywords.csvexist - ✅
used-keywords.mdexists - ✅
notes.mdexists - ✅
/auditruns end-to-end without errors
What "done" means
Never claim a change is done if:
- A smoke test failed.
- Schema validators report errors.
- The voice reads as AI on the regenerated sample.
- A required file is missing or malformed.
Scope
Only build what's requested. If anything is unclear, ask before starting.
Toolkit-specific scope boundaries
- Editing external site code. The toolkit reads
site-info.mdand generates content. It does not modify the site's own repo, theme, plugins, CMS, or hosting unless explicitly told to push changes. - Generating content for sites without
site-info.md. The skills refuse to run on a site folder missingsite-info.md. - Modifying live infrastructure (GSC properties, GA4, GBP, DNS, hosting). The toolkit guides the user; the user executes.
- Bulk operations across all sites without approval. Running
/blog20 times across 20 sites in one session requires explicit approval. - Spending money. The toolkit doesn't sign up for paid tools. The user evaluates and pays separately.
- Refactoring the toolkit itself without explicit request. Do exactly what's asked.
When in doubt
Ask. The toolkit is opinionated about how SEO work happens, not about what gets done. The user always picks the priorities.
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.

