# 2572 Audit SEO 9bb85c62 > Audit a web app's SEO — meta tags, crawlability, performance, and content structure - Skill: `tools-only/2572-audit-seo-9bb85c62` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/2572-audit-seo-9bb85c62` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/2572-audit-seo-9bb85c62/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Marketing & Growth - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/tools-only/2572-audit-seo-9bb85c62 --- # SEO Audit: $ARGUMENTS **READ-ONLY MODE**: This command audits a web application's SEO readiness and reports findings. It does NOT make code changes. Use the findings to create follow-up tasks or PRs. ## Options - `--local` — Show findings locally only, skip GitHub posting - `--repo OWNER/NAME` — Audit a specific GitHub repo (clones it to /tmp) - No arguments — Audit the current working directory ## Examples ```bash /audit-seo # Audit current repo, prompt for posting /audit-seo --local # Audit current repo, show locally only /audit-seo --repo PolicyEngine/us-marriage-incentive # Audit a specific repo /audit-seo --repo PolicyEngine/us-marriage-incentive --local ``` --- ## Phase 0: Parse Arguments & Setup ``` Parse $ARGUMENTS: - LOCAL_ONLY: true if --local flag present - REPO_ARG: value after --repo if present (e.g., "PolicyEngine/us-marriage-incentive") - If no --repo: use current working directory ``` ### Determine Posting Mode **If `--local` flag**: Skip prompt, proceed in local-only mode. **If no flag**: Use `AskUserQuestion`: ``` Question: "Post SEO audit findings to GitHub when complete?" Options: - "Yes, create a GitHub issue with findings" (default) - "No, show locally only" ``` ### Determine Target Repository **If `--repo` is provided:** ```bash # Clone to temp directory gh repo clone $REPO_ARG /tmp/seo-audit-target -- --depth 1 AUDIT_DIR="/tmp/seo-audit-target" ``` **If no `--repo`:** ```bash AUDIT_DIR="$(pwd)" ``` Verify this is a web application by checking for `index.html`, `frontend/index.html`, `frontend/app/layout.tsx`, or `package.json` with a frontend framework dependency. --- ## Phase 1: Gather Context Collect information about the project: ```bash # Get repo info REPO_NAME=$(basename $(git -C $AUDIT_DIR remote get-url origin 2>/dev/null) .git || basename $AUDIT_DIR) REPO_FULL=$(git -C $AUDIT_DIR remote get-url origin 2>/dev/null | sed 's|.*github.com[:/]||;s|\.git$||') # Check for built output (root and monorepo) ls $AUDIT_DIR/dist/ 2>/dev/null || ls $AUDIT_DIR/build/ 2>/dev/null ls $AUDIT_DIR/frontend/dist/ 2>/dev/null || ls $AUDIT_DIR/frontend/build/ 2>/dev/null # Detect project structure ls $AUDIT_DIR/frontend/package.json 2>/dev/null # monorepo? ls $AUDIT_DIR/frontend/app/layout.tsx 2>/dev/null # Next.js? # Identify framework (check both root and frontend/) cat $AUDIT_DIR/package.json | grep -E '"(react|vue|svelte|next|vite|gatsby)"' cat $AUDIT_DIR/frontend/package.json 2>/dev/null | grep -E '"(react|vue|svelte|next|vite|gatsby)"' # Check hosting ls $AUDIT_DIR/.github/workflows/ 2>/dev/null cat $AUDIT_DIR/vercel.json 2>/dev/null cat $AUDIT_DIR/netlify.toml 2>/dev/null ``` **Document:** - Repository name and URL - Project structure (Vite SPA, Vite Monorepo, Next.js Monorepo, etc.) - Framework (React, Vue, Next.js, etc.) - Build tool (Vite, CRA, Webpack, etc.) - Hosting platform (GitHub Pages, Vercel, Netlify, Cloud Run, Modal) - Whether built output exists locally --- ## Phase 2: Run Build (if needed) If no `dist/` or `build/` directory exists, attempt to build: ```bash cd $AUDIT_DIR npm install 2>/dev/null || yarn install 2>/dev/null npm run build 2>/dev/null || yarn build 2>/dev/null ``` The built output is needed for accurate bundle size analysis and to check what HTML Google actually receives. If the build fails, note this and continue with source-only analysis. --- ## Phase 3: Spawn Specialist Agents Spawn all four agents in parallel using `run_in_background: true` with `subagent_type: general-purpose`. ### Agent 1: Meta Tag Checker Invoke **seo-meta-checker** agent: ``` Audit the web application at $AUDIT_DIR for SEO meta tags. Follow the instructions in agents/app/seo-meta-checker.md. Read the index.html file and check all meta tags, OG tags, Twitter cards, canonical URL, and structured data. Report findings in the specified format. ``` ### Agent 2: Crawlability Checker Invoke **seo-crawlability-checker** agent: ``` Audit the web application at $AUDIT_DIR for crawlability. Follow the instructions in agents/app/seo-crawlability-checker.md. Check robots.txt, sitemap.xml, routing type, SSR/pre-rendering, 404 handling, and duplicate content risk. Report findings in the specified format. ``` ### Agent 3: Performance Checker Invoke **seo-performance-checker** agent: ``` Audit the web application at $AUDIT_DIR for SEO-impacting performance issues. Follow the instructions in agents/app/seo-performance-checker.md. Check bundle sizes, code splitting, image optimization, font loading, and render-blocking resources. Report findings in the specified format. ``` ### Agent 4: Content & Structure Checker Invoke **seo-content-checker** agent: ``` Audit the web application at $AUDIT_DIR for content structure and semantic HTML. Follow the instructions in agents/app/seo-content-checker.md. Check heading hierarchy, semantic elements, link quality, accessibility, and content quality. Report findings in the specified format. ``` --- ## Phase 4: Collect & Score Results Wait for all agents to complete. Aggregate their scores. ### Scoring Each agent scores their domain out of their total checks. Combine into an overall score: | Category | Agent | Max Points | Weight | |----------|-------|-----------|--------| | Meta Tags | seo-meta-checker | 19 | 30% | | Crawlability | seo-crawlability-checker | 7 | 30% | | Performance | seo-performance-checker | 7 | 20% | | Content & Structure | seo-content-checker | 7 | 20% | **Overall Score** = weighted average, expressed as percentage (0-100%). ### Score Interpretation | Score | Rating | Meaning | |-------|--------|---------| | 80-100% | Excellent | SEO-ready, minor improvements possible | | 60-79% | Good | Fundamentals covered, some gaps | | 40-59% | Needs Work | Significant gaps affecting discoverability | | 20-39% | Poor | Major issues preventing indexing | | 0-19% | Critical | Essentially invisible to search engines | --- ## Phase 5: Compile Report ### Determine Deployed URL Try to determine the live URL: - Check for CNAME file in `public/` or repo root - Check GitHub Pages settings: `https://{org}.github.io/{repo}/` - Check vercel.json or netlify.toml for custom domains - If policyengine.org embeds the app, note both URLs ### Report Structure ```markdown ## SEO Audit Report: {REPO_NAME} **Score: XX/100 ({Rating})** **Deployed URL:** {URL or "Unknown"} **Framework:** {React/Vue/etc.} + {Vite/CRA/etc.} **Hosting:** {GitHub Pages/Vercel/Netlify} --- ### Summary | Category | Score | Status | |----------|-------|--------| | Meta Tags | X/19 | {emoji} | | Crawlability | X/7 | {emoji} | | Performance | X/7 | {emoji} | | Content & Structure | X/7 | {emoji} | ### Critical Issues (must fix) 1. **{Issue}** — {Description and why it matters} 2. ... ### Important Issues (should fix) 1. **{Issue}** — {Description} 2. ... ### Suggestions (nice to have) 1. **{Issue}** — {Description} 2. ... --- ### Detailed Findings #### Meta Tags {Full report from seo-meta-checker} #### Crawlability {Full report from seo-crawlability-checker} #### Performance {Full report from seo-performance-checker} #### Content & Structure {Full report from seo-content-checker} --- ### Standalone + Iframe Assessment - **Standalone URL:** {GitHub Pages URL} - **Embedded on:** {policyengine.org URL if detectable} - **Canonical strategy:** {Present/Missing/Misconfigured} - **Duplicate content risk:** {Low/Medium/High} ### Next Steps 1. {Prioritized action item} 2. {Prioritized action item} 3. ... --- *Audited by `/audit-seo` — PolicyEngine Claude Plugin* ``` --- ## Phase 6: Post Results **If user chose local-only mode**: Display the full report in the terminal. **If user chose to post to GitHub**: Create a GitHub issue on the audited repo. ```bash gh issue create \ --repo "$REPO_FULL" \ --title "SEO Audit: Score XX/100 — {N} critical issues found" \ --body "$REPORT_BODY" \ --label "seo,audit" ``` If the `seo` or `audit` labels don't exist, create the issue without labels: ```bash gh issue create \ --repo "$REPO_FULL" \ --title "SEO Audit: Score XX/100 — {N} critical issues found" \ --body "$REPORT_BODY" ``` Report the issue URL to the user. --- ## Key Rules 1. **READ-ONLY**: Never edit files. This is an audit. 2. **Build if possible**: Bundle sizes from built output are more accurate than estimates. 3. **Account for dual-mode**: Always check for standalone + iframe usage patterns. 4. **Prioritize findings**: Critical > Important > Suggestions. 5. **Be actionable**: Every finding should include what to do about it. 6. **Score consistently**: Use the same scoring across all repos for comparison. --- ## Pre-Flight Checklist Before starting: - [ ] I will NOT make any code changes - [ ] I will ask about posting mode FIRST (unless --local flag used) - [ ] I will run all 4 specialist checks - [ ] I will account for the standalone + iframe dual-mode - [ ] I will prioritize findings by severity - [ ] I will include actionable next steps Start by parsing arguments, then proceed through all phases.