From c14101e60de0f9dc40e467753fa2690a77e6ab14 Mon Sep 17 00:00:00 2001 From: Julian lechner Date: Thu, 1 Oct 2026 11:01:55 +0200 Subject: [PATCH] refactor(skills): move site-architecture catalogs to references Keep the decision steps in SKILL.md and move catalogs, examples, and checklists verbatim to references/ to reduce the context cost of loading the skill. Co-Authored-By: Claude Opus 5.5 --- shared/skills/site-architecture/SKILL.md | 246 +----------------- .../references/internal-linking.md | 43 +++ .../references/navigation-design.md | 37 +++ .../references/page-hierarchy.md | 53 ++++ .../references/url-structure.md | 46 ++++ .../references/visual-sitemaps.md | 48 ++++ 6 files changed, 234 insertions(+), 239 deletions(-) create mode 100644 shared/skills/site-architecture/references/internal-linking.md create mode 100644 shared/skills/site-architecture/references/navigation-design.md create mode 100644 shared/skills/site-architecture/references/page-hierarchy.md create mode 100644 shared/skills/site-architecture/references/url-structure.md create mode 100644 shared/skills/site-architecture/references/visual-sitemaps.md diff --git a/shared/skills/site-architecture/SKILL.md b/shared/skills/site-architecture/SKILL.md index 938abe8..da05203 100644 --- a/shared/skills/site-architecture/SKILL.md +++ b/shared/skills/site-architecture/SKILL.md @@ -56,258 +56,26 @@ Gather this context (ask if not provided): --- -## Page Hierarchy Design +## References -### The 3-Click Rule - -Users should reach any important page within 3 clicks from the homepage. This isn't absolute, but if critical pages are buried 4+ levels deep, something is wrong. - -### Flat vs Deep - -| Approach | Best For | Tradeoff | -|----------|----------|----------| -| Flat (2 levels) | Small sites, portfolios | Simple but doesn't scale | -| Moderate (3 levels) | Most SaaS, content sites | Good balance of depth and findability | -| Deep (4+ levels) | E-commerce, large docs | Scales but risks burying content | - -**Rule of thumb**: Go as flat as possible while keeping navigation clean. If a nav dropdown has 20+ items, add a level of hierarchy. - -### Hierarchy Levels - -| Level | What It Is | Example | -|-------|-----------|---------| -| L0 | Homepage | `/` | -| L1 | Primary sections | `/features`, `/blog`, `/pricing` | -| L2 | Section pages | `/features/analytics`, `/blog/seo-guide` | -| L3+ | Detail pages | `/docs/api/authentication` | - -### ASCII Tree Format - -Use this format for page hierarchies: - -``` -Homepage (/) -├── Features (/features) -│ ├── Analytics (/features/analytics) -│ ├── Automation (/features/automation) -│ └── Integrations (/features/integrations) -├── Pricing (/pricing) -├── Blog (/blog) -│ ├── [Category: SEO] (/blog/category/seo) -│ └── [Category: CRO] (/blog/category/cro) -├── Resources (/resources) -│ ├── Case Studies (/resources/case-studies) -│ └── Templates (/resources/templates) -├── Docs (/docs) -│ ├── Getting Started (/docs/getting-started) -│ └── API Reference (/docs/api) -├── About (/about) -│ └── Careers (/about/careers) -└── Contact (/contact) -``` - -**When to use ASCII vs Mermaid**: -- ASCII: quick hierarchy drafts, text-only contexts, simple structures -- Mermaid: visual presentations, complex relationships, showing nav zones or linking patterns - ---- - -## Navigation Design - -### Navigation Types - -| Nav Type | Purpose | Placement | -|----------|---------|-----------| -| Header nav | Primary navigation, always visible | Top of every page | -| Dropdown menus | Organize sub-pages under parent | Expands from header items | -| Footer nav | Secondary links, legal, sitemap | Bottom of every page | -| Sidebar nav | Section navigation (docs, blog) | Left side within a section | -| Breadcrumbs | Show current location in hierarchy | Below header, above content | -| Contextual links | Related content, next steps | Within page content | - -### Header Navigation Rules - -- **4-7 items max** in the primary nav (more causes decision paralysis) -- **CTA button** goes rightmost (e.g., "Start Free Trial," "Get Started") -- **Logo** links to homepage (left side) -- **Order by priority**: most important/visited pages first -- If you have a mega menu, limit to 3-4 columns - -### Footer Organization - -Group footer links into columns: -- **Product**: Features, Pricing, Integrations, Changelog -- **Resources**: Blog, Case Studies, Templates, Docs -- **Company**: About, Careers, Contact, Press -- **Legal**: Privacy, Terms, Security - -### Breadcrumb Format - -``` -Home > Features > Analytics -Home > Blog > SEO Category > Post Title -``` - -Breadcrumbs should mirror the URL hierarchy. Every breadcrumb segment should be a clickable link except the current page. +- [references/page-hierarchy.md](references/page-hierarchy.md): Read when designing hierarchy depth, levels, or the ASCII tree +- [references/navigation-design.md](references/navigation-design.md): Read when designing header, footer, sidebar, or breadcrumb navigation +- [references/url-structure.md](references/url-structure.md): Read when designing URL patterns and redirects +- [references/visual-sitemaps.md](references/visual-sitemaps.md): Read when producing the Mermaid visual sitemap +- [references/internal-linking.md](references/internal-linking.md): Read when planning internal links or a link audit **For detailed navigation patterns**: See [references/navigation-patterns.md](references/navigation-patterns.md) ---- - -## URL Structure - -### Design Principles - -1. **Readable by humans** — `/features/analytics` not `/f/a123` -2. **Hyphens, not underscores** — `/blog/seo-guide` not `/blog/seo_guide` -3. **Reflect the hierarchy** — URL path should match site structure -4. **Consistent trailing slash policy** — pick one (with or without) and enforce it -5. **Lowercase always** — `/About` should redirect to `/about` -6. **Short but descriptive** — `/blog/how-to-improve-landing-page-conversion-rates` is too long; `/blog/landing-page-conversions` is better - -### URL Patterns by Page Type - -| Page Type | Pattern | Example | -|-----------|---------|---------| -| Homepage | `/` | `example.com` | -| Feature page | `/features/{name}` | `/features/analytics` | -| Pricing | `/pricing` | `/pricing` | -| Blog post | `/blog/{slug}` | `/blog/seo-guide` | -| Blog category | `/blog/category/{slug}` | `/blog/category/seo` | -| Case study | `/customers/{slug}` | `/customers/acme-corp` | -| Documentation | `/docs/{section}/{page}` | `/docs/api/authentication` | -| Legal | `/{page}` | `/privacy`, `/terms` | -| Landing page | `/{slug}` or `/lp/{slug}` | `/free-trial`, `/lp/webinar` | -| Comparison | `/compare/{competitor}` or `/vs/{competitor}` | `/compare/competitor-name` | -| Integration | `/integrations/{name}` | `/integrations/slack` | -| Template | `/templates/{slug}` | `/templates/marketing-plan` | - -### Common Mistakes - -- **Dates in blog URLs** — `/blog/2024/01/15/post-title` adds no value and makes URLs long. Use `/blog/post-title`. -- **Over-nesting** — `/products/category/subcategory/item/detail` is too deep. Flatten where possible. -- **Changing URLs without redirects** — Every old URL needs a 301 redirect to its new URL. Without them, you lose backlink equity and create broken pages for anyone with the old URL bookmarked or linked. -- **IDs in URLs** — `/product/12345` is not human-readable. Use slugs. -- **Query parameters for content** — `/blog?id=123` should be `/blog/post-title`. -- **Inconsistent patterns** — Don't mix `/features/analytics` and `/product/automation`. Pick one parent. - -### Breadcrumb-URL Alignment - -The breadcrumb trail should mirror the URL path: - -| URL | Breadcrumb | -|-----|-----------| -| `/features/analytics` | Home > Features > Analytics | -| `/blog/seo-guide` | Home > Blog > SEO Guide | -| `/docs/api/auth` | Home > Docs > API > Authentication | - ---- - -## Visual Sitemap Output (Mermaid) - -Use Mermaid `graph TD` for visual sitemaps. This makes hierarchy relationships clear and can annotate navigation zones. - -### Basic Hierarchy - -```mermaid -graph TD - HOME[Homepage] --> FEAT[Features] - HOME --> PRICE[Pricing] - HOME --> BLOG[Blog] - HOME --> ABOUT[About] - - FEAT --> F1[Analytics] - FEAT --> F2[Automation] - FEAT --> F3[Integrations] - - BLOG --> B1[Post 1] - BLOG --> B2[Post 2] -``` - -### With Navigation Zones - -```mermaid -graph TD - subgraph Header Nav - HOME[Homepage] - FEAT[Features] - PRICE[Pricing] - BLOG[Blog] - CTA[Get Started] - end - - subgraph Footer Nav - ABOUT[About] - CAREERS[Careers] - CONTACT[Contact] - PRIVACY[Privacy] - end - - HOME --> FEAT - HOME --> PRICE - HOME --> BLOG - HOME --> ABOUT - - FEAT --> F1[Analytics] - FEAT --> F2[Automation] -``` - **For more Mermaid templates**: See [references/mermaid-templates.md](references/mermaid-templates.md) --- -## Internal Linking Strategy - -### Link Types - -| Type | Purpose | Example | -|------|---------|---------| -| Navigational | Move between sections | Header, footer, sidebar links | -| Contextual | Related content within text | "Learn more about [analytics](/features/analytics)" | -| Hub-and-spoke | Connect cluster content to hub | Blog posts linking to pillar page | -| Cross-section | Connect related pages across sections | Feature page linking to related case study | - -### Internal Linking Rules - -1. **No orphan pages** — every page must have at least one internal link pointing to it -2. **Descriptive anchor text** — "our analytics features" not "click here" -3. **5-10 internal links per 1000 words** of content (approximate guideline) -4. **Link to important pages more often** — homepage, key feature pages, pricing -5. **Use breadcrumbs** — free internal links on every page -6. **Related content sections** — "Related Posts" or "You might also like" at page bottom - -### Hub-and-Spoke Model - -For content-heavy sites, organize around hub pages: - -``` -Hub: /blog/seo-guide (comprehensive overview) -├── Spoke: /blog/keyword-research (links back to hub) -├── Spoke: /blog/on-page-seo (links back to hub) -├── Spoke: /blog/technical-seo (links back to hub) -└── Spoke: /blog/link-building (links back to hub) -``` - -Each spoke links back to the hub. The hub links to all spokes. Spokes link to each other where relevant. - -### Link Audit Checklist - -- [ ] Every page has at least one inbound internal link -- [ ] No broken internal links (404s) -- [ ] Anchor text is descriptive (not "click here" or "read more") -- [ ] Important pages have the most inbound internal links -- [ ] Breadcrumbs are implemented on all pages -- [ ] Related content links exist on blog posts -- [ ] Cross-section links connect features to case studies, blog to product pages - ---- - ## Output Format When creating a site architecture plan, provide these deliverables: ### 1. Page Hierarchy (ASCII Tree) -Full site structure with URLs at each node. Use the ASCII tree format from the Page Hierarchy Design section. +Full site structure with URLs at each node. Use the ASCII tree format from [references/page-hierarchy.md](references/page-hierarchy.md). ### 2. Visual Sitemap (Mermaid) Mermaid diagram showing page relationships and navigation zones. Use `graph TD` with subgraphs for nav zones where helpful. diff --git a/shared/skills/site-architecture/references/internal-linking.md b/shared/skills/site-architecture/references/internal-linking.md new file mode 100644 index 0000000..19a856a --- /dev/null +++ b/shared/skills/site-architecture/references/internal-linking.md @@ -0,0 +1,43 @@ +# Internal Linking Strategy + +## Link Types + +| Type | Purpose | Example | +|------|---------|---------| +| Navigational | Move between sections | Header, footer, sidebar links | +| Contextual | Related content within text | "Learn more about [analytics](/features/analytics)" | +| Hub-and-spoke | Connect cluster content to hub | Blog posts linking to pillar page | +| Cross-section | Connect related pages across sections | Feature page linking to related case study | + +## Internal Linking Rules + +1. **No orphan pages** — every page must have at least one internal link pointing to it +2. **Descriptive anchor text** — "our analytics features" not "click here" +3. **5-10 internal links per 1000 words** of content (approximate guideline) +4. **Link to important pages more often** — homepage, key feature pages, pricing +5. **Use breadcrumbs** — free internal links on every page +6. **Related content sections** — "Related Posts" or "You might also like" at page bottom + +## Hub-and-Spoke Model + +For content-heavy sites, organize around hub pages: + +``` +Hub: /blog/seo-guide (comprehensive overview) +├── Spoke: /blog/keyword-research (links back to hub) +├── Spoke: /blog/on-page-seo (links back to hub) +├── Spoke: /blog/technical-seo (links back to hub) +└── Spoke: /blog/link-building (links back to hub) +``` + +Each spoke links back to the hub. The hub links to all spokes. Spokes link to each other where relevant. + +## Link Audit Checklist + +- [ ] Every page has at least one inbound internal link +- [ ] No broken internal links (404s) +- [ ] Anchor text is descriptive (not "click here" or "read more") +- [ ] Important pages have the most inbound internal links +- [ ] Breadcrumbs are implemented on all pages +- [ ] Related content links exist on blog posts +- [ ] Cross-section links connect features to case studies, blog to product pages diff --git a/shared/skills/site-architecture/references/navigation-design.md b/shared/skills/site-architecture/references/navigation-design.md new file mode 100644 index 0000000..f0a00bb --- /dev/null +++ b/shared/skills/site-architecture/references/navigation-design.md @@ -0,0 +1,37 @@ +# Navigation Design + +## Navigation Types + +| Nav Type | Purpose | Placement | +|----------|---------|-----------| +| Header nav | Primary navigation, always visible | Top of every page | +| Dropdown menus | Organize sub-pages under parent | Expands from header items | +| Footer nav | Secondary links, legal, sitemap | Bottom of every page | +| Sidebar nav | Section navigation (docs, blog) | Left side within a section | +| Breadcrumbs | Show current location in hierarchy | Below header, above content | +| Contextual links | Related content, next steps | Within page content | + +## Header Navigation Rules + +- **4-7 items max** in the primary nav (more causes decision paralysis) +- **CTA button** goes rightmost (e.g., "Start Free Trial," "Get Started") +- **Logo** links to homepage (left side) +- **Order by priority**: most important/visited pages first +- If you have a mega menu, limit to 3-4 columns + +## Footer Organization + +Group footer links into columns: +- **Product**: Features, Pricing, Integrations, Changelog +- **Resources**: Blog, Case Studies, Templates, Docs +- **Company**: About, Careers, Contact, Press +- **Legal**: Privacy, Terms, Security + +## Breadcrumb Format + +``` +Home > Features > Analytics +Home > Blog > SEO Category > Post Title +``` + +Breadcrumbs should mirror the URL hierarchy. Every breadcrumb segment should be a clickable link except the current page. diff --git a/shared/skills/site-architecture/references/page-hierarchy.md b/shared/skills/site-architecture/references/page-hierarchy.md new file mode 100644 index 0000000..eafd6c3 --- /dev/null +++ b/shared/skills/site-architecture/references/page-hierarchy.md @@ -0,0 +1,53 @@ +# Page Hierarchy Design + +## The 3-Click Rule + +Users should reach any important page within 3 clicks from the homepage. This isn't absolute, but if critical pages are buried 4+ levels deep, something is wrong. + +## Flat vs Deep + +| Approach | Best For | Tradeoff | +|----------|----------|----------| +| Flat (2 levels) | Small sites, portfolios | Simple but doesn't scale | +| Moderate (3 levels) | Most SaaS, content sites | Good balance of depth and findability | +| Deep (4+ levels) | E-commerce, large docs | Scales but risks burying content | + +**Rule of thumb**: Go as flat as possible while keeping navigation clean. If a nav dropdown has 20+ items, add a level of hierarchy. + +## Hierarchy Levels + +| Level | What It Is | Example | +|-------|-----------|---------| +| L0 | Homepage | `/` | +| L1 | Primary sections | `/features`, `/blog`, `/pricing` | +| L2 | Section pages | `/features/analytics`, `/blog/seo-guide` | +| L3+ | Detail pages | `/docs/api/authentication` | + +## ASCII Tree Format + +Use this format for page hierarchies: + +``` +Homepage (/) +├── Features (/features) +│ ├── Analytics (/features/analytics) +│ ├── Automation (/features/automation) +│ └── Integrations (/features/integrations) +├── Pricing (/pricing) +├── Blog (/blog) +│ ├── [Category: SEO] (/blog/category/seo) +│ └── [Category: CRO] (/blog/category/cro) +├── Resources (/resources) +│ ├── Case Studies (/resources/case-studies) +│ └── Templates (/resources/templates) +├── Docs (/docs) +│ ├── Getting Started (/docs/getting-started) +│ └── API Reference (/docs/api) +├── About (/about) +│ └── Careers (/about/careers) +└── Contact (/contact) +``` + +**When to use ASCII vs Mermaid**: +- ASCII: quick hierarchy drafts, text-only contexts, simple structures +- Mermaid: visual presentations, complex relationships, showing nav zones or linking patterns diff --git a/shared/skills/site-architecture/references/url-structure.md b/shared/skills/site-architecture/references/url-structure.md new file mode 100644 index 0000000..7ab7fd1 --- /dev/null +++ b/shared/skills/site-architecture/references/url-structure.md @@ -0,0 +1,46 @@ +# URL Structure + +## Design Principles + +1. **Readable by humans** — `/features/analytics` not `/f/a123` +2. **Hyphens, not underscores** — `/blog/seo-guide` not `/blog/seo_guide` +3. **Reflect the hierarchy** — URL path should match site structure +4. **Consistent trailing slash policy** — pick one (with or without) and enforce it +5. **Lowercase always** — `/About` should redirect to `/about` +6. **Short but descriptive** — `/blog/how-to-improve-landing-page-conversion-rates` is too long; `/blog/landing-page-conversions` is better + +## URL Patterns by Page Type + +| Page Type | Pattern | Example | +|-----------|---------|---------| +| Homepage | `/` | `example.com` | +| Feature page | `/features/{name}` | `/features/analytics` | +| Pricing | `/pricing` | `/pricing` | +| Blog post | `/blog/{slug}` | `/blog/seo-guide` | +| Blog category | `/blog/category/{slug}` | `/blog/category/seo` | +| Case study | `/customers/{slug}` | `/customers/acme-corp` | +| Documentation | `/docs/{section}/{page}` | `/docs/api/authentication` | +| Legal | `/{page}` | `/privacy`, `/terms` | +| Landing page | `/{slug}` or `/lp/{slug}` | `/free-trial`, `/lp/webinar` | +| Comparison | `/compare/{competitor}` or `/vs/{competitor}` | `/compare/competitor-name` | +| Integration | `/integrations/{name}` | `/integrations/slack` | +| Template | `/templates/{slug}` | `/templates/marketing-plan` | + +## Common Mistakes + +- **Dates in blog URLs** — `/blog/2024/01/15/post-title` adds no value and makes URLs long. Use `/blog/post-title`. +- **Over-nesting** — `/products/category/subcategory/item/detail` is too deep. Flatten where possible. +- **Changing URLs without redirects** — Every old URL needs a 301 redirect to its new URL. Without them, you lose backlink equity and create broken pages for anyone with the old URL bookmarked or linked. +- **IDs in URLs** — `/product/12345` is not human-readable. Use slugs. +- **Query parameters for content** — `/blog?id=123` should be `/blog/post-title`. +- **Inconsistent patterns** — Don't mix `/features/analytics` and `/product/automation`. Pick one parent. + +## Breadcrumb-URL Alignment + +The breadcrumb trail should mirror the URL path: + +| URL | Breadcrumb | +|-----|-----------| +| `/features/analytics` | Home > Features > Analytics | +| `/blog/seo-guide` | Home > Blog > SEO Guide | +| `/docs/api/auth` | Home > Docs > API > Authentication | diff --git a/shared/skills/site-architecture/references/visual-sitemaps.md b/shared/skills/site-architecture/references/visual-sitemaps.md new file mode 100644 index 0000000..28b3a2a --- /dev/null +++ b/shared/skills/site-architecture/references/visual-sitemaps.md @@ -0,0 +1,48 @@ +# Visual Sitemap Output (Mermaid) + +Use Mermaid `graph TD` for visual sitemaps. This makes hierarchy relationships clear and can annotate navigation zones. + +## Basic Hierarchy + +```mermaid +graph TD + HOME[Homepage] --> FEAT[Features] + HOME --> PRICE[Pricing] + HOME --> BLOG[Blog] + HOME --> ABOUT[About] + + FEAT --> F1[Analytics] + FEAT --> F2[Automation] + FEAT --> F3[Integrations] + + BLOG --> B1[Post 1] + BLOG --> B2[Post 2] +``` + +## With Navigation Zones + +```mermaid +graph TD + subgraph Header Nav + HOME[Homepage] + FEAT[Features] + PRICE[Pricing] + BLOG[Blog] + CTA[Get Started] + end + + subgraph Footer Nav + ABOUT[About] + CAREERS[Careers] + CONTACT[Contact] + PRIVACY[Privacy] + end + + HOME --> FEAT + HOME --> PRICE + HOME --> BLOG + HOME --> ABOUT + + FEAT --> F1[Analytics] + FEAT --> F2[Automation] +```