/seo-auditor

name: seo-auditor
description: |
  Scan and optimize documentation files for SEO. Audits README.md files and docs/ pages for
  meta tags, headings, keywords, readability, duplicate content, and broken links. Applies
  fixes, updates sitemap.xml, and generates a report. Usage: /seo-auditor [path]
argument-hint: "[path]"

/seo-auditor

Systematically scan, audit, and optimize documentation files for SEO. Targets README.md files and docs/ pages — fixes issues in place, preserves rankings on high-performing pages, and generates a final report.

Usage

/seo-auditor                    # Audit all docs/ and root README.md
/seo-auditor docs/skills/       # Audit a specific docs subdirectory
/seo-auditor --report-only      # Scan without making changes

What It Does

Execute all 7 phases sequentially. Auto-fix non-destructive issues. Preserve existing high-ranking content. Report everything at the end.

---

Phase 1: Discovery & Baseline

1a. Identify target files

Scan for documentation files that need SEO audit:

# Find all markdown files in docs/ and root README files
find docs/ -name '*.md' -type f | sort
find . -maxdepth 2 -name 'README.md' -not -path './.codex/*' -not -path './.gemini/*' | sort

Classify each file:

• **New/recently modified** — files changed in the last 2 commits (check via `git log`)
• **Index pages** — `index.md` files (high authority, handle with care)
• **Skill pages** — `docs/skills/**/*.md` (generated by `generate-docs.py`)
• **Static pages** — `docs/index.md`, `docs/getting-started.md`, `docs/integrations.md`, etc.
• **README files** — root and domain-level README.md

1b. Capture baseline

For each target file, extract current SEO state:

• `title:` frontmatter field → becomes `<title>` tag
• `description:` frontmatter field → becomes `<meta name="description">`
• First `# H1` heading
• All `## H2` and `### H3` subheadings
• Word count
• Internal link count
• External link count

Store baseline in memory for the report.

---

Phase 2: Meta Tag Audit

For every file with YAML frontmatter, check and fix:

Title Tag (`title:`)

**Rules:**

• Must exist and be non-empty
• Length: 50-60 characters ideal (Google truncates at ~60)
• Must contain a primary keyword
• Must NOT duplicate another page's title
• For skill pages: should follow the pattern `{Skill Name} — {Differentiator} - {site_name}`
• site_name from `mkdocs.yml` is appended automatically — don't duplicate it in the title

**Auto-fix:** If title is generic (e.g., just the skill name), enrich it with domain context using the DOMAIN_SEO_SUFFIX pattern from `scripts/generate-docs.py`.

Meta Description (`description:`)

**Rules:**

• Must exist and be non-empty
• Length: 120-160 characters (Google truncates at ~160)
• Must contain the primary keyword naturally
• Must be unique across all pages — no two pages share the same description
• Should include a call-to-action or value proposition
• Must NOT start with "This page..." or "This document..."

**Auto-fix:** If description is missing or generic, generate one from the SKILL.md frontmatter description (if available) or from the first paragraph of content. Use the `extract_description_from_frontmatter()` function from `generate-docs.py` as reference.

Validation Script

Run on each file that has HTML output in `site/`:

python3 marketing-skill/skills/seo-audit/scripts/seo_checker.py --file site/{path}/index.html

Parse the score. Flag any page scoring below 60.

---

Phase 3: Content Quality & Readability

For each target file, analyze and improve:

Heading Structure

**Rules:**

• Exactly one `# H1` per page
• H2s follow H1, H3s follow H2 — no skipping levels
• Headings should contain keywords naturally (not stuffed)
• No duplicate headings on the same page

**Auto-fix:** If heading levels skip (H1 → H3), adjust to proper hierarchy.

Readability

Run the content scorer on each file:

python3 marketing-skill/skills/content-production/scripts/content_scorer.py {file_path}

Check scores for:

• **Readability** — aim for score ≥ 70
• **Structure** — aim for score ≥ 60
• **Engagement** — aim for score ≥ 50

Content Quality Rules

• **Paragraphs:** No single paragraph longer than 5 sentences
• **Sentences:** Average sentence length 15-20 words
• **Passive voice:** Less than 15% of sentences
• **Transition words:** At least 30% of sentences use transitions
• **Bullet lists:** Use lists for 3+ items instead of comma-separated inline lists

AI Content Detection

Run the humanizer scorer on non-generated content (README.md files, static pages):

python3 marketing-skill/skills/content-humanizer/scripts/humanizer_scorer.py {file_path}

Flag pages scoring below 50 (too AI-sounding). For these pages, apply voice techniques from `marketing-skill/skills/content-humanizer/references/voice-techniques.md`:

• Replace AI clichés ("delve into", "leverage", "it's important to note")
• Vary sentence length
• Add specific examples instead of generic statements
• Use active voice

**Important:** Only modify content that was recently created or updated. Do NOT rewrite pages that are ranking well — preserve their content.

---

Phase 4: Keyword Optimization

4a. Identify target keywords per page

Based on the page's purpose and domain:

| Page Type | Primary Keywords | Secondary Keywords | |-----------|-----------------|-------------------| | Homepage (docs/index.md) | "Claude Code Skills", "agent plugins" | "Codex skills", "Gemini CLI", "OpenClaw" | | Skill pages | Skill name + "Claude Code" | "agent skill", "Codex plugin", domain terms | | Agent pages | Agent name + "AI coding agent" | "Claude Code", "orchestrator" | | Command pages | Command name + "slash command" | "Claude Code", "AI coding" | | Getting started | "install Claude Code skills" | platform names | | Domain index | Domain + "skills" + "plugins" | "Claude Code", platform names |

4b. Keyword placement