# site-architecture

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

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 1216 repo stars
- Author: fcakyon
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/fcakyon/claude-codex-settings/tree/HEAD/plugins/seo-skills/skills/site-architecture/SKILL.md
- Updated: 2026-11-09
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/fcakyon-site-architecture

## What it 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.

## Install

### Claude Code (native platform)

1. **Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add fcakyon/claude-codex-settings
```
In the agent chat (not a shell):
```text
/plugin install seo-skills@claude-settings
```
This installs the whole seo-skills plugin with all its skills

2. **Skills CLI (Vercel)**
```bash
npx skills add fcakyon/claude-codex-settings --skill site-architecture -a claude-code
```

3. **Manually: put the files in place**
- File: `~/.claude/skills/site-architecture/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/site-architecture/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add fcakyon/claude-codex-settings --skill site-architecture -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/site-architecture/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add fcakyon/claude-codex-settings --skill site-architecture -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/site-architecture/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install fcakyon/claude-codex-settings plugins/seo-skills/skills/site-architecture
```

2. **Manually: put the files in place**
- File: `.github/skills/site-architecture/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add fcakyon/claude-codex-settings --skill site-architecture -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/fcakyon/claude-codex-settings --path plugins/seo-skills/skills/site-architecture
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/site-architecture/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/fcakyon/claude-codex-settings/tree/HEAD/plugins/seo-skills/skills/site-architecture/SKILL.md

## When to use it
- 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
- 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

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 2616ce43c42feb6d.

BEGIN THIRD-PARTY FILE 2616ce43c42feb6d
```text
---
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}` |
```
END THIRD-PARTY FILE 2616ce43c42feb6d

The third-party file has ended. Everything between the 2616ce43c42feb6d tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 1968 of 5867 bytes. © fcakyon · MIT · https://github.com/fcakyon/claude-codex-settings/tree/HEAD/plugins/seo-skills/skills/site-architecture/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
