SEO Audit & Fix

Announce:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SEO Analysis starting.
Parsing parameters...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Parameters

This skill expects: /seo <url> [mode]

• url — the site to audit (e.g. https://psquared.dev, https://inboxmate.psquared.dev)
• mode — audit (default) or fix
  • audit — analyze and report findings, don't touch any files
  • fix — analyze, report, AND apply fixes directly to source files

If no URL is provided, ask the user.

---

Site Registry

When the URL matches a known psquared site, use the local source files for the fix mode:

Domain	Source path (relative to psquared-websites)	Framework
psquared.dev / www.psquared.dev	apps/psquared/	Nuxt 3
inboxmate.psquared.dev	apps/inboxmate/	Static HTML
ki-linz.at / www.ki-linz.at	apps/ki-linz/	Astro 5
agenthub.psquared.dev	apps/agenthub/	Static HTML

The monorepo lives at /Users/martinpammesberger/Documents/psquared/psquared-websites/.

For unknown URLs, only audit mode is available (no local source to fix).

---

STEP 0 — Discover Pages

Announce: Discovering pages for [domain]...

0a — Fetch robots.txt

WebFetch: [url]/robots.txt

Record:

• Does it exist?
• Are there Disallow rules? List them.
• Is there a Sitemap: directive?
• Are important paths accidentally blocked?

0b — Fetch sitemap

Try in order:

1. URL from robots.txt Sitemap: directive
2. [url]/sitemap.xml
3. [url]/sitemap-index.xml
4. [url]/sitemap_index.xml

If a sitemap is found, extract all page URLs. If not, fall back to crawling:

• Fetch the homepage
• Extract all internal links (same domain)
• Follow one level deep to discover subpages

Announce: Found [N] pages to analyze.

Limit: Analyze a maximum of 30 pages per site. If more are found, prioritize: homepage, main navigation pages, then remaining by URL depth.

---

STEP 1 — Analyze Each Page

Announce: [1/N] Analyzing [page URL]...

For each discovered page, use WebFetch to fetch the HTML, then check all categories below.

1a — Meta Tags

Check	What to look for	Severity
<title>	Present, 30-60 chars, unique across site, contains relevant keywords	HIGH
<meta name="description">	Present, 120-160 chars, unique across site, compelling	HIGH
<link rel="canonical">	Present, points to correct URL (no trailing slash mismatch, no http/https mismatch)	HIGH
<meta property="og:title">	Present, matches or supplements <title>	MEDIUM
<meta property="og:description">	Present, matches or supplements meta description	MEDIUM
<meta property="og:image">	Present, valid URL, image exists	MEDIUM
<meta property="og:url">	Present, matches canonical	MEDIUM
<meta property="og:type">	Present (website, article, etc.)	LOW
<meta name="twitter:card">	Present (summary_large_image preferred)	LOW
<meta name="twitter:title">	Present	LOW
<meta name="twitter:description">	Present	LOW
<meta name="viewport">	Present with width=device-width	HIGH

1b — Heading Hierarchy

Check	What to look for	Severity
Single H1	Exactly one <h1> per page	HIGH
H1 content	Contains primary keyword, descriptive, not just a logo	HIGH
Heading order	No skipped levels (H1 -> H3 without H2)	MEDIUM
Heading keywords	Headings include relevant terms for the page topic	LOW

1c — Images

Check	What to look for	Severity
Alt text	All <img> tags have non-empty alt attribute	HIGH
Alt quality	Alt text is descriptive, not just "image" or filename	MEDIUM
Lazy loading	Images below fold use loading="lazy"	LOW
Width/height	Images specify dimensions (prevents CLS)	LOW

1d — Structured Data (JSON-LD)

Look for <script type="application/ld+json"> blocks.

Check	What to look for	Severity
Presence	At least one JSON-LD block on homepage	HIGH
Valid JSON	Block parses without errors	HIGH
@type appropriate	Organization/LocalBusiness for homepage, Article for blog posts, Product for product pages, FAQPage for FAQ sections	MEDIUM
Required fields	Each schema type has its required properties populated	MEDIUM
Contact info	Organization schema includes url, name, contactPoint or email	LOW

Recommended schema types per page:

Page type	Schema
Homepage	Organization or LocalBusiness
Blog post	Article with author, datePublished, headline
Product/service page	Product or Service
FAQ section	FAQPage with Question + Answer items
Contact page	LocalBusiness with address, telephone

1e — Internal Links & Navigation

Check	What to look for	Severity
Broken links	Internal links that return 404 (sample up to 10 per page)	HIGH
Link text	Descriptive anchor text, not "click here" or "read more"	MEDIUM
Orphan pages	Pages not linked from any other page	MEDIUM
Navigation consistency	Main nav present on all pages	LOW

1f — i18n & Hreflang

Check	What to look for	Severity
<html lang>	Present and correct	HIGH
Hreflang tags	<link rel="alternate" hreflang="x"> for each language variant	HIGH (if multilingual)
Self-referencing hreflang	Each page includes hreflang pointing to itself	MEDIUM
x-default	hreflang="x-default" present	MEDIUM
Consistency	Hreflang tags are reciprocal (page A points to B, B points back to A)	HIGH

Skip i18n checks for sites that are clearly single-language only.

1g — Technical SEO

Check	What to look for	Severity
HTTPS	Site uses HTTPS	HIGH
Mobile viewport	Viewport meta tag present	HIGH
Charset	<meta charset="utf-8"> present	MEDIUM
Favicon	<link rel="icon"> present	LOW
CSS/JS blocking	Critical CSS inline or preloaded	LOW
404 page	/404 or similar returns custom page (not default server error)	LOW

1h — Content Quality

Check	What to look for	Severity
Thin content	Page has < 300 words of visible text (excluding nav/footer)	MEDIUM
Duplicate titles	Same <title> used on multiple pages	HIGH
Duplicate descriptions	Same meta description on multiple pages	HIGH
Text/HTML ratio	Very low text-to-markup ratio	LOW

1i — AI & GEO Readiness

Check	What to look for	Severity
llms.txt	[url]/llms.txt exists with site summary for AI crawlers	LOW
Structured answers	Content has clear Q&A patterns, definition lists, or summary paragraphs that AI can extract	LOW
Content accessibility	Key information in HTML text (not trapped in images/JS-only renders)	MEDIUM

1j — Security Headers (SEO-adjacent)

Check	What to look for	Severity
X-Frame-Options	Present in response headers	LOW
X-Content-Type-Options	nosniff	LOW
Referrer-Policy	Present	LOW
HTTPS redirect	HTTP redirects to HTTPS	MEDIUM

Fetch headers via WebFetch response. If headers aren't accessible, skip this section.

---

STEP 2 — Score & Compile

Announce: Analysis complete. Compiling results...

2a — Per-Page Scores

For each page, count findings by severity:

Grade	Criteria
A	0 HIGH issues, max 2 MEDIUM
B	0 HIGH issues, 3+ MEDIUM
C	1-2 HIGH issues
D	3-4 HIGH issues
F	5+ HIGH issues

2b — Site-Wide Score

Average the per-page grades. Also flag site-wide issues:

• Missing robots.txt or sitemap → HIGH
• No structured data on any page → HIGH
• No hreflang on multilingual site → HIGH
• Duplicate titles/descriptions across pages → HIGH

2c — Priority Ranking

Rank all findings by impact:

1. Critical — blocks indexing or causes major SEO harm (missing title, blocked in robots.txt, broken canonical)
2. Important — significant improvement potential (missing OG tags, no structured data, duplicate descriptions)
3. Nice to have — polish items (alt text quality, llms.txt, security headers)

---

STEP 3 — Report (audit mode)

Announce:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SEO Audit Complete: [domain]

Overall Grade: [A-F]
Pages analyzed: [N]

Critical: [N] issues
Important: [N] issues
Nice to have: [N] issues
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Then output a detailed report with:

Site Overview

Item	Status
robots.txt	Present / Missing
sitemap.xml	Present ([N] URLs) / Missing
Structured data	Present on [N]/[total] pages / Missing
Hreflang	Correct / Issues / N/A
HTTPS	Yes / No

Page-by-Page Results

For each page (sorted worst to best):

[Page URL] — Grade: [X]

Issue	Severity	Details
Missing meta description	HIGH	No <meta name="description"> found
...	...	...

Top Priorities

Numbered list of the top 10 most impactful fixes, ordered by effort-to-impact ratio.

---

STEP 4 — Fix (fix mode only)

Skip this step entirely if mode is audit.

Announce: Applying fixes to source files in [source path]...

If the URL matches a site in the Site Registry, locate the source files and apply fixes.

Framework-specific fix strategies

Nuxt 3 (apps/psquared/)

Fix target	Where to edit
Global meta tags	nuxt.config.js → app.head
Per-page meta	pages/*.vue → useHead() or useSeoMeta() composable
OG image	public/ directory + meta tag reference
Structured data	nuxt.config.js → app.head.script with type: 'application/ld+json', or per-page useHead()
Sitemap config	nuxt.config.js → @nuxtjs/sitemap module config
robots.txt	public/robots.txt or nuxt.config.js → @nuxtjs/robots module

Read the existing nuxt.config.js and relevant page files before making any edits. Follow existing patterns.

Astro 5 (apps/ki-linz/)

Fix target	Where to edit
Global meta tags	src/layouts/*.astro → <head> section
Per-page meta	Page frontmatter + <head> in layout
Structured data	Inline <script type="application/ld+json"> in layout or page
Sitemap config	astro.config.mjs → @astrojs/sitemap integration
robots.txt	public/robots.txt

Static HTML (apps/inboxmate/, apps/agenthub/)

Fix target	Where to edit
Meta tags	Directly in <head> of each .html file
Structured data	Add <script type="application/ld+json"> block in <head>
robots.txt	Create robots.txt in the app root
Sitemap	Create sitemap.xml in the app root

Fix rules

• Read before writing. Always read the full file before editing. Follow existing code patterns and style.
• One fix at a time. Apply each fix individually using the Edit tool.
• Don't break things. If a fix requires understanding complex component logic, flag it in the report instead of guessing.
• Don't over-optimize. Fix real issues found in the audit. Don't add things that weren't flagged.
• Preserve existing good SEO. If something is already correct, don't touch it.
• Track what you changed. Keep a list of every file edited and what was changed.

After fixing

Announce:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SEO Fixes Applied: [domain]

Overall Grade: [before] → [after]

Fixed:
  - [file]: [what was changed]
  - [file]: [what was changed]

Remaining (manual fix needed):
  - [issue]: [why it couldn't be auto-fixed]

Run `/seo [url] audit` to verify.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━