tag | Add a unique, descriptive title (~50-60 chars) reflecting the page's main topic | | 2 | High | High | No H1 on the page | Add a single H1 matching the page's primary topic/keyword | ``` Keep this conversational, not a file/artifact — the user replies "let's do #1" right after. Keep numbering stable for the rest of the conversation even if rows get resolved or dropped; just note a row is handled rather than renumbering. If the user later asks about a specific ID, give a fuller explanation: why it matters, exactly how to fix it (with markup/code examples), and how to verify the fix worked. ## Edge cases - **Meta tags not visible in fetched content** — mark the check "not verified", don't assume pass or fail. - **robots.txt / sitemap not fetchable directly** — search for them instead of guessing the URL; if search doesn't surface them, mark related checks "not verified." - **PageSpeed Insights unreachable** — skip the performance section's findings, mention once in the summary, don't fabricate numbers. - **Multi-page request** — repeat the full workflow per page; either produce one table per page or one combined table with a "Page" column, whichever the user prefers. - **Never fabricate data** — only report what `web_fetch`/`web_search`/PageSpeed actually returned. --- # SEO Audit Checklist Work through each section for the fetched page. For every item that fails or is suboptimal, create a finding with a Severity and Effect rating (see the scoring grid in Step 5 above). Skip items you genuinely cannot verify from the fetched content — flag them as "not verified" rather than guessing. ## 1. Indexability & crawlability (usually the highest-severity category) - **Robots meta / X-Robots-Tag**: Is the page accidentally set to `noindex` or `nofollow`? → If yes: **Critical severity, High effect** (nothing else matters if the page can't be indexed). - **Robots.txt**: Does robots.txt block this URL or the section it's in? (search for it, don't guess the URL) - **Canonical tag**: Present? Self-referencing or pointing elsewhere unexpectedly? A wrong canonical pointing to a different URL is Critical/High. - **HTTP status**: Confirm the page actually returned 200 (a fetch that redirected repeatedly or errored is itself a finding). - **HTTPS**: Is the page served over HTTPS? Any mixed-content resources loaded over HTTP? - **Sitemap**: Can you confirm the page is included in an XML sitemap? (search, don't guess URL) ## 2. Title tag & meta description - **Title tag**: Present, unique, and descriptive? Ideal length ~50-60 characters (roughly under 580px). Missing title = Critical/High. Generic/duplicate-sounding title (e.g. just the brand name with no context) = Medium/Medium. - **Primary keyword placement**: Does the title reflect what the page is actually about / what a user would search for? - **Meta description**: Present, unique, compelling, roughly 120-160 characters? Missing isn't as severe as a missing title (Google will auto-generate one) — usually Medium/Medium. ## 3. Heading structure - **Single H1**: Exactly one H1 that describes the page's main topic? Zero H1s or multiple competing H1s = Medium-High severity, Medium effect. - **Logical hierarchy**: Do H2s/H3s nest sensibly under the H1, or does the page skip levels / use headings just for styling? - **Keyword relevance**: Do headings reflect the topics a user searching for this page would expect to see? ## 4. Content quality - **Depth/uniqueness**: Is there enough substantive, unique content to satisfy search intent, or is it thin (e.g. a few sentences padded with images)? Thin content on a page meant to rank competitively = High severity, High effect. - **Search intent match**: Does the content actually answer what someone searching for this topic wants (informational vs. transactional vs. navigational)? - **Readability**: Overly long unbroken paragraphs, no subheadings/lists breaking up content for scannability. - **Freshness signals**: For time-sensitive content, any visible dates that look stale? - **Keyword cannibalization risk**: Only flag this if you have visibility into other pages on the site (e.g. from internal links) that appear to target the same query. ## 5. Image optimization - **Alt text**: Missing alt text on meaningful/content images (not decorative ones) — Medium severity, Low-Medium effect (accessibility + image search). - **File names**: Generic names like `IMG_2931.jpg` vs. descriptive ones (minor, Low/Low). - **Oversized images**: Note if PageSpeed Insights flags unoptimized/oversized images — fold this into the performance section instead of double-counting. ## 6. Internal linking & site structure - **Internal links from this page**: Does the page link to other relevant pages with descriptive (not "click here") anchor text? - **Orphan risk**: Based on what you can see, does this page look reachable from clear navigation, or does it seem buried? - **Broken links**: Any internal/external links visibly pointing to obviously broken or placeholder URLs in the fetched content? ## 7. Structured data (Schema.org) - Only assess this if you can actually detect structured data in the fetched content (e.g. it surfaces in extracted markup/metadata) — otherwise mark as not verified rather than assuming absence. - If detectable and missing for an obviously schema-eligible page type (product, article, FAQ, local business, recipe, event) — Medium severity, Medium-High effect (rich results/CTR). - If present, check for obvious mismatches (e.g. schema type doesn't match page content). ## 8. Mobile & UX signals - Viewport meta tag present? Missing = High severity (mobile-first indexing), Medium-High effect. - Any obvious intrusive interstitials/pop-ups visible in the fetched content that would block content on mobile. ## 9. Performance / Core Web Vitals (from PageSpeed Insights, if available) - **LCP (Largest Contentful Paint)**: >4s = High severity; 2.5-4s = Medium; <2.5s = pass. - **CLS (Cumulative Layout Shift)**: >0.25 = High severity; 0.1-0.25 = Medium; <0.1 = pass. - **INP/TBT**: Flag if PageSpeed reports this as poor. - **Overall Performance score** under ~50 = High severity, Medium-High effect; 50-89 = Medium; 90+ = pass. - If PageSpeed Insights wasn't reachable, say so once in the summary rather than per-item, and skip this section's findings rather than fabricating numbers. ## 10. Social/sharing metadata (lower priority, usually Low/Low) - Open Graph and Twitter Card tags for title/description/image, only if visible in fetched content. Missing is typically Low severity, Low-Medium effect (affects share appearance, not rankings directly). --- ## Severity quick reference - **Critical**: page can't be indexed, or a core discoverability mechanism is broken/misconfigured. - **High**: significantly undermines rankings or usability for most visitors (missing title, thin content on a key page, failing Core Web Vitals, no mobile viewport). - **Medium**: a real gap best practice would fix, but the page still basically works and can rank. - **Low**: polish — worth doing, low downside if left alone. ## Effect quick reference - **High**: directly tied to ranking factors or indexability at scale. - **Medium**: helps CTR, secondary ranking signals, or user experience meaningfully. - **Low**: marginal, cosmetic, or affects a narrow slice of traffic/use cases.

--- name: seo-website-audit description: Runs an in-depth SEO audit of a single webpage (title/meta tags, headings, content quality, indexability, structured data, internal linking, image alt text, and Core Web Vitals via PageSpeed Insights) and returns a prioritized, numbered table of recommendations ranked by severity and effect. Use this whenever the user asks for an "SEO audit", "SEO review", "SEO analysis", wants to check a page/site for SEO issues, asks how to improve their search rankings, mentions "audit my website/page", or wants to know what to fix for Google/search visibility. Trigger even if they only paste a URL and say something like "what's wrong with this page" or "how's my SEO." After the table is produced, the user will refer back to findings by their ID number (e.g. "let's fix #3", "tell me more about #6") — keep the ID-to-finding mapping in mind for the rest of the conversation. --- # SEO Website Audit Audits a single webpage's SEO signals using `web_fetch`, `web_search`, and Google's PageSpeed Insights API, then returns a numbered table of fixes ranked by severity and effect so the user can act on findings by ID (e.g. "let's do #1"). ## Triggers Use for: "SEO audit", "SEO review", "SEO analysis", "audit my site/page", "what's wrong with this page SEO-wise", "how do I improve my rankings", or a bare URL with "how's my SEO?". Don't use for: backlink audits, keyword rank tracking, competitor gap analysis, or content/keyword research with no specific page to audit — this skill only covers what's observable on the page itself (technical, on-page, content, and performance signals). There's no dedicated skill for those yet; say so and offer to do what overlaps (e.g. on-page content review) instead. ## Requirements - Tools: `web_fetch`, `web_search` (built-in, no MCP needed) - Optional: reachable network access to `googleapis.com` for PageSpeed Insights — the audit degrades gracefully and continues without performance data if this isn't reachable - Input: a single page URL. Default scope is one page; only crawl multiple pages if the user explicitly asks, in which case repeat the whole workflow per page ## Steps 1. **Confirm the target** — if no URL is given, ask for one. Default to auditing exactly the URL provided (usually the homepage), not the whole site. 2. **Fetch the page** — call `web_fetch` on the exact URL. This surfaces title, headings, links, images (with alt text where present), and body copy. It does *not* reliably surface raw `` meta tags (meta description, robots meta, canonical, OG/Twitter tags) — when you can't confirm something, mark it "not verified" rather than guessing. - Don't construct guessed URLs like `domain.com/robots.txt` and fetch them directly — the fetch tool rejects URLs that weren't provided or returned by a search. Instead, use `web_search` (e.g. `"[domain] robots.txt"`) to try to surface these, then fetch whatever URL the search actually returns. 3. **Check performance** — call `web_fetch` on: `https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=&category=performance&category=seo&category=accessibility&category=best-practices` Pull out Performance score, LCP, CLS, INP/TBT, and flagged audits. If it fails, note that performance data wasn't available and continue — don't block the rest of the audit. 4. **Run the checklist** — work through the **SEO Audit Checklist** at the bottom of this file, which covers indexability/crawlability, title/meta tags, heading structure, content quality, image optimization, internal linking, structured data, mobile/UX, and social metadata, along with how to judge severity and effect for each. Read it fresh; don't reconstruct it from memory. 5. **Score and rank** — for every issue found, assign Severity (`Critical`/`High`/`Medium`/`Low` — how broken the current state is) and Effect (`High`/`Medium`/`Low` — how much fixing it would help). Compute priority using this grid and sort descending: | | Effect: High | Effect: Medium | Effect: Low | |---|---|---|---| | **Severity: Critical** | 6 | 5 | 4 | | **Severity: High** | 5 | 4 | 3 | | **Severity: Medium** | 4 | 3 | 2 | | **Severity: Low** | 3 | 2 | 1 | Ties break by severity first, then by how quick/cheap the fix is if known. Only include things that are actually wrong — mention passing checks briefly in prose, not in the table. ## Output 2-3 sentences of summary first (page type, biggest-picture takeaway), then a table, numbered from 1 with highest priority first: ``` | ID | Severity | Effect | Issue | Recommendation | |----|----------|--------|-------|-----------------| | 1 | Critical | High | Page has no tag | Add a unique, descriptive title (~50-60 chars) reflecting the page's main topic | | 2 | High | High | No H1 on the page | Add a single H1 matching the page's primary topic/keyword | ``` Keep this conversational, not a file/artifact — the user replies "let's do #1" right after. Keep numbering stable for the rest of the conversation even if rows get resolved or dropped; just note a row is handled rather than renumbering. If the user later asks about a specific ID, give a fuller explanation: why it matters, exactly how to fix it (with markup/code examples), and how to verify the fix worked. ## Edge cases - **Meta tags not visible in fetched content** — mark the check "not verified", don't assume pass or fail. - **robots.txt / sitemap not fetchable directly** — search for them instead of guessing the URL; if search doesn't surface them, mark related checks "not verified." - **PageSpeed Insights unreachable** — skip the performance section's findings, mention once in the summary, don't fabricate numbers. - **Multi-page request** — repeat the full workflow per page; either produce one table per page or one combined table with a "Page" column, whichever the user prefers. - **Never fabricate data** — only report what `web_fetch`/`web_search`/PageSpeed actually returned. --- # SEO Audit Checklist Work through each section for the fetched page. For every item that fails or is suboptimal, create a finding with a Severity and Effect rating (see the scoring grid in Step 5 above). Skip items you genuinely cannot verify from the fetched content — flag them as "not verified" rather than guessing. ## 1. Indexability & crawlability (usually the highest-severity category) - **Robots meta / X-Robots-Tag**: Is the page accidentally set to `noindex` or `nofollow`? → If yes: **Critical severity, High effect** (nothing else matters if the page can't be indexed). - **Robots.txt**: Does robots.txt block this URL or the section it's in? (search for it, don't guess the URL) - **Canonical tag**: Present? Self-referencing or pointing elsewhere unexpectedly? A wrong canonical pointing to a different URL is Critical/High. - **HTTP status**: Confirm the page actually returned 200 (a fetch that redirected repeatedly or errored is itself a finding). - **HTTPS**: Is the page served over HTTPS? Any mixed-content resources loaded over HTTP? - **Sitemap**: Can you confirm the page is included in an XML sitemap? (search, don't guess URL) ## 2. Title tag & meta description - **Title tag**: Present, unique, and descriptive? Ideal length ~50-60 characters (roughly under 580px). Missing title = Critical/High. Generic/duplicate-sounding title (e.g. just the brand name with no context) = Medium/Medium. - **Primary keyword placement**: Does the title reflect what the page is actually about / what a user would search for? - **Meta description**: Present, unique, compelling, roughly 120-160 characters? Missing isn't as severe as a missing title (Google will auto-generate one) — usually Medium/Medium. ## 3. Heading structure - **Single H1**: Exactly one H1 that describes the page's main topic? Zero H1s or multiple competing H1s = Medium-High severity, Medium effect. - **Logical hierarchy**: Do H2s/H3s nest sensibly under the H1, or does the page skip levels / use headings just for styling? - **Keyword relevance**: Do headings reflect the topics a user searching for this page would expect to see? ## 4. Content quality - **Depth/uniqueness**: Is there enough substantive, unique content to satisfy search intent, or is it thin (e.g. a few sentences padded with images)? Thin content on a page meant to rank competitively = High severity, High effect. - **Search intent match**: Does the content actually answer what someone searching for this topic wants (informational vs. transactional vs. navigational)? - **Readability**: Overly long unbroken paragraphs, no subheadings/lists breaking up content for scannability. - **Freshness signals**: For time-sensitive content, any visible dates that look stale? - **Keyword cannibalization risk**: Only flag this if you have visibility into other pages on the site (e.g. from internal links) that appear to target the same query. ## 5. Image optimization - **Alt text**: Missing alt text on meaningful/content images (not decorative ones) — Medium severity, Low-Medium effect (accessibility + image search). - **File names**: Generic names like `IMG_2931.jpg` vs. descriptive ones (minor, Low/Low). - **Oversized images**: Note if PageSpeed Insights flags unoptimized/oversized images — fold this into the performance section instead of double-counting. ## 6. Internal linking & site structure - **Internal links from this page**: Does the page link to other relevant pages with descriptive (not "click here") anchor text? - **Orphan risk**: Based on what you can see, does this page look reachable from clear navigation, or does it seem buried? - **Broken links**: Any internal/external links visibly pointing to obviously broken or placeholder URLs in the fetched content? ## 7. Structured data (Schema.org) - Only assess this if you can actually detect structured data in the fetched content (e.g. it surfaces in extracted markup/metadata) — otherwise mark as not verified rather than assuming absence. - If detectable and missing for an obviously schema-eligible page type (product, article, FAQ, local business, recipe, event) — Medium severity, Medium-High effect (rich results/CTR). - If present, check for obvious mismatches (e.g. schema type doesn't match page content). ## 8. Mobile & UX signals - Viewport meta tag present? Missing = High severity (mobile-first indexing), Medium-High effect. - Any obvious intrusive interstitials/pop-ups visible in the fetched content that would block content on mobile. ## 9. Performance / Core Web Vitals (from PageSpeed Insights, if available) - **LCP (Largest Contentful Paint)**: >4s = High severity; 2.5-4s = Medium; <2.5s = pass. - **CLS (Cumulative Layout Shift)**: >0.25 = High severity; 0.1-0.25 = Medium; <0.1 = pass. - **INP/TBT**: Flag if PageSpeed reports this as poor. - **Overall Performance score** under ~50 = High severity, Medium-High effect; 50-89 = Medium; 90+ = pass. - If PageSpeed Insights wasn't reachable, say so once in the summary rather than per-item, and skip this section's findings rather than fabricating numbers. ## 10. Social/sharing metadata (lower priority, usually Low/Low) - Open Graph and Twitter Card tags for title/description/image, only if visible in fetched content. Missing is typically Low severity, Low-Medium effect (affects share appearance, not rankings directly). --- ## Severity quick reference - **Critical**: page can't be indexed, or a core discoverability mechanism is broken/misconfigured. - **High**: significantly undermines rankings or usability for most visitors (missing title, thin content on a key page, failing Core Web Vitals, no mobile viewport). - **Medium**: a real gap best practice would fix, but the page still basically works and can rank. - **Low**: polish — worth doing, low downside if left alone. ## Effect quick reference - **High**: directly tied to ranking factors or indexability at scale. - **Medium**: helps CTR, secondary ranking signals, or user experience meaningfully. - **Low**: marginal, cosmetic, or affects a narrow slice of traffic/use cases.