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]
Ships with claude-skills. Installing the plugin gets this command.
⚡ How it fires
How this command gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/seo-auditor
👁️ Context preview
What this command does when you run it.
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]
📊 Stats
Stars23,062
Forks3,139
LanguagePython
LicenseMIT
📦 Ships with claude-skills
</> Command definition
seo-auditor.md
---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
```bash
/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:
```bash
# Find all markdown files in docs/ and root README files
- **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.
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 |
For each page, verify the primary keyword appears in:
- [ ] Title tag (frontmatter `title:`)
- [ ] Meta description (frontmatter `description:`)
- [ ] H1 heading
- [ ] First paragraph (within first 100 words)
- [ ] At least one H2 subheading
- [ ] Image alt text (if images present)
- [ ] URL slug (for new pages only — never change existing URLs)
### 4c. Keyword density
- Primary keyword: 1-2% of total word count
- Secondary keywords: 0.5-1% each
- No keyword stuffing — if density exceeds 3%, reduce it
**Important:** Never change URLs of existing pages. URL changes break incoming links and destroy rankings. Only optimize content and meta tags.
---
## Phase 5: Link Audit
### 5a. Internal links
For each target file, check all markdown links `[text](url)`:
- Verify the target exists (file path resolves)
- Check for broken relative links (`../`, `./`)
- Verify anchor links (`#section-name`) point to existing headings
**Auto-fix:** Use the `rewrite_skill_internal_links()` and `rewrite_relative_links()` functions from `generate-docs.py` as reference. Rewrite broken skill-internal links to GitHub source URLs.
If duplicates found, make each description unique by adding page-specific context.
Compare H1 headings across all pages — no two pages should have the same H1.
### 5c. Orphan page detection
Check if every page in `docs/` is referenced in `mkdocs.yml` nav. Pages not in nav are orphans — they won't appear in navigation and may not be indexed.
```bash
# Find doc pages not in mkdocs nav
find docs -name '*.md' -not -name 'index.md' | while read f; do
slug=$(echo "$f" | sed 's|docs/||')
grep -q "$slug" mkdocs.yml || echo "ORPHAN: $f"
done
```
**Auto-fix:** Add orphan pages to the correct nav section in `mkdocs.yml`.
---
## Phase 6: Sitemap & Build
### 6a. Rebuild the site
```bash
mkdocs build
```
This regenerates `site/sitemap.xml` automatically (MkDocs Material generates it during build).
