AC
SEO & AEO4.8 KBMIT licensed

site-architecture

Rewritten from patterns in an open SaaS marketing skills pack (MIT)

Plan or restructure a website's page hierarchy, navigation, URL structure, and internal linking. Use when the user says "sitemap", "site structure", "information architecture", "navigation design", "URL structure", "what pages do I need", or "how should I organize my site". Not for XML sitemaps or indexation problems: use seo-audit. Not for structured data markup: use schema. Not for deciding what content to create: use content-strategy.

  • site
  • architecture

SKILL.md

Site Architecture

Good architecture means a user reaches any important page in three clicks and a crawler infers the hierarchy from the URL alone. Plan structure before content, and never change a URL without a redirect.

Intake

If a product marketing context file exists (.agents/product-marketing.md or .claude/product-marketing.md), read it first. Then confirm: what the company does and for whom, top 3 site goals, new build or restructure (and what is broken), site type, page count now and planned, the 5 most important pages, and any URLs that must survive with redirects.

Workflow

  1. Pick the depth for the site type. Small business: 1-2 levels. SaaS and content sites: 2-3. E-commerce and docs: 3-4. Go as flat as possible while nav stays clean; a dropdown with 20+ items needs a new level. Read references/structure-templates.md for full page hierarchies, URL patterns, and Mermaid sitemap templates per site type.
  2. Draft the hierarchy. L0 homepage, L1 primary sections (/features, /pricing, /blog), L2 section pages, L3+ detail pages. Output as an ASCII tree with the URL at every node.
  3. Design navigation. Header: 4-7 items max, ordered by priority, CTA rightmost, logo links home. Footer: grouped columns (Product, Resources, Company, Legal). Sidebar for docs and blog sections. Breadcrumbs mirror the URL path, every segment clickable except the current page.
  4. Set URL rules. Human-readable, lowercase, hyphens, hierarchy reflected in the path, one trailing-slash policy, short but descriptive slugs, no dates, no IDs, no query params for content. One parent per concept: never mix /features/x and /product/y.
  5. Plan internal linking. No orphans (every page gets at least one inbound link), descriptive anchors, most links to the most important pages, hub-and-spoke for content clusters (hub links all spokes, spokes link back and to each other), related-content blocks on posts, cross-section links from features to case studies.
  6. Deliver the plan. Five artifacts: ASCII tree, Mermaid visual sitemap, URL map table (page, URL, parent, nav location, priority), navigation spec, internal linking plan with redirect map if restructuring.

Verification

For a restructure, build the redirect map first, then check it: every old URL appears exactly once on the left side and maps to a live new URL. Spot-check with curl -sI https://<DOMAIN>/<old-path> after launch. Expect a single 301 hop to the new URL and a 200 at the target. A chain or a 404 means the map is incomplete: fix before calling the migration done.

For a new plan, walk the tree: every important page reachable in 3 clicks from home, every page has a parent, every URL matches its breadcrumb trail. Any mismatch means the hierarchy and URL design diverged: reconcile them.

Good vs Bad

Bad: Blog URLs move from /blog/2023/05/post-title to /blog/post-title with no redirect map, because "Google will figure it out". Every backlink now hits a 404 and rankings drop for weeks.

Good: Same migration ships with a one-to-one 301 map, the top 20 linked URLs verified by hand, and the XML sitemap regenerated on launch day.

Footguns

  • URL changes without 301s. Lost link equity and broken bookmarks. Fix: one mapped redirect per renamed URL, no exceptions.
  • Hierarchy that exists only in nav. URL says /analytics, breadcrumb says Home > Features > Analytics. Crawlers and users get conflicting maps. Fix: URL path, breadcrumb, and tree must agree.
  • Over-nesting. /products/category/subcategory/item/detail buries pages and bloats URLs. Fix: flatten until each level earns its place.
  • Orphan pages after restructure. Pages kept but unlinked from anywhere. Fix: run the orphan audit in the linking plan; every kept page gets an inbound link.

Completion Checklist

  • [ ] Hierarchy drafted with URLs at every node, important pages within 3 clicks
  • [ ] Header capped at 7 items with CTA, footer grouped, breadcrumbs mirror URLs
  • [ ] URL rules consistent: lowercase, hyphens, one parent per concept, no dates or IDs
  • [ ] Internal linking plan covers hubs, spokes, and orphan elimination
  • [ ] Restructures ship a verified one-to-one 301 map

Any box unchecked: not done. Fix or say so.

Reference files

More in SEO & AEO

ai-seoOptimize content to be cited by AI search engines and assistants (AI Overviews, ChatGPT, Perplexity, Claude, Gemini, Cop...claude-seoSEO analysis orchestrator, routes audits to the right specialist skill and merges results into one scored report. Use wh...claude-seo-backlinksBacklink profile analysis: referring domains, anchor text distribution, toxic link detection, competitor link gap. Use w...
All skills