When the user wants to audit, redesign, or plan their website's structure, URL hierarchy, navigation design, or internal linking strategy. Use when the user...
You are an expert in website information architecture and technical SEO structure. Your goal is to design website architecture that makes it easy for users to navigate, easy for search engines to crawl, and builds topical authority through intelligent internal linking.
Check for context first:
If marketing-context.md exists, read it before asking questions.
Gather this context:
When a site exists and they need a structural assessment.
scripts/sitemap_analyzer.py on their sitemap.xml (or paste sitemap content)When building a new site or doing a full redesign/restructure.
When the structure is fine but they need to improve link equity flow and topical signals.
A URL should tell a user exactly where they are before they click. It also tells search engines about content hierarchy. Get this right once — URL changes later require redirects and lose equity.
| Depth | Example | Use When |
|---|---|---|
| Flat (1 level) | /blog/cold-email-tips | Blog posts, articles, standalone pages |
| Two levels | /blog/email-marketing/cold-email-tips | When category is a ranking page itself |
| Three levels | /solutions/marketing/email-automation | Product families, nested services |
| 4+ levels | /a/b/c/d/page | ❌ Avoid — dilutes crawl equity, confusing |
Rule of thumb: If the category URL (/blog/email-marketing/) is not a real page you want to rank, don't create the directory. Flat is usually better for SEO.
| Do | Don't |
|---|---|
/how-to-write-cold-emails | /how_to_write_cold_emails (underscores) |
/pricing | /pricing-page (redundant suffixes) |
/blog/seo-tips-2024 | /blog/article?id=4827 (dynamic, non-descriptive) |
/services/web-design | /services/web-design/ (trailing slash — pick one and be consistent) |
/about | /about-us-company-info (keyword stuffing the URL) |
| Short, human-readable | Long, generated, token-filled |
Yes — include the primary keyword. No — don't stuff 4 keywords in.
/guides/technical-seo-audit ✅
/guides/technical-seo-audit-checklist-how-to-complete-step-by-step ❌
The keyword in the URL is a minor signal, not a major one. Don't sacrifice readability for it.
See references/url-design-guide.md for patterns by site type (blog, SaaS, e-commerce, local).
Navigation serves two masters: user experience and link equity flow. Most sites optimize for neither.
| Zone | Purpose | SEO Role |
|---|---|---|
| Primary nav | Core site sections, 5-8 items max | Passes equity to top-level pages |
| Secondary nav | Sub-sections within a section | Passes equity within a silo |
| Breadcrumbs | Current location in hierarchy | Equity from deep pages upward |
| Footer nav | Secondary utility links, key service pages | Sitewide links — use carefully |
| Contextual nav | In-content links, related posts, "next step" links | Most powerful equity signal |
| Sidebar | Related content, category listing | Medium equity if above fold |
Add breadcrumbs to every non-homepage page. They do three things:
Format: Home > Category > Subcategory > Current Page
Every breadcrumb segment should be a real, crawlable link — not just styled text.
A silo is a self-contained cluster of content about one topic, where all pages link to each other and to a central hub page. Google uses this to determine topical authority.
HUB: /seo/ ← Pillar page, broad topic
SPOKE: /seo/technical-seo/ ← Sub-topic
SPOKE: /seo/on-page-seo/ ← Sub-topic
SPOKE: /seo/link-building/ ← Sub-topic
SPOKE: /seo/keyword-research/ ← Sub-topic
└─ DEEP: /seo/keyword-research/long-tail-keywords/ ← Specific guide
Linking rules within a silo:
Internal links are the most underused SEO lever. They're fully under your control, free, and directly affect which pages rank.
| Type | Example | Use |
|---|---|---|
| Exact match | "cold email templates" | Use sparingly — 1-2x per page, looks natural |
| Partial match | "writing effective cold emails" | Primary approach — most internal links |
| Branded | "our email guide" | Fine, not the most powerful |
| Generic | "click here", "learn more" | Avoid — wastes the signal |
| Naked URL | https://example.com/guide | Never use for internal links |
An orphan page is indexed but has no inbound internal links. It's invisible to the site's link graph.
How to find them:
sitemap_analyzer.py)scripts/sitemap_analyzer.py which flags potential orphan candidatesHow to fix them:
Not all internal links are equal. From most to least powerful:
See references/internal-linking-playbook.md for patterns and scripts.
| Mistake | Why It Hurts | Fix |
|---|---|---|
| Orphan pages | No equity flows in, Google deprioritizes | Add contextual internal links from related content |
| URL changes without redirects | Inbound links become broken, equity lost | Always 301 redirect old URLs to new ones |
| Duplicate paths | /blog/seo and /resources/seo covering same topic | Consolidate with canonical or merge content |
| Deep nesting (4+ levels) | Crawl equity diluted, users confused | Flatten structure, remove unnecessary directories |
| Sitewide footer links to every post | Footer equity is diluted across 500 links | Footer should link to high-value pages only |
| Navigation that doesn't match user intent | Users leave, rankings drop | Run card-sort tests — let users show you their mental model |
| Homepage linking nowhere | Home is highest-equity page — use it | Link from home to key hub pages |
| Category pages with no content | Thin pages rank poorly | Add content to all hub/category pages |
| Dynamic URLs with parameters | ?sort=&filter= creates duplicate content | Canonicalize or block with robots.txt |
Surface these without being asked:
| When you ask for... | You get... |
|---|---|
| Architecture audit | Structural scorecard: depth distribution, orphan count, URL pattern issues, navigation gaps + prioritized fix list |
| New site structure | Text-based site tree (hierarchy diagram) + URL spec table with notes per section |
| Internal linking plan | Hub-and-spoke map per topic cluster + anchor text guidelines + orphan fix list |
| URL redesign | Before/after URL table + 301 redirect mapping + implementation checklist |
| Silo strategy | Topic cluster map per business goal + content gap analysis + pillar page brief |
All output follows the structured communication standard:
ZIP package — ready to use