site-architecture

Overview of site-architecture skill

What the site-architecture skill does

The site-architecture skill helps you plan or reorganize a website's page hierarchy, navigation, URL structure, and internal linking. It is built for information architecture work, not technical XML sitemap generation. If your real question is “what pages should this site have, how should they connect, and how should users move through them?”, this is the right skill.

Who should use site-architecture

This site-architecture skill is best for:

• marketers planning a new site or major restructure
• founders defining a SaaS marketing site
• UI/UX teams working on navigation and IA
• SEO-aware content teams deciding hubs, sections, and page relationships
• agencies that need a fast first-pass sitemap, URL map, and nav spec

It is especially useful when a site has grown organically and now feels hard to browse, inconsistent, or too deep.

Best-fit jobs to be done

Use site-architecture when you need to:

• turn a rough list of pages into a logical site map
• decide between flat vs deep structure
• define header, footer, and section navigation
• create URL patterns for sections like /features, /compare, or /integrations
• improve internal linking between hub pages and detail pages
• produce a visual sitemap in ASCII or Mermaid for review

What makes this skill different from a generic prompt

A generic prompt may list pages. The site-architecture skill is stronger because it pushes toward a fuller deliverable set:

• business and audience context first
• explicit hierarchy design
• navigation recommendations
• URL structure patterns
• internal linking guidance
• visual sitemap outputs
• reusable templates for common site types

The repo also includes practical references for Mermaid diagrams, navigation patterns, and site-type templates, which makes output more consistent than starting from scratch.

Important scope boundaries

This skill does not primarily cover:

• XML sitemap files
• full SEO audits
• schema markup
• final wireframes or polished UI mockups

For site-architecture for UI/UX Design, it is most useful at the structure layer: page grouping, wayfinding, nav zones, and content discoverability before detailed interface design.

How to Use site-architecture skill

Install context and access pattern

Install the skill from the repository with:

npx skills add https://github.com/coreyhaines31/marketingskills --skill site-architecture

In practice, users trigger site-architecture by asking for help with site maps, navigation, page hierarchy, or URL planning. It fits best in a Skills-compatible agent setup where the model can read the skill files and follow the workflow.

Read these files first before using site-architecture

If you want to judge the skill quickly, start here:

1. skills/site-architecture/SKILL.md
2. skills/site-architecture/references/site-type-templates.md
3. skills/site-architecture/references/navigation-patterns.md
4. skills/site-architecture/references/mermaid-templates.md
5. skills/site-architecture/evals/evals.json

That reading order tells you the workflow, common outputs, concrete navigation options, diagram formats, and what “good” looks like in evaluations.

The most important input the skill needs

The site-architecture skill gets much better when you provide:

• what the company does
• primary audiences
• top site goals, usually 2-3 max
• whether this is a new site or a restructure
• existing page inventory, if any
• problem areas such as duplication, deep nesting, or poor findability
• site type, such as SaaS, ecommerce, services, marketplace, or content-heavy site

If you omit this, the model can still draft a structure, but it will be generic and may choose the wrong navigation pattern.

Check product-marketing context first

A useful repo-specific behavior: the skill explicitly tells the agent to check for .agents/product-marketing-context.md or older .claude/product-marketing-context.md before asking questions. That matters because many architecture decisions depend on positioning, audiences, and offer structure.

If you already have product marketing context documented, point the model to it. This reduces repetitive back-and-forth and improves page grouping decisions.

Turn a rough goal into a strong site-architecture prompt

Weak prompt:

Help me make a sitemap.

Stronger prompt:

Use the site-architecture skill to plan a SaaS marketing site for an analytics product aimed at ecommerce teams. Our goals are demo requests, SEO traffic, and partner integrations. We need a homepage, pricing, feature pages, docs, blog, integrations, and competitor comparison pages. Keep top nav to 5-6 primary items. Propose page hierarchy, URL structure, header/footer nav, and internal linking model.

Why this works:

• defines audience and business type
• names conversion and content goals
• lists required content types
• adds a navigation constraint
• asks for concrete deliverables the skill is designed to produce

What good site-architecture usage looks like

Ask for output in this order:

1. assumptions and missing inputs
2. proposed hierarchy
3. URL map
4. navigation spec
5. internal linking recommendations
6. ASCII tree or Mermaid diagram
7. tradeoffs or open questions

This mirrors the skill’s practical strengths. It helps you review structure before debating labels or design details.

Use the reference templates instead of starting blank

The biggest adoption shortcut is the reference set:

• site-type-templates.md gives ready-made hierarchy patterns
• navigation-patterns.md helps choose simple header vs mega menu vs other nav models
• mermaid-templates.md speeds up visual sitemap creation

For many teams, the best workflow is: choose the closest site template, adapt sections, then refine nav and URLs. That is faster and usually better than freeform prompting.

Recommended workflow for a new site

For a new build:

1. define business goals and audiences
2. pick the closest site type template
3. adjust primary sections
4. set URL conventions
5. limit header navigation to priority items
6. assign supporting pages to footer or sectional nav
7. add hub-and-spoke internal linking where relevant
8. export an ASCII tree or Mermaid diagram for stakeholder review

This works especially well for SaaS, where sections like /features, /customers, /resources, /integrations, and /compare often need clear separation.

Recommended workflow for a restructure

For a messy existing site, give the model:

• current nav
• page count or inventory
• duplicated sections
• pages with poor traffic or unclear ownership
• user complaints like “can’t find docs” or “too many dropdowns”

Then ask it to:

• consolidate sections
• remove duplicate entry points
• flatten unnecessary depth
• separate primary nav from utility/footer items
• preserve high-value legacy URLs where possible

This is where the site-architecture skill is more useful than a generic brainstorming prompt because it frames the work as reorganization, not just page listing.

site-architecture for UI/UX Design teams

For UI/UX Design, use the skill before wireframes when you need to clarify:

• what belongs in global nav
• where section landing pages are needed
• how breadcrumbs should reflect hierarchy
• which pages deserve direct access vs indirect access
• when a mega menu is justified

It will not replace interaction design, but it gives UI/UX teams a more defensible IA baseline before designing components.

Practical output formats to request

The skill is strongest when you request one or more of these:

• ASCII tree for quick review
• Mermaid sitemap for documentation
• URL map table with priorities
• header/footer nav spec
• internal linking model by section

These formats are all supported by repository evidence, so you are aligning your request to what the skill already handles well.

site-architecture skill FAQ

Is site-architecture good for beginners?

Yes, if you already know the site’s goals and major content types. The skill gives structure faster than inventing IA from scratch. Beginners usually struggle when they provide too little context, not because the skill is too advanced.

When should I use site-architecture instead of a normal prompt?

Use the site-architecture skill when the output needs to be operational: hierarchy, nav, URL rules, and linking strategy. A normal prompt can brainstorm pages, but this skill is better when you need a reviewable architecture artifact.

Does site-architecture create XML sitemaps?

No. This skill is for information architecture and navigation planning. It is not the right tool for XML sitemap generation or technical crawl diagnostics.

Is site-architecture useful for existing sites, not just new ones?

Yes. It is a strong fit for restructures, especially when a site has too many pages, inconsistent grouping, or confusing navigation. Give it the current state and the pain points, not just the desired future state.

How does it compare to doing IA manually?

Manual IA work is still valuable, but this skill accelerates first-pass structure and gives reusable templates. It is most helpful for drafting options, exposing tradeoffs, and producing artifacts for team review. You still need human judgment on politics, ownership, and implementation constraints.

Is this a good fit for site-architecture for UI/UX Design?

Yes, as an upstream planning tool. It helps UI/UX Design teams define page relationships, navigation depth, and wayfinding logic before detailed layouts. It is less suited for component-level design decisions.

When is site-architecture the wrong skill?

Skip it if your real need is:

• technical SEO auditing
• schema planning
• content writing
• wireframing high-fidelity page layouts
• app information architecture far beyond marketing-site patterns

It is also a weak fit if you cannot supply basic business context.

How to Improve site-architecture skill

Give sharper business constraints

The fastest way to improve site-architecture output is to state constraints explicitly:

• primary conversion action
• top audience segments
• maximum header nav count
• must-have sections
• sections that should stay out of main nav
• whether SEO landing pages are a priority

Without constraints, the model tends to overinclude pages and underprioritize navigation.

Provide a page inventory for restructures

For existing sites, paste a rough page inventory or current nav. Even a messy list is enough. This helps the site-architecture skill identify consolidation opportunities, duplicate structures, and orphaned sections that would otherwise be missed.

Ask for tradeoffs, not just one answer

A strong improvement pattern is:

Give me a recommended architecture plus one simpler option and one SEO-expansion option.

This surfaces real decisions such as:

• simple nav vs scalable nav
• fewer top-level sections vs dedicated landing page hubs
• flatter hierarchy vs clearer categorization

That makes the skill more useful for stakeholder alignment.

Force clearer output with specific deliverables

If first-pass output feels vague, ask for:

• a full ASCII tree
• exact URL patterns
• nav labels with item counts
• breadcrumbs examples
• section-level internal links

Specific formats reduce hand-wavy advice and make the site-architecture guide more implementation-ready.

Common failure modes to watch for

Watch for these issues in first drafts:

• too many top-level nav items
• category names that overlap
• content hubs mixed with conversion pages without clear priority
• deep nesting with little user benefit
• blog/resources/docs grouped inconsistently
• SEO landing pages added without a linking plan

These are common IA problems the skill can introduce if your prompt is broad or ambiguous.

Improve internal linking recommendations

Don’t accept “add internal links” as enough. Ask the model to specify:

• which hub pages link to which detail pages
• which detail pages link back to hubs
• where cross-links make sense, such as features to integrations or comparisons to pricing
• which pages should be excluded from heavy cross-linking

This turns the site-architecture usage from conceptual to actionable.

Use the repo references to tighten weak drafts

If output feels generic, direct the model to apply:

• references/navigation-patterns.md for nav decisions
• references/site-type-templates.md for section coverage
• references/mermaid-templates.md for clearer diagrams

This is one of the easiest ways to improve the site-architecture skill without changing the skill itself.

Iterate after the first architecture pass

Best practice is a second-round prompt like:

Revise this site architecture to reduce header nav to 5 items, move low-priority pages to footer, preserve our existing /blog structure, and create a clearer hub model for integrations and comparison pages.

That kind of targeted revision is usually where the skill becomes genuinely production-useful.

Validate the structure against real user journeys

Before adopting the output, test whether key journeys are easy:

• first-time visitor to product understanding
• comparison shopper to decision page
• SEO visitor from article to product intent
• existing customer to docs or support
• partner prospect to integrations details

If those journeys feel awkward, the site-architecture needs another iteration even if the sitemap looks clean.

Improve site-architecture by narrowing the audience

Broad audiences create muddy architecture. If your first output tries to serve everyone, split priorities:

• buyer vs user
• SMB vs enterprise
• prospect vs customer
• educational content vs conversion content

The site-architecture skill improves significantly when audience priority is clear, because navigation and page grouping become easier to defend.