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 checks

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.

5b. Duplicate content detection

Compare meta descriptions across all pages:

grep -rh '^description:' docs/**/*.md | sort | uniq -d

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.

# 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

mkdocs build

This regenerates site/sitemap.xml automatically (MkDocs Material generates it during build).

6b. Verify sitemap

Check the generated sitemap:

python3 marketing-skill/skills/site-architecture/scripts/sitemap_analyzer.py site/sitemap.xml

Verify:

All documentation pages appear in the sitemap
No broken/404 URLs
URL count matches expected page count
Depth distribution is reasonable (no pages deeper than 4 levels)

6c. Check for sitemap issues

Missing pages: Pages in mkdocs.yml nav that don't appear in sitemap
Extra pages: Pages in sitemap that aren't in nav (orphans)
Duplicate URLs: Same page accessible via multiple URLs

Phase 7: Report

Generate a concise report for the user:

╔══════════════════════════════════════════════════════════════╗
║  SEO AUDITOR REPORT                                         ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  Pages scanned:        {n}                                   ║
║  Issues found:         {n}                                   ║
║  Auto-fixed:           {n}                                   ║
║  Manual review needed: {n}                                   ║
║                                                              ║
║  META TAGS                                                   ║
║    Titles optimized:     {n}                                 ║
║    Descriptions fixed:   {n}                                 ║
║    Duplicate titles:     {n} → {n} (fixed)                   ║
║    Duplicate descs:      {n} → {n} (fixed)                   ║
║                                                              ║
║  CONTENT                                                     ║
║    Readability improved: {n} pages                           ║
║    Heading fixes:        {n}                                 ║
║    AI score improved:    {n} pages                           ║
║                                                              ║
║  KEYWORDS                                                    ║
║    Pages missing primary keyword in title: {n}               ║
║    Pages missing keyword in description:   {n}               ║
║    Pages with keyword stuffing:            {n}               ║
║                                                              ║
║  LINKS                                                       ║
║    Broken links found:   {n} → {n} (fixed)                   ║
║    Orphan pages:         {n} → {n} (added to nav)            ║
║    Duplicate content:    {n} → {n} (deduplicated)            ║
║                                                              ║
║  SITEMAP                                                     ║
║    Total URLs:           {n}                                 ║
║    Sitemap regenerated:  ✅                                  ║
║                                                              ║
║  PRESERVED (no changes — ranking well)                       ║
║    {list of pages left untouched}                            ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

Pages to preserve (do NOT modify)

These pages rank well for their target keywords. Only fix critical issues (broken links, missing meta). Do NOT rewrite content:

docs/index.md — homepage, ranks for "Claude Code Skills"
docs/getting-started.md — installation guide
docs/integrations.md — multi-tool support
Any page the user explicitly marks as "preserve"

Skill References

Tool	Path	Use
SEO Checker	`marketing-skill/skills/seo-audit/scripts/seo_checker.py`	Score HTML pages 0-100
Content Scorer	`marketing-skill/skills/content-production/scripts/content_scorer.py`	Score content readability/structure/engagement
Humanizer Scorer	`marketing-skill/skills/content-humanizer/scripts/humanizer_scorer.py`	Detect AI-sounding content
Headline Scorer	`marketing-skill/skills/copywriting/scripts/headline_scorer.py`	Score title quality
SEO Optimizer	`marketing-skill/skills/content-production/scripts/seo_optimizer.py`	Optimize content for target keyword
Sitemap Analyzer	`marketing-skill/skills/site-architecture/scripts/sitemap_analyzer.py`	Analyze sitemap structure
Schema Validator	`marketing-skill/skills/schema-markup/scripts/schema_validator.py`	Validate structured data
Topic Cluster Mapper	`marketing-skill/skills/content-strategy/scripts/topic_cluster_mapper.py`	Group pages into content clusters

Reference Docs

Reference	Path	Use
SEO Audit Framework	`marketing-skill/skills/seo-audit/references/seo-audit-reference.md`	Priority order for SEO fixes
AI Search Optimization	`marketing-skill/skills/aeo/references/extractable_content_patterns.md`	Make content citable by AI
Content Optimization	`marketing-skill/skills/content-production/references/optimization-checklist.md`	Pre-publish checklist
URL Design Guide	`marketing-skill/skills/site-architecture/references/url-design-guide.md`	URL structure best practices
Internal Linking	`marketing-skill/skills/site-architecture/references/internal-linking-playbook.md`	Internal linking strategy
AI Writing Detection	`marketing-skill/skills/content-humanizer/references/ai-tells-checklist.md`	AI cliché removal

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

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..."

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 checks

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.

5b. Duplicate content detection

Compare meta descriptions across all pages:

grep -rh '^description:' docs/**/*.md | sort | uniq -d

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.

# 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

mkdocs build

This regenerates site/sitemap.xml automatically (MkDocs Material generates it during build).

6b. Verify sitemap

Check the generated sitemap:

python3 marketing-skill/skills/site-architecture/scripts/sitemap_analyzer.py site/sitemap.xml

Verify:

All documentation pages appear in the sitemap
No broken/404 URLs
URL count matches expected page count
Depth distribution is reasonable (no pages deeper than 4 levels)

6c. Check for sitemap issues

Missing pages: Pages in mkdocs.yml nav that don't appear in sitemap
Extra pages: Pages in sitemap that aren't in nav (orphans)
Duplicate URLs: Same page accessible via multiple URLs

Phase 7: Report

Generate a concise report for the user:

╔══════════════════════════════════════════════════════════════╗
║  SEO AUDITOR REPORT                                         ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  Pages scanned:        {n}                                   ║
║  Issues found:         {n}                                   ║
║  Auto-fixed:           {n}                                   ║
║  Manual review needed: {n}                                   ║
║                                                              ║
║  META TAGS                                                   ║
║    Titles optimized:     {n}                                 ║
║    Descriptions fixed:   {n}                                 ║
║    Duplicate titles:     {n} → {n} (fixed)                   ║
║    Duplicate descs:      {n} → {n} (fixed)                   ║
║                                                              ║
║  CONTENT                                                     ║
║    Readability improved: {n} pages                           ║
║    Heading fixes:        {n}                                 ║
║    AI score improved:    {n} pages                           ║
║                                                              ║
║  KEYWORDS                                                    ║
║    Pages missing primary keyword in title: {n}               ║
║    Pages missing keyword in description:   {n}               ║
║    Pages with keyword stuffing:            {n}               ║
║                                                              ║
║  LINKS                                                       ║
║    Broken links found:   {n} → {n} (fixed)                   ║
║    Orphan pages:         {n} → {n} (added to nav)            ║
║    Duplicate content:    {n} → {n} (deduplicated)            ║
║                                                              ║
║  SITEMAP                                                     ║
║    Total URLs:           {n}                                 ║
║    Sitemap regenerated:  ✅                                  ║
║                                                              ║
║  PRESERVED (no changes — ranking well)                       ║
║    {list of pages left untouched}                            ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

Pages to preserve (do NOT modify)

These pages rank well for their target keywords. Only fix critical issues (broken links, missing meta). Do NOT rewrite content:

docs/index.md — homepage, ranks for "Claude Code Skills"
docs/getting-started.md — installation guide
docs/integrations.md — multi-tool support
Any page the user explicitly marks as "preserve"

Skill References

Tool	Path	Use
SEO Checker	`marketing-skill/skills/seo-audit/scripts/seo_checker.py`	Score HTML pages 0-100
Content Scorer	`marketing-skill/skills/content-production/scripts/content_scorer.py`	Score content readability/structure/engagement
Humanizer Scorer	`marketing-skill/skills/content-humanizer/scripts/humanizer_scorer.py`	Detect AI-sounding content
Headline Scorer	`marketing-skill/skills/copywriting/scripts/headline_scorer.py`	Score title quality
SEO Optimizer	`marketing-skill/skills/content-production/scripts/seo_optimizer.py`	Optimize content for target keyword
Sitemap Analyzer	`marketing-skill/skills/site-architecture/scripts/sitemap_analyzer.py`	Analyze sitemap structure
Schema Validator	`marketing-skill/skills/schema-markup/scripts/schema_validator.py`	Validate structured data
Topic Cluster Mapper	`marketing-skill/skills/content-strategy/scripts/topic_cluster_mapper.py`	Group pages into content clusters

Reference Docs

Reference	Path	Use
SEO Audit Framework	`marketing-skill/skills/seo-audit/references/seo-audit-reference.md`	Priority order for SEO fixes
AI Search Optimization	`marketing-skill/skills/aeo/references/extractable_content_patterns.md`	Make content citable by AI
Content Optimization	`marketing-skill/skills/content-production/references/optimization-checklist.md`	Pre-publish checklist
URL Design Guide	`marketing-skill/skills/site-architecture/references/url-design-guide.md`	URL structure best practices
Internal Linking	`marketing-skill/skills/site-architecture/references/internal-linking-playbook.md`	Internal linking strategy
AI Writing Detection	`marketing-skill/skills/content-humanizer/references/ai-tells-checklist.md`	AI cliché removal

seo-auditor

让 AI 帮你安装

/seo-auditor

Usage

What It Does

Phase 1: Discovery & Baseline

1a. Identify target files

1b. Capture baseline

Phase 2: Meta Tag Audit

Title Tag (title:)

Meta Description (description:)

Validation Script

Phase 3: Content Quality & Readability

Heading Structure

Readability

Content Quality Rules

AI Content Detection

Phase 4: Keyword Optimization

4a. Identify target keywords per page

4b. Keyword placement checks

4c. Keyword density

Phase 5: Link Audit

5a. Internal links

5b. Duplicate content detection

5c. Orphan page detection

Phase 6: Sitemap & Build

6a. Rebuild the site

6b. Verify sitemap

6c. Check for sitemap issues

Phase 7: Report

Pages to preserve (do NOT modify)

Skill References

Reference Docs

链接

创作者

/seo-auditor

Usage

What It Does

Phase 1: Discovery & Baseline

1a. Identify target files

1b. Capture baseline

Phase 2: Meta Tag Audit

Title Tag (title:)

Meta Description (description:)

Validation Script

Phase 3: Content Quality & Readability

Heading Structure

Readability

Content Quality Rules

AI Content Detection

Phase 4: Keyword Optimization

4a. Identify target keywords per page

4b. Keyword placement checks

4c. Keyword density

Phase 5: Link Audit

5a. Internal links

5b. Duplicate content detection

5c. Orphan page detection

Phase 6: Sitemap & Build

6a. Rebuild the site

6b. Verify sitemap

6c. Check for sitemap issues

Phase 7: Report

Pages to preserve (do NOT modify)

Skill References

Reference Docs

Title Tag (`title:`)

Meta Description (`description:`)

Title Tag (`title:`)

Meta Description (`description:`)