When the user wants to audit, review, or diagnose SEO issues, plan site architecture, or implement schema markup. Use when someone says 'SEO audit', 'technical SEO', 'site architecture', 'schema markup', 'internal linking', 'why isn't my site ranking', 'site health check', 'crawl issues', 'fix my SEO', 'my traffic dropped', 'rankings fell', or 'site not ranking'. Also trigger when someone wants to plan URL structure, design navigation, add structured data, or review any website for search performance. Three modes: Full Audit (comprehensive health check), Architecture (URL structure and internal linking), Schema (JSON-LD structured data). Covers crawlability, indexation, Core Web Vitals, and on-page factors.
When the user wants to audit, review, or diagnose SEO issues, plan site architecture, or implement schema markup. Use when someone says 'SEO audit', 'technical SEO', 'site architecture', 'schema markup', 'internal linking', 'why isn't my site ranking', 'site health check', 'crawl issues', 'fix my SEO', 'my traffic dropped', 'rankings fell', or 'site not ranking'. Also trigger when someone wants to plan URL structure, design navigation, add structured data, or review any website for search performance. Three modes: Full Audit (comprehensive health check), Architecture (URL structure and internal linking), Schema (JSON-LD structured data). Covers crawlability, indexation, Core Web Vitals, and on-page factors.
Determine which mode applies based on user request. If ambiguous, confirm before proceeding.
Ask only for information not already available from brand files.
Brand Integration
keyword-plan.md → Audit priorities align with target keywords. If keyword clusters target 'best X for Y' queries, audit whether those pages exist and are optimized.
voice-profile.md → Meta descriptions and title tags should reflect brand voice. Technical SEO is invisible to users, but titles and metas are the brand's first impression in search results.
Mode: Audit (Default)
Initial Assessment
Before auditing, understand:
— What type of site? Primary business goal for SEO? Priority keywords/topics?
Site Context
Current State — Known issues? Current organic traffic level? Recent changes or migrations?
Scope — Full site audit or specific pages? Technical + on-page, or one focus area?
Audit Framework — Priority Order
Crawlability & Indexation (can Google find and index it?)
Technical Foundations (is the site fast and functional?)
On-Page Optimization (is content optimized?)
Content Quality (does it deserve to rank?)
Authority & Links (does it have credibility?)
Schema Markup Detection Limitation
web_fetch and curl cannot reliably detect structured data / schema markup. Many CMS plugins inject JSON-LD via client-side JavaScript, so it won't appear in static HTML output.
To accurately check for schema markup:
Browser tool — render the page and run: document.querySelectorAll('script[type="application/ld+json"]')
Noindex tags on important pages, canonicals pointing wrong direction
Redirect chains/loops, soft 404s, duplicate content without canonicals
HTTP/HTTPS and www/non-www consistency, trailing slash consistency
Site Speed & Core Web Vitals
LCP < 2.5s, INP < 200ms, CLS < 0.1
Server response time, image optimization, JS execution, CSS delivery, caching, CDN, fonts
Mobile-Friendliness
Responsive design, tap targets, viewport, no horizontal scroll, mobile-first indexing readiness
Security
HTTPS everywhere, valid SSL, no mixed content, HSTS header
On-Page SEO Audit
Title Tags — Unique per page, primary keyword near beginning, 50-60 chars, compelling
Meta Descriptions — Unique per page, 150-160 chars, includes keyword, CTA
Heading Structure — One H1 per page with keyword, logical H1-H2-H3 hierarchy
Content — Keyword in first 100 words, sufficient depth, answers search intent, better than competitors
Images — Descriptive file names, alt text, compressed, WebP format, lazy loading
Internal Linking — Important pages well-linked, descriptive anchor text, no broken links
Content Quality — E-E-A-T
Experience: First-hand experience, original insights/data
Expertise: Author credentials, accurate detailed information
Authoritativeness: Recognized in space, cited by others
Trustworthiness: Accurate info, transparent business, contact info, privacy policy, HTTPS
Common Issues by Site Type
Site Type
Watch For
SaaS
Thin product pages, blog not linked to product, missing comparison pages
E-commerce
Thin category pages, duplicate descriptions, faceted nav duplicates
Content/Blog
Outdated content, keyword cannibalization, no topical clustering
Local Business
Inconsistent NAP, missing local schema, no location pages
Save the audit report to marketing/seo/audit-report.md. For Architecture mode, save to marketing/seo/site-architecture.md. For Schema mode, save to marketing/seo/schema-implementation.md.
Mode: Architecture
Plan website structure including page hierarchy, navigation, URL patterns, and internal linking.
Context Gathering
Business: What does the company do? Who are the audiences? Top 3 site goals?
Current State: New site or restructuring? What's broken? URLs to preserve?
Site Type: SaaS, content/blog, e-commerce, docs, hybrid, small business?
Scale: How many pages exist or planned? Most important pages?
Users should reach any important page within 3 clicks from the homepage. Go as flat as possible while keeping navigation clean. If a nav dropdown has 20+ items, add a level of hierarchy.
URL Design Principles
Readable by humans — /features/analytics not /f/a123
Hyphens, not underscores — /blog/seo-guide not /blog/seo_guide
Reflect hierarchy — URL path matches site structure
Consistent trailing slash — pick one and enforce
Lowercase always
Short but descriptive
Navigation Design
Nav Type
Purpose
Rules
Header
Primary navigation
4-7 items max, CTA rightmost, logo links to home
Footer
Secondary links, legal
Organize into 3-5 themed columns
Sidebar
Section navigation (docs, blog)
Collapsible, search at top, sticky on scroll
Breadcrumbs
Current location in hierarchy
Mirror URL path, all segments linked except current
Internal Linking Strategy
Type
Purpose
Navigational
Move between sections (header, footer, sidebar)
Contextual
Related content within text
Hub-and-spoke
Connect cluster content to pillar page
Cross-section
Connect related pages across sections
Rules: No orphan pages. Descriptive anchor text. 5-10 internal links per 1000 words. Link to important pages more often. Use breadcrumbs.
Architecture Output
Deliver these artifacts:
Page Hierarchy (ASCII tree with URLs)
Visual Sitemap (Mermaid diagram with nav zones)
URL Map Table (page, URL, parent, nav location, priority)
// Full JSON-LD code block ready to paste{"@context":"https://schema.org","@type":"...",// Complete markup}
Testing checklist:
Validates in Rich Results Test
No errors or warnings
Matches page content
All required properties included
Tools
Free — Google Search Console, PageSpeed Insights, Rich Results Test, Schema Validator, Bing Webmaster Tools
Paid (if available) — Screaming Frog, Sitebulb
For research — Use Exa MCP or web search for competitive analysis
If Web Search Is Unavailable
Proceed with all technical audits (crawlability, indexation, site speed, on-page SEO, schema detection) — these don't require web search. Skip competitive benchmarking and SERP position analysis. Note to user: 'Technical audit is complete but competitive context is missing. Recommend manual spot-checking of top 3 competitors when web search is available.'
Scope before you audit. A 10,000-page audit helps no one — the user needs actionable findings, not a catalog. Prioritize revenue-driving pages, high-traffic pages, and pages that recently dropped. Ask about scope if it's unclear.
Every finding needs evidence. "Title tags need improvement" is useless. Show the specific title, explain what's wrong, and provide the exact fix. Findings without evidence feel like guesswork and get ignored.
Match tool recommendations to the user's stack. Check brand/stack.md before suggesting Screaming Frog or Sitebulb — recommending paid tools the user doesn't have wastes their time and yours.
Audit and Architecture are different modes for a reason. Audit diagnoses what's wrong with existing pages. Architecture plans new structure. If someone asks for an audit, don't redesign their site. If the audit reveals structural issues, suggest switching to Architecture mode.
Prioritization is the deliverable, not the findings. A list of 50 findings without priority is overwhelming and leads to paralysis. Rank by impact and effort — the user should know what to fix first, second, and third.
Error States
Site unreachable / no URL provided: Ask for the site URL. If site is down, note limitation and audit what's possible from cached/provided content.
No brand files exist: Proceed with audit using default assumptions. Note: "No brand context loaded — audit is based on general SEO best practices. Run /brand-voice and /keyword-research for targeted recommendations."
Web search unavailable: Complete technical audit (crawlability, indexation, speed, on-page, schema). Skip competitive benchmarking and SERP position analysis. Note limitation.
Can't access site programmatically: Rely on user-provided screenshots, HTML, or descriptions. Note which checks require live access.
Scope ambiguous: Confirm with user before proceeding: "Full site audit, specific pages, or a focus area (technical / on-page / content)?"
Chain Offers
After completing, suggest based on findings:
/seo-content — for content gaps found during audit (missing pages, thin content)
/ai-seo — if site lacks AI search visibility
/keyword-research — if audit reveals no keyword strategy
/page-cro — if pages rank but don't convert
/competitor-alternatives — if missing comparison/alternatives pages competitors have
Related Skills
ai-seo: AI search optimization (AEO, GEO, LLMO)
seo-content: Content creation optimized for search (use Scale mode for programmatic SEO)
page-cro: Optimizing pages for conversion, not just ranking
keyword-research: Finding and prioritizing keyword targets
