/seo-ai-optimizer

name: seo-ai-optimizer
description: "Audit and optimize websites for technical SEO, content SEO, and AI bot accessibility. Fixes meta tags, sitemaps, robots.txt, structured data, llms.txt, and GPTBot/ClaudeBot directives. Don't use for App Store ASO, paid search, or blog writing."
license: MIT
effort: high
metadata:
  version: 1.6.0
  author: "Luong NGUYEN <luongnv89@gmail.com>"

SEO & AI Bot Optimizer

Audit and optimize website codebases for search engines and AI systems.

Dependency Preflight (mandatory)

Step 8 invokes `website-agent-readiness`. Verify it is installed **before** the first step that changes anything:

test -d "$HOME/.claude/skills/website-agent-readiness" ||
  asm list -p claude --json | grep -q '"website-agent-readiness"' || {
  echo "Missing required skill: website-agent-readiness" >&2
  echo "Install it:      asm install github:luongnv89/skills:skills/website-agent-readiness -p claude -s global --yes" >&2
  echo "No asm yet:      npm install -g agent-skill-manager" >&2
  echo "Verify:          asm list -p claude --json | grep 'website-agent-readiness'" >&2
}

Test the install path first: a repo-installed `website-agent-readiness` is absent from the curated registry, so an `asm list` check alone would nag on every run and a bare-name `asm install` would not resolve.

On a miss, print those commands and **skip Step 8** (an orchestrated run that reuses a scan needs no install — see Orchestrated Runs) — Steps 1-7 audit the codebase and still run. Never invoke a half-installed skill. `website-agent-readiness` enforces its own prerequisites (`curl`, `python3`, and for issue filing `git`, `gh`, `plan-to-issues`); this skill does not re-check them.

Repo Sync Before Edits (mandatory)

Before modifying any project files, sync the current branch with remote. Stash first, so a dirty working tree never meets a bare rebase:

stashed=0
if [ -n "$(git status --porcelain)" ]; then git stash push -u -m "pre-sync" && stashed=1; fi
branch="$(git rev-parse --abbrev-ref HEAD)"
if git fetch origin && git pull --rebase origin "$branch"; then
  if [ "$stashed" = 1 ]; then git stash pop; fi
fi

If `origin` is missing, the pull fails, or the rebase or stash pop conflicts, stop and ask the user before continuing. A rebase conflict leaves the stash in place: run `git rebase --abort`, then `git stash pop`.

Prerequisites

• **Environment:** The project is a git repository (except a live-evidence-only orchestrated run — see Orchestrated Runs). Otherwise stop.
• **Tools:** Python 3.x on the path, for the bundled `scripts/audit_seo.py`.
• **Access:** Write access to the project, including new files (robots.txt, llms.txt).

Quick Reference

Read each file only when its step needs it, to keep the context window small:

• `references/workflow-detail.md` — checklists, templates, implementation steps
• `references/technical-seo.md` — full SEO checklist
• `references/framework-configs.md` — framework-specific configuration
• `references/ai-bot-guide.md` — AI crawler directives, llms.txt format, JSON-LD templates

Environment Check

If the Agent tool is available, run the 4-phase subagent workflow in `references/subagent-architecture.md`. Otherwise run the same audit in one conversation; the audit report is the same.

Important

• Audit first, present findings, then propose a plan — never modify files without user approval
• **Safety First:** Always show a diff and get explicit confirmation before writing any file change
• Fetch latest best practices via web search during each audit to supplement embedded knowledge

Workflow

1. **Detect** -- Identify project framework and scan for relevant files 2. **Audit** -- Run automated scan + manual review across 4 categories 3. **Research** -- Web search for latest SEO/AI bot best practices 4. **Report** -- Present findings grouped by severity 5. **Plan** -- Propose prioritized improvements for user approval 6. **Implement** -- Apply approved changes following the Safety Protocol 7. **Validate** -- Re-check modified files 8. **Agent-readiness handoff** -- Scan the deployed site via `/website-agent-readiness`

---

Step 1: Detect Project Type

Run the audit script to detect framework and scan files:

python scripts/audit_seo.py <project-root>

If the script reports "No HTML/template files found," inform the user: this skill is designed for web frontends with HTML output.

Step 2: Audit

The audit script checks **per-file issues** and **project-level issues**. After running the script, perform a manual review for items requiring human judgment (content quality, links, E-E-A-T).

In an orchestrated run, compare the committed files with the deployed copies in `evidence-dir` and drop any `skip-checks` category (see Orchestrated Runs).

For the full manual review checklist, see `references/workflow-detail.md`.

Step 3: Research Latest Best Practices

Use web search to check for updates (SEO best practices, AI bot directives, llms.txt spec, algorithm updates). Compare findings with embedded knowledge in `references/`.

Step 4: Report

Present the audit report grouping findings by severity (Critical, Warning, Info) and project-level findings (robots.txt, sitemap, llms.txt, JSON-LD). With `output-dir`, also write it to `<output-dir>/seo-audit-report.md`.

Step 5: Plan

Present a prioritized improvement plan using the template in `references/workflow-detail.md`.

Ask the user: "Which improvements should I implement? You can approve all, select specific items, or modify the plan."

Do NOT proceed without explicit approval.

Step 6: Implement

Apply approved changes following the **Safety First** protocol:

1. **Show Diff:** For every file change, generate and show a clear diff or summary. 2. **Confirm:** Request explicit user confirmation before writing each file (or batch).

For detailed implementation instructions per category (Technical SEO, robots.txt, llms.txt, JSON-LD, sitemaps), see