feat(commands): add /seo-auditor — 7-phase SEO audit pipeline for documentation

- 7 phases: discovery → meta tags → content quality → keywords → links → sitemap → report - Integrates 8 marketing-skill scripts: seo_checker, content_scorer, humanizer_scorer, headline_scorer, seo_optimizer, sitemap_analyzer, schema_validator, topic_cluster_mapper - References 6 SEO knowledge bases for audit framework, AI search, content optimization, URL design, internal linking, AI detection - Auto-fixes: generic titles, missing descriptions, broken links, orphan pages - Preserves high-ranking pages — only fixes critical issues on those - Registered in both commands/ (distributable) and .claude/commands/ (local) Also: sync all doc counts — 28 plugins, 26 eng-core skills, 21 commands Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-18 10:28:17 +01:00
parent 4709662631
commit 90cef3b3ac
19 changed files with 2303 additions and 26 deletions
--- a/docs/commands/a11y-audit.md
+++ b/docs/commands/a11y-audit.md
@@ -0,0 +1,90 @@
+---
+title: "/a11y-audit — Slash Command for AI Coding Agents"
+description: "Scan a frontend project for WCAG 2.2 accessibility violations and fix them. Usage: /a11y-audit [path]. Slash command for Claude Code, Codex CLI, Gemini CLI."
+---
+
+# /a11y-audit
+
+<div class="page-meta" markdown>
+<span class="meta-badge">:material-console: Slash Command</span>
+<span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/commands/a11y-audit.md">Source</a></span>
+</div>
+
+
+Scan a frontend project for WCAG 2.2 accessibility issues, show fixes, and optionally check color contrast.
+
+## Usage
+
+```bash
+/a11y-audit                     # Scan current project
+/a11y-audit ./src               # Scan specific directory
+/a11y-audit ./src --fix         # Scan and auto-fix what's possible
+```
+
+## What It Does
+
+### Step 1: Scan
+
+Run the a11y scanner on the target directory:
+
+```bash
+python3 {skill_path}/scripts/a11y_scanner.py {path} --json
+```
+
+Parse the JSON output. Group findings by severity (critical → serious → moderate → minor).
+
+Display a summary:
+```
+A11y Audit: ./src
+  Critical: 3 | Serious: 7 | Moderate: 12 | Minor: 5
+  Files scanned: 42 | Files with issues: 15
+```
+
+### Step 2: Fix
+
+For each finding (starting with critical):
+
+1. Read the affected file
+2. Show the violation with context (before)
+3. Apply the fix from `references/framework-a11y-patterns.md`
+4. Show the result (after)
+
+**Auto-fixable issues** (apply without asking):
+- Missing `alt=""` on decorative images
+- Missing `lang` attribute on `<html>`
+- `tabindex` values > 0 → set to 0
+- Missing `type="button"` on non-submit buttons
+- Outline removal without replacement → add `:focus-visible` styles
+
+**Issues requiring user input** (show fix, ask to apply):
+- Missing alt text (need description from user)
+- Missing form labels (need label text)
+- Heading restructuring (may affect layout)
+- ARIA role changes (may affect functionality)
+
+### Step 3: Contrast Check
+
+If CSS files are present, run the contrast checker:
+
+```bash
+python3 {skill_path}/scripts/contrast_checker.py --batch {path}
+```
+
+For each failing color pair, suggest accessible alternatives.
+
+### Step 4: Report
+
+Generate a markdown report at `a11y-report.md`:
+- Executive summary (pass/fail, issue counts)
+- Per-file findings with before/after diffs
+- Remaining manual review items
+- WCAG criteria coverage
+
+## Skill Reference
+
+- `engineering-team/a11y-audit/SKILL.md`
+- `engineering-team/a11y-audit/scripts/a11y_scanner.py`
+- `engineering-team/a11y-audit/scripts/contrast_checker.py`
+- `engineering-team/a11y-audit/references/wcag-quick-ref.md`
+- `engineering-team/a11y-audit/references/aria-patterns.md`
+- `engineering-team/a11y-audit/references/framework-a11y-patterns.md`
--- a/docs/commands/index.md
+++ b/docs/commands/index.md
@@ -1,18 +1,24 @@
 ---
 title: "Slash Commands — AI Coding Agent Commands & Codex Shortcuts"
-description: "19 slash commands for Claude Code, Codex CLI, and Gemini CLI — sprint planning, tech debt analysis, PRDs, OKRs, and more."
+description: "21 slash commands for Claude Code, Codex CLI, and Gemini CLI — sprint planning, tech debt analysis, PRDs, OKRs, and more."
 ---

 <div class="domain-header" markdown>

 # :material-console: Slash Commands

-<p class="domain-count">19 commands for quick access to common operations</p>
+<p class="domain-count">21 commands for quick access to common operations</p>

 </div>

 <div class="grid cards" markdown>

+-   :material-console:{ .lg .middle } **[`/a11y-audit`](a11y-audit.md)**
+
+    ---
+
+    Scan a frontend project for WCAG 2.2 accessibility issues, show fixes, and optionally check color contrast.
+
 -   :material-console:{ .lg .middle } **[`/changelog`](changelog.md)**

    ---
@@ -97,6 +103,12 @@ description: "19 slash commands for Claude Code, Codex CLI, and Gemini CLI — s

    Calculate SaaS financial health metrics from raw business numbers, benchmark against industry standards, and project ...

+-   :material-console:{ .lg .middle } **[`/seo-auditor`](seo-auditor.md)**
+
+    ---
+
+    Systematically scan, audit, and optimize documentation files for SEO. Targets README.md files and docs/ pages — fixes...
+
 -   :material-console:{ .lg .middle } **[`/sprint-health`](sprint-health.md)**

    ---
--- a/docs/commands/seo-auditor.md
+++ b/docs/commands/seo-auditor.md
@@ -0,0 +1,343 @@
+---
+title: "/seo-auditor — Slash Command for AI Coding Agents"
+description: "|. Slash command for Claude Code, Codex CLI, Gemini CLI."
+---
+
+# /seo-auditor
+
+<div class="page-meta" markdown>
+<span class="meta-badge">:material-console: Slash Command</span>
+<span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/commands/seo-auditor.md">Source</a></span>
+</div>
+
+
+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 `extract_description_from_frontmatter()` function from `generate-docs.py` as reference.
+
+### Validation Script
+
+Run on each file that has HTML output in `site/`:
+
+```bash
+python3 marketing-skill/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/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):
+
+```bash
+python3 marketing-skill/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/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:
+
+```bash
+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.
+
+```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).
+
+### 6b. Verify sitemap
+
+Check the generated sitemap:
+
+```bash
+python3 marketing-skill/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/seo-audit/scripts/seo_checker.py` | Score HTML pages 0-100 |
+| Content Scorer | `marketing-skill/content-production/scripts/content_scorer.py` | Score content readability/structure/engagement |
+| Humanizer Scorer | `marketing-skill/content-humanizer/scripts/humanizer_scorer.py` | Detect AI-sounding content |
+| Headline Scorer | `marketing-skill/copywriting/scripts/headline_scorer.py` | Score title quality |
+| SEO Optimizer | `marketing-skill/content-production/scripts/seo_optimizer.py` | Optimize content for target keyword |
+| Sitemap Analyzer | `marketing-skill/site-architecture/scripts/sitemap_analyzer.py` | Analyze sitemap structure |
+| Schema Validator | `marketing-skill/schema-markup/scripts/schema_validator.py` | Validate structured data |
+| Topic Cluster Mapper | `marketing-skill/content-strategy/scripts/topic_cluster_mapper.py` | Group pages into content clusters |
+
+### Reference Docs
+
+| Reference | Path | Use |
+|-----------|------|-----|
+| SEO Audit Framework | `marketing-skill/seo-audit/references/seo-audit-reference.md` | Priority order for SEO fixes |
+| AI Search Optimization | `marketing-skill/ai-seo/references/content-patterns.md` | Make content citable by AI |
+| Content Optimization | `marketing-skill/content-production/references/optimization-checklist.md` | Pre-publish checklist |
+| URL Design Guide | `marketing-skill/site-architecture/references/url-design-guide.md` | URL structure best practices |
+| Internal Linking | `marketing-skill/site-architecture/references/internal-linking-playbook.md` | Internal linking strategy |
+| AI Writing Detection | `marketing-skill/content-humanizer/references/ai-tells-checklist.md` | AI cliché removal |
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -140,7 +140,7 @@ Choose your platform and follow the steps:

 | Bundle | Install Command | Skills |
 |--------|----------------|--------|
-| **Engineering Core** | `/plugin install engineering-skills@claude-code-skills` | 25 |
+| **Engineering Core** | `/plugin install engineering-skills@claude-code-skills` | 26 |
 | **Engineering POWERFUL** | `/plugin install engineering-advanced-skills@claude-code-skills` | 30 |
 | **Product** | `/plugin install product-skills@claude-code-skills` | 14 |
 | **Marketing** | `/plugin install marketing-skills@claude-code-skills` | 43 |
--- a/docs/index.md
+++ b/docs/index.md
@@ -89,7 +89,7 @@ hide:

    [:octicons-arrow-right-24: Getting started](getting-started.md)

-   :material-puzzle-outline:{ .lg .middle } **22 Plugins**
+-   :material-puzzle-outline:{ .lg .middle } **28 Plugins**

    ---

@@ -135,7 +135,7 @@ hide:

    Architecture, frontend, backend, fullstack, QA, DevOps, SecOps, AI/ML, data engineering, Playwright testing, self-improving agent

-    [:octicons-arrow-right-24: 25 skills](skills/engineering-team/)
+    [:octicons-arrow-right-24: 26 skills](skills/engineering-team/)

 -   :material-lightning-bolt:{ .lg .middle } **Engineering — Advanced**

--- a/docs/plugins/index.md
+++ b/docs/plugins/index.md
@@ -1,13 +1,13 @@
 ---
 title: "Agent Plugin Marketplace — Codex & OpenClaw Plugins"
-description: "21 installable agent plugins for Claude Code, Codex CLI, Gemini CLI, and OpenClaw. One-command install for engineering, marketing, product, compliance, and finance skill bundles."
+description: "28 installable agent plugins for Claude Code, Codex CLI, Gemini CLI, and OpenClaw. One-command install for engineering, marketing, product, compliance, and finance skill bundles."
 ---

 <div class="skills-hero" markdown>

 # Plugins & Marketplace

-**19 installable plugins** — domain bundles and standalone packages distributed via Claude Code plugin registry and ClawHub.
+**28 installable plugins** — domain bundles and standalone packages distributed via Claude Code plugin registry and ClawHub.

 <p class="skills-hero-sub">Install entire skill domains or individual tools with a single command. Compatible with Claude Code, OpenAI Codex, Gemini CLI, and OpenClaw.</p>

@@ -19,7 +19,7 @@ description: "21 installable agent plugins for Claude Code, Codex CLI, Gemini CL

 <div class="grid cards" markdown>

-   :material-puzzle-outline:{ .lg .middle } **19 Plugins**
+-   :material-puzzle-outline:{ .lg .middle } **28 Plugins**

    ---

@@ -90,7 +90,7 @@ description: "21 installable agent plugins for Claude Code, Codex CLI, Gemini CL
 ```mermaid
 graph TB
    subgraph Registry["Plugin Registry"]
-        MP["marketplace.json<br/>19 plugins"]
+        MP["marketplace.json<br/>28 plugins"]
    end

    subgraph Bundles["Domain Bundles (9)"]
--- a/docs/skills/engineering-team/a11y-audit.md
+++ b/docs/skills/engineering-team/a11y-audit.md
--- a/docs/skills/engineering-team/index.md
+++ b/docs/skills/engineering-team/index.md
@@ -1,13 +1,13 @@
 ---
 title: "Engineering - Core Skills — Agent Skills & Codex Plugins"
-description: "40 engineering - core skills — engineering agent skill and Claude Code plugin for code generation, DevOps, architecture, and testing. Works with Claude Code, Codex CLI, Gemini CLI, and OpenClaw."
+description: "41 engineering - core skills — engineering agent skill and Claude Code plugin for code generation, DevOps, architecture, and testing. Works with Claude Code, Codex CLI, Gemini CLI, and OpenClaw."
 ---

 <div class="domain-header" markdown>

 # :material-code-braces: Engineering - Core

-<p class="domain-count">40 skills in this domain</p>
+<p class="domain-count">41 skills in this domain</p>

 </div>

@@ -17,6 +17,12 @@ description: "40 engineering - core skills — engineering agent skill and Claud

 <div class="grid cards" markdown>

+-   **[Accessibility Audit](a11y-audit.md)**
+
+    ---
+
+    ---
+
 -   **[AWS Solution Architect](aws-solution-architect.md)**

    ---