Skip to main content
skill CX Codex

site-architecture · fcakyon — Claude Code & Codex skill: what it does

The site-architecture skill for Claude Code and Codex plans or restructures site structure, including page hierarchy, navigation, URL patterns, breadcrumbs, and internal links.

MIT ★ 1,216 updated 2026-11-09

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install seo-skills@claude-settings
Open on GitHub

What site-architecture does

The skill treats depth, URLs, navigation, and internal links as four views of a single structure, because adjusting them separately causes drift.

For each site type — SaaS, content site, e-commerce, documentation, small business — it provides a starting point: recommended depth (1–2 up to 3–4 levels), section names, and URL shape. Primary navigation should hold 4–7 items; once a dropdown exceeds roughly 20 entries, the skill flags that as the point to add a level rather than stretch the list. On URLs, it calls out three patterns that most often cause traffic loss after a redesign: dates in blog paths, numeric IDs instead of slugs, and changing a URL without a 301 redirect.

The agent hands back an ASCII hierarchy tree with the URL at each node, a URL-map table (page, URL, parent, navigation placement, priority), a redirect list when pages move, and a Mermaid diagram when the structure is clearer as a diagram. Pages with no incoming internal links are treated as orphans — the sitemap does not count as a link. Breadcrumb output pairs with BreadcrumbList schema; the skill notes they appear in desktop search results only.

What it helps with

  • Design a page hierarchy and URL scheme for a new SaaS site
  • Rebuild URL structure after a redesign and produce the full 301 redirect list
  • Add breadcrumbs with BreadcrumbList structured data across all pages
  • Build a hub-and-spoke content cluster linking spokes back to the hub
  • Find orphan pages with no incoming internal links and connect them

Example prompts for the agent

  • Plan the site architecture for a SaaS product: sections, URL patterns, and primary navigation
  • Audit the current hierarchy and list pages more than three clicks from the homepage
  • Generate a 301 redirect table for all URLs changing in the upcoming redesign

How to install site-architecture

1Plugin marketplace

/plugin marketplace add fcakyon/claude-codex-settings
/plugin install seo-skills@claude-settings

This installs the whole seo-skills plugin with all its skills

2Skills CLI (Vercel)

npx skills add fcakyon/claude-codex-settings --skill site-architecture -a claude-code

3Manually: put the files in place

~/.claude/skills/site-architecture/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/site-architecture/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about site-architecture

How do I install site-architecture in Claude Code?

Two steps: run /plugin marketplace add fcakyon/claude-codex-settings, then /plugin install seo-skills@claude-settings. The skill is then available at ~/.claude/skills/site-architecture/SKILL.md.

What does the site-architecture skill do?

It guides the agent through planning or restructuring a site's page hierarchy, URL patterns, navigation layout, breadcrumbs, and internal linking. Output includes an ASCII tree, a URL-map table, a redirect list, and an optional Mermaid diagram.

How is site-architecture different from seo-audit?

site-architecture focuses on structural decisions: hierarchy, navigation, URLs, and internal links. XML sitemaps are deliberately out of scope here — they live in the seo-audit skill.

Source text

SKILL.md · MIT
---
name: site-architecture
description: "Use when planning or restructuring what pages a site has and how they connect: hierarchy, navigation, URL patterns, breadcrumbs, and internal linking. Not for XML sitemaps, which are in seo-audit."
license: MIT
---

# Site architecture

Architecture is one decision repeated: how does someone get from the homepage to the page that answers their question, and how does a crawler follow the same path. Depth, navigation, URLs, and internal links are four views of that one structure, so change them together or they drift.

## Depth

Aim to put any page that matters within three clicks of the homepage. It isn't a law, but a critical page four or more levels down is a symptom worth chasing.

| Shape | Fits | Costs |
| --- | --- | --- |
| Flat, 2 levels | Small sites, portfolios | Stops scaling once a nav item has 20 children |
| Moderate, 3 levels | Most SaaS and content sites | Usually the right answer |
| Deep, 4 or more | Large catalogs, big docs | Scales, but buries things without strong linking |

Go as flat as the navigation tolerates. When a dropdown passes roughly 20 items, that's the signal to add a level rather than keep the list flat.

Levels: L0 is the homepage, L1 is a primary section (`/features`, `/blog`), L2 is a page within it (`/features/analytics`), L3 and beyond are detail pages (`/docs/api/authentication`).

## Site types as starting points

| Type | Depth | Sections | URL shape |
| --- | --- | --- | --- |
| SaaS marketing | 2 to 3 | Home, Features, Pricing, Blog, Docs | `/features/{name}`, `/blog/{slug}` |
| Content site | 2 to 3 | Home, Blog, Categories, About | `/blog/{slug}`, `/blog/category/{slug}` |
| Ecommerce | 3 to 4 | Home, Categories, Products | `/{category}/{subcategory}/{product}` |
| Documentation | 3 to 4 | Home, Guides, Reference | `/docs/{section}/{page}` |
| SaaS plus content | 3 to 4 | Home, Product, Blog, Resources, Docs | `/product/{feature}`, `/blog/{slug}` |
| Small business | 1 to 2 | Home, Services, About, Contact | `/services/{name}` |

## URLs

Readable, lowercase, hyphenated, mirroring the hierarchy, with one trailing-slash policy enforced everywhere. Short but still descriptive: `/blog/landing-page-conversions` beats `/blog/how-to-improve-your-landing-page-conversion-rates`.

The mistakes that cost the most:

- Dates in blog URLs. `/blog/2026/07/25/title` adds nothing and ages the post visibly.
- IDs or query strings carrying content. `/product/12345` and `/blog?id=123` should be slugs.
- Over-nesting past what the hierarchy needs.
- Mixing parents for the same kind of page, like `/features/analytics` alongside `/product/automation`.
- Changing a URL without a 301. Every old URL needs one, or the links pointing at it stop counting and anyone who bookmarked it gets a 404. This is the single most common cause of traffic loss after a redesign.

`references/patterns.md` has the URL pattern per page type, navigation layouts, and the diagram formats to hand back.

## Navigation

Primary navigation holds 4 to 7 items, ordered by importance, with the logo linking home and the call to action rightmost. Past 7, people stop reading the list and start hunting.

Footers group into columns: product, resources, company, legal. Sidebars carry within-section navigation for docs and long content. Breadcrumbs follow the path a typical user takes to the page, which Google recommends over mirroring the URL, with every segment linked except the current page, and they pair with `BreadcrumbList` schema.

Breadcrumbs are the cheapest structural win available: they add internal links on every page, they make hierarchy legible to a crawler, and they can earn a richer result.

## Internal linking

- No orphans. Every page needs at least one internal link pointing at it, and the sitemap is not a link.
- Anchor text describes the destination. Never "click here" or "read more".
- How many contextual links a single page carries is a decision for whoever owns that page's format, so recommend the connections worth making rather than a density target.
- Link the pages that matter more often. Inbound internal links are how you tell a crawler what's important.
- Hub and spoke for content clusters: one comprehensive hub, spokes covering sub-topics, each spoke linking back to the hub, the hub linking to all spokes, and spokes cross-linking where a reader would actually want it.

Hub and spoke is what makes a set of posts add up to more than its pages, because it concentrates the signal on the hub rather than spreading it across a dozen equal posts competing with each other.

## What to hand back

An ASCII tree of the hierarchy with the URL at each node, a URL map table (page, URL, parent, where it appears in navigation, priority), the redirect list when anything moves, and a Mermaid diagram when the structure is worth seeing rather than reading. `references/patterns.md` has the formats.

## Checks from live audits

- Fragment routes: Google [generally ignores URL fragments](https://developers.google.com/search/docs/crawling-indexing/url-structure), so client-side routes like `/#/pricing` need real paths through the History API.
- Breadcrumb results: Google shows them [on desktop only](https://developers.google.com/search/docs/appearance/structured-data/breadcrumb), so don't expect them in mobile results.

## Sources

- Google Search Central, URL structure best practices: https://developers.google.com/search/docs/crawling-indexing/url-structure
- Google Search Central, Redirects and Google Search: https://developers.google.com/search/docs/crawling-indexing/301-redirects
- Google Search Central, Breadcrumb structured data: https://developers.google.com/search/docs/appearance/structured-data/breadcrumb
- Nielsen Norman Group, Flat vs deep website hierarchies: https://www.nngroup.com/articles/flat-vs-deep-hierarchy/

© fcakyon · MIT · fcakyon/claude-codex-settings

Similar skills

All skills for SEO and GEO →

site-architecture by other authors comes first.

site-architecture coreyhaines31 site-architecture — a skill for planning page hierarchy, URL structure, navigation, and internal linking when building or restructuring a website. Works on Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. CX Codex +1 135,700installs site-architecture Alireza Rezvani The site-architecture skill audits site structure, URLs, navigation, and internal links. Use it when planning a redesign or investigating structural SEO issues. CX Codex +1 623installs site-architecture alinaqi site-architecture sets up technical SEO foundations: robots.txt rules, XML sitemaps, Open Graph metadata, and crawler access for search engines and AI bots. CX Codex +1 342installs site-crawlability kostja94 site-crawlability — a technical SEO skill that walks through redirect chains, broken links, orphan pages and what AI crawlers can actually read. CX Codex +1 1,200installs site-structure-optimizer aaron-he-zhu site-structure-optimizer — a skill that plans site structure and untangles internal linking: page hierarchy, URLs, hub clusters, orphan pages. It returns a structure score out of 100. CX Codex +1 1,500installs pillar-content-architecture rampstackco pillar-content-architecture — a skill that designs content hubs: pillar topic selection, cluster planning, internal linking, URL structure. Use it when content fails to rank despite decent individual pieces. CX Codex +1 333installs url-link-extractor davila7 url-link-extractor scans your codebase to compile an inventory of internal links, external URLs, asset paths, and API endpoints. Useful during domain migrations, SEO audits, and code cleanup. CX Codex 799installs website-structure kostja94 website-structure is a Claude Code skill that plans which pages to build and in what order for a new or existing site. CX Codex +1 1,400installs navigation-patterns Owl-Listener Helps select and design navigation patterns such as tab bars, sidebars, and breadcrumbs. Useful when mapping user journeys across mobile and desktop interfaces. CX Codex +1 2,300installs

From the same set113

The whole set →
ultralytics-platform ultralytics-platform is a Claude Code skill for managing Ultralytics Platform resources, model training, and hosted inference. It activates on requests to upload datasets or models, train in the cloud, or deploy an endpoint. CX Codex +1 ★ 1,216repo stars ultralytics-branding ultralytics-branding loads Ultralytics brand rules: colors, typography, logo specs and tone for PDFs, slides, documents, marketing emails and social posts. CX Codex +1 ★ 1,216repo stars email-design email-design — a skill for Claude Code and Codex that handles transactional email layout. Styles account confirmations, password resets and billing receipts to match your application branding. CX Codex +1 ★ 1,216repo stars commit-creator commit-creator reviews staged changes, plans a single commit or a logical series, and writes concise commit messages. Available for Claude Code and Codex. CX Codex ★ 1,216repo stars derive-client derive-client records browser network traffic into a HAR archive and turns captured internal endpoints into a standalone API client or CLI script. CX Codex +1 ★ 1,216repo stars polar-local-environment The polar-local-environment skill for Claude Code manages Polar’s local Docker setup, including stack operations, service debugging, and separate environments for multiple worktrees. CX Codex +1 ★ 1,216repo stars yolo-training yolo-training reads YOLO26 training curves and results.csv, diagnoses overfitting or poor mAP, and points to the cheapest fix first. CX Codex +1 ★ 1,216repo stars supabase-cli Equips coding agents to run Supabase CLI commands for local environments, schema migrations, edge function deployments, and TypeScript type generation. CX Codex +1 ★ 1,216repo stars

Project sponsors

Companies that keep this analytics open