# SEO AI Optimizer > Audits and optimizes website codebases for SEO and AI bot scanning. Covers technical SEO (meta tags, sitemaps, robots.txt, canonical URLs, page speed hints, structured data), content SEO (heading structure, alt text, readability), and AI bot accessibility (llms.txt, GPTBot/ClaudeBot directives, ai-plugin.json, Schema.org/JSON-LD). Use when user asks to "optimize for SEO", "audit SEO", "improve search rankings", "make site AI-friendly", "add structured data", "fix meta tags", or "optimize for AI bots". Works with any web framework. Use when this capability is needed. - Skill: `tomevault-io/seo-ai-optimizer` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/seo-ai-optimizer` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/seo-ai-optimizer/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Marketing & Growth - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/seo-ai-optimizer --- # SEO & AI Bot Optimizer Audit and optimize website codebases for search engines and AI systems. ## Repo Sync Before Edits (mandatory) Before modifying any project files, sync the current branch with remote: ```bash 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: ```bash 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. ## Quick Reference Consult these reference files as needed during the workflow: - `references/technical-seo.md` — Full SEO checklist and best practices - `references/framework-configs.md` — Framework-specific configuration (Next.js, Nuxt, Astro, Hugo, etc.) - `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 "Subagent Architecture" section below. **Without Subagent Tool (Fallback):** If Agent is not available, the skill still runs a complete audit in a single conversation, though without the structured intermediate data format. The end result (SEO audit report) is the same. ## Subagent Architecture When the Agent tool is available, this skill uses a 4-phase, multi-agent architecture optimized for large websites: ### Phase 1: Auditor Agent **Purpose:** Run automated SEO audit and manual review checklist This agent: - Scans website files for technical SEO issues (meta tags, headings, canonical URLs, structured data) - Checks project-level files (robots.txt, sitemap.xml, llms.txt, ai-plugin.json) - Performs manual review of content quality, internal linking, and framework configuration - Creates seo-audit.json: a complete machine-readable inventory of all SEO issues with severity levels **Output artifact:** `/seo-audit.json` ### Phase 2: Researcher Agent **Purpose:** Fetch latest SEO and AI-bot best practices via web search This agent: - Performs 4+ targeted web searches covering SEO best practices, meta tags, AI-bot directives, framework-specific guidance - Synthesizes findings into actionable recommendations - Compares research against audit findings to identify gaps - Creates seo-research-findings.json: structured research results and recommendations with citations **Output artifact:** `/seo-research-findings.json` ### Phase 3: Implementer Agent **Purpose:** Apply user-approved changes per category (meta tags, robots.txt, llms.txt, structured data, sitemaps) This agent: - Receives user-approved list of improvements to apply - Implements changes categorized by type (meta tags, robots.txt, AI bot directives, JSON-LD, sitemap, etc.) - Handles framework-specific implementation (Next.js, Nuxt, Astro, Hugo, SvelteKit, static HTML) - Produces modified source files ready for testing **Output:** Modified project files with git-ready changes ### Phase 4: Validator Agent **Purpose:** Re-run audit on modified site, return before/after comparison This agent: - Re-runs the audit script on the modified website - Produces before/after comparison showing what was fixed - Validates critical files (robots.txt syntax, JSON-LD validity, canonical URLs, image links) - Creates seo-validation-report.json: detailed delta report with recommendations for remaining work **Output artifact:** `/seo-validation-report.json` ### Data Flow ``` Website Project ↓ [Auditor] → seo-audit.json ↓ [Researcher] → seo-research-findings.json ↓ (User reviews & approves improvements) ↓ [Implementer] → Modified source files ↓ [Validator] → seo-validation-report.json ↓ (User reviews improvements & validates results) ``` Each agent is self-contained, with clear responsibilities and structured outputs that can be reviewed independently. ## Important - Audit first, present findings, then propose a plan — never modify files without user approval - Fetch latest best practices via web search during each audit to supplement embedded knowledge - For large codebases (100+ pages), audit a representative sample and offer to expand ## 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 7. **Validate** -- Re-check modified files --- ## Step 1: Detect Project Type Run the audit script to detect framework and scan files: ```bash python scripts/audit_seo.py ``` The script automatically: - Detects the framework (Next.js, Nuxt, Astro, Hugo, SvelteKit, static HTML, etc.) - Finds all HTML/template files (excluding node_modules, build dirs) - Samples representative files for large codebases If the script reports "No HTML/template files found," inform the user: this skill is designed for web frontends with HTML output. For framework-specific configuration guidance, consult `references/framework-configs.md`. ## Step 2: Audit The audit script checks **per-file issues** and **project-level issues**. ### Per-File Checks (automated) - **Technical SEO:** title tag, meta description, viewport, charset, canonical, lang attribute - **Content SEO:** H1 presence/count, heading hierarchy, image alt text, image dimensions - **Structured Data:** JSON-LD presence/validity, OpenGraph tags, Twitter Cards - **Performance:** render-blocking scripts, lazy-loading on LCP candidates ### Project-Level Checks (automated) - robots.txt existence and AI bot directives - sitemap.xml existence (or sitemap generation package) - llms.txt existence - ai-plugin.json existence ### Manual Review (after script) After running the script, manually review these items that require human judgment: 1. **Title/description quality** -- Are they compelling and keyword-relevant? (not just present) 2. **Structured data accuracy** -- Does JSON-LD match visible page content? 3. **Internal linking** -- Are pages reachable within 3 clicks? Descriptive anchors? 4. **Content depth** -- Sufficient E-E-A-T signals? Author bios? Source citations? 5. **Framework-specific config** -- Are SEO packages properly configured? Consult `references/technical-seo.md` for the full checklist. ## Step 3: Research Latest Best Practices Use web search to check for updates: ``` Search: "SEO best practices [current year]" Search: "AI bot robots.txt directives [current year]" Search: "llms.txt specification latest" Search: "Google algorithm update [current month/year]" ``` Compare findings with embedded knowledge in `references/` and note any new recommendations. ## Step 4: Report Present the audit report to the user in this format: ```markdown ## SEO & AI Bot Audit Report **Project:** [project name] **Framework:** [detected framework] **Files audited:** [N] / [total] **Date:** [date] ### Critical Issues (must fix) 1. [File:line] Issue description 2. ... ### Warnings (should fix) 1. [File:line] Issue description 2. ... ### Info (nice to have) 1. Issue description 2. ... ### Project-Level Findings - robots.txt: [status] - sitemap.xml: [status] - llms.txt: [status] - Structured data: [status] - AI bot directives: [status] ### Latest Best Practices (from web search) - [Any new recommendations not covered by existing fixes] ``` ## Step 5: Plan Present a prioritized improvement plan: ```markdown ## Improvement Plan ### Priority 1: Critical Fixes - [ ] [Fix description] -- [file(s) affected] - [ ] ... ### Priority 2: Warnings - [ ] [Fix description] -- [file(s) affected] - [ ] ... ### Priority 3: Enhancements - [ ] [Fix description] -- [file(s) affected] - [ ] ... ### New Files to Create - [ ] robots.txt with AI bot directives - [ ] sitemap.xml (or install generation package) - [ ] llms.txt - [ ] JSON-LD structured data ``` 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. For each category: ### Technical SEO Fixes - Add/fix meta tags, title, description, viewport, charset, canonical, lang - For framework-specific implementation, consult `references/framework-configs.md` ### robots.txt with AI Bot Directives - Consult `references/ai-bot-guide.md` for the full list of AI crawlers - Ask user preference: allow all AI bots, allow search only, or block all - Include sitemap reference: `Sitemap: https://example.com/sitemap.xml` ### llms.txt Generation - Create based on site structure and content - Follow format in `references/ai-bot-guide.md` - Include H1 with site name, blockquote summary, H2 sections with key page links ### Structured Data (JSON-LD) - Add Organization schema on homepage - Add Article/BlogPosting on content pages - Add Product on e-commerce pages - Add BreadcrumbList for navigation - Consult `references/ai-bot-guide.md` for templates ### OpenGraph & Twitter Cards - Add og:title, og:type, og:image, og:url, og:description - Add twitter:card, twitter:title, twitter:description, twitter:image ### sitemap.xml - Generate or install appropriate package for the framework - See `references/framework-configs.md` for framework-specific packages ## Step 7: Validate After implementing changes: 1. Re-run the audit script on modified files: ```bash python scripts/audit_seo.py ``` 2. Verify critical issues are resolved 3. Report remaining warnings to user ## Step Completion Reports After completing each major step, output a status report in this format: ``` ◆ [Step Name] ([step N of M] — [context]) ·································································· [Check 1]: √ pass [Check 2]: √ pass (note if relevant) [Check 3]: × fail — [reason] [Check 4]: √ pass [Criteria]: √ N/M met ____________________________ Result: PASS | FAIL | PARTIAL ``` Adapt the check names to match what the step actually validates. Use `√` for pass, `×` for fail, and `—` to add brief context. The "Criteria" line summarizes how many acceptance criteria were met. The "Result" line gives the overall verdict. ### Phase-specific checks **Step 1 — Detection** ``` ◆ Detection (step 1 of 7 — project scan) ·································································· Framework identified: √ pass (Next.js | Nuxt | Astro | ...) File structure mapped: √ pass (N HTML/template files found) ____________________________ Result: PASS | FAIL | PARTIAL ``` **Step 2 — Audit** ``` ◆ Audit (step 2 of 7 — SEO analysis) ·································································· Meta tags checked: √ pass (N files scanned) Structured data validated: √ pass (JSON-LD present/valid) AI bot access verified: √ pass (robots.txt + llms.txt checked) ____________________________ Result: PASS | FAIL | PARTIAL ``` **Step 3 — Research** ``` ◆ Research (step 3 of 7 — best practices lookup) ·································································· Web searches completed: √ pass (N queries executed) Latest practices fetched: √ pass (current year updates noted) Gaps identified: √ pass | × fail — [missing coverage areas] ____________________________ Result: PASS | FAIL | PARTIAL ``` **Step 4 — Report** ``` ◆ Report (step 4 of 7 — findings presentation) ·································································· Issues categorized: √ pass (critical/warning/info grouped) Project-level findings: √ pass (robots.txt, sitemap, llms.txt, JSON-LD) Report presented: √ pass ____________________________ Result: PASS | FAIL | PARTIAL ``` **Step 5 — Plan** ``` ◆ Plan (step 5 of 7 — improvement planning) ·································································· Priorities ranked: √ pass (critical → warnings → enhancements) New files identified: √ pass (N files to create) User approval received: √ pass | × fail — [awaiting approval] ____________________________ Result: PASS | FAIL | PARTIAL ``` **Step 6 — Implementation** ``` ◆ Implementation (step 6 of 7 — applying fixes) ·································································· Fixes applied: √ pass (N issues resolved) Sitemaps updated: √ pass Schema.org added: √ pass (Organization + Article JSON-LD) ____________________________ Result: PASS | FAIL | PARTIAL ``` **Step 7 — Validation** ``` ◆ Validation (step 7 of 7 — post-fix verification) ·································································· SEO score improved: √ pass (critical issues: N → 0) No regressions: √ pass AI crawl accessible: √ pass (llms.txt + GPTBot/ClaudeBot allowed) ____________________________ Result: PASS | FAIL | PARTIAL ``` ## Error Handling ### No HTML Files Found **Cause:** API-only backend or non-web project. **Solution:** Inform user this skill is for web frontends. Exit gracefully. ### Framework Config Not Found **Cause:** Framework detected but config file missing or non-standard location. **Solution:** Warn and skip framework-specific optimizations. Proceed with generic HTML analysis. ### Web Search Fails **Cause:** Network issues or rate limiting. **Solution:** Fall back to embedded best practices in `references/`. Note that latest guidelines could not be fetched. ### Large Codebase **Cause:** 100+ HTML/template files. **Solution:** The audit script samples 50 representative files by default. Offer to increase with `--max-files N`. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/luongnv89) — claim your Tome and manage your conversions.