seo

--- name: seo-auditor description: | Scans and optimizes 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 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 extractdescriptionfrom_frontmatter() function from generate-docs.py as reference. ### Validation Script Run on each file that has HTML output in site/ : `bash 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: `bash python3 marketing-skill/skills/content-production/scripts/content_scorer.py {file_path} `` Check scores for: - Readability : aim for a score of ≥ 70 - Structure : aim for a score of ≥ 60 - Engagement : aim for a score of ≥ 50 ##