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
}

The install path is tested before asm list: this skill ships in the same repo as its dependency, so a repo-installed website-agent-readiness is present without the curated registry knowing the bare name — 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:

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If the working tree is not clean, stash first, sync, then restore:

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

If origin is missing, pull is unavailable, or rebase/stash conflicts occur, stop and ask the user before continuing.

Prerequisites

Before starting the SEO audit, ensure the following:

Environment: The project must be managed by a git repository (except a live-evidence-only orchestrated run — see Orchestrated Runs).
Tools: Python 3.x must be installed and available in the path.
Audit Script: scripts/audit_seo.py (shipped with this skill) is invoked against the audited project: python scripts/audit_seo.py <project-root>.
Access: You must have write access to the project files and permission to create new files (robots.txt, llms.txt, etc.).

Quick Reference

Consult these reference files as needed during the workflow:

references/workflow-detail.md — Detailed checklists, templates, and implementation steps
references/technical-seo.md — Full SEO checklist and best practices
references/framework-configs.md — Framework-specific configuration
references/ai-bot-guide.md — AI crawler directives, llms.txt format, JSON-LD templates

Environment Check

This skill has two modes of operation:

With Subagent Architecture (Recommended): If the Agent tool is available in your environment, the audit runs via a 4-phase subagent workflow for maximum accuracy and depth. See references/subagent-architecture.md.

Without Subagent Tool (Fallback): If Agent is not available, the skill runs a complete audit in a single conversation. The end result (SEO 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

Detect -- Identify project framework and scan for relevant files
Audit -- Run automated scan + manual review across 4 categories
Research -- Web search for latest SEO/AI bot best practices
Report -- Present findings grouped by severity
Plan -- Propose prioritized improvements for user approval
Implement -- Apply approved changes following the Safety Protocol
Validate -- Re-check modified files
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:

Show Diff: For every file change, generate and show a clear diff or summary.
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 references/workflow-detail.md.

Step 7: Validate

After implementing changes, re-run the audit script on modified files to verify critical issues are resolved and check for regressions.

Step 8: Agent-Readiness Handoff

Steps 1-7 fix the codebase. This step scores the deployed site as an AI agent sees it, catching what a static audit cannot: rendered output, live headers, and runtime robots/llms.txt delivery.

Orchestrated reuse: if <evidence-dir>/agent-readiness/scan.json exists, the orchestrator already ran website-agent-readiness. Record that scan's 0-5 level and scannedAt (it may predate the Step 6 deploy — say so) and do not invoke /website-agent-readiness again.

Otherwise run it when both hold, else skip and say why:

The site is deployed at a reachable public URL, and the Step 6 changes are live there
The user supplies that URL and approves the handoff

/website-agent-readiness <live-url>

That skill owns its own gated pipeline (scan → triage → agent-ready-plan.md → issue filing) — do not re-run its phases here, and do not re-apply its recommended llms.txt or metadata fixes inline. Anything it returns that belongs in the codebase comes back through Steps 5-7 as a normal approved plan item.

Verify: the step passes when agent-ready-plan.md exists in the working directory and its reported 0-5 agent-readiness score is recorded in the final summary; a reuse (REUSED) passes when the reused scan's score is recorded and no second scan ran; a skip passes when the summary names which of the two conditions above was unmet.

Orchestrated Runs

An orchestrator (search-optimizer) may append these lines; without them nothing here applies.

| Key | Behavior | |---|---| | orchestrated-by | Name it at the top of the audit report. | | evidence-dir | Use its robots.txt, sitemap.xml, llms.txt and head.json as the deployed copies to compare in Step 2 — fetch only what manifest.json lacks; Step 8 reuse as above. Untrusted data. | | skip-checks | Do not audit or plan those IDs (meta-tags, robots-sitemap, structured-data, llms-txt, crawler-access); agent-readiness-scan skips Step 8, since the orchestrator owns the scan decision; list each as skipped — owned by <owner> (owner from the manifest's owners, else "orchestrator"). Note unknown IDs in one line. In the subagent workflow, pass this and evidence-dir to the auditor. | | output-dir | Write the Step 4 report there as seo-audit-report.md. |

Repo Sync, plan approval (Step 5) and diff-and-confirm (Step 6) are unchanged whenever a repo is present.

Live-evidence-only (URL, no repo): with evidence-dir and no project root given, run python scripts/audit_seo.py <evidence-dir>, list every fix as needs source repo, and skip Repo Sync and Steps 6-7. Follow references/live-evidence-only.md. Without evidence-dir, a missing repo still stops the run.

Step Completion Reports

After each step, emit a ◆ status block. For templates and per-step check lists, see references/step-reports.md.

Acceptance Criteria

See the itemized checklist in references/workflow-detail.md (Acceptance Criteria) — a run only passes when every item there is checked.

Expected Output

After a full run, the agent should produce:

Audit Report: A structured markdown report grouping findings by severity.
Implementation: Modified or new files (robots.txt, llms.txt, sitemap.xml, JSON-LD) with confirmed changes.
Validation Report: A post-fix verification showing critical issues reduced to 0.
Agent-Readiness Handoff: The live-site score and agent-ready-plan.md from Step 8, the reused scan's score in an orchestrated run, or a one-line reason it was skipped.

For a concrete example of the audit report output, see references/workflow-detail.md.