agentleFS
VercelKnown publishervercel/eve/apps/templates/marketing-team-eve-template/agent/subagents/seo/skills/site-architecture/SKILL.md

site-architecture

Skill5.9k starsChanged 4 days agoApache-2.0View on GitHub

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.

73 other projects use a version of this, 1 of them edited.

How people change it

All 1 edited versions we compared keep every one of its 1 rules.

Of the 1 edited version we compared: 1 keep every rule.

We split this file and each edited version into the rules they give an agent and match them by wording. A version that adds no rule of its own and has not changed since this file last did reads as an older text, so what it lacks is not counted as dropped. We keep no past texts of a file, so that is inferred, and an edited version that started from an older text still counts its gaps as drops.

Adopted by

Steady: 0 new projects took it in the last 4 weeks, none the 4 weeks before.thin data

Week of Sep 20: 0 new projectsWeek of Sep 27: 0 new projectsWeek of Oct 4: 0 new projectsWeek of Oct 11: 0 new projectsWeek of Oct 18: 0 new projectsWeek of Oct 25: 0 new projectsWeek of Nov 1: 0 new projectsWeek of Nov 8: 0 new projects
Sep 2026Oct 2026Nov 2026
New projects taking a version of this file each week, over the 8 weeks our latest run read: only 0 in all, so this is a hint, not a trend.

Most recently taken up by

Who's talking about vercel/eve

The biggest 5 of 57 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 57

Talked about on GitHub and Bluesky (57 times).

On GitHub · 50

45 more on GitHub

On Bluesky · 7

2 more on Bluesky

Used with

Projects with it also use popups, free-tools and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • CesarjoquinSkill

    popups

    When the user wants to create or optimize popups, modals, overlays, slide-ins, or banners for conversion purposes. Also use when the user mentions "exit intent," "popup conversions," "modal optimization," "lead capture popup," "email popup," "announcement banner," "overlay," "collect emails with a popup," "exit popup," "scroll trigger," "sticky bar," or "notification bar." Use this for any overlay or interrupt-style conversion element. For forms outside of popups, see cro. For general page conversion optimization, see cro.

    Also in 24 projects that use this

  • CesarjoquinSkill

    free-tools

    When the user wants to plan, evaluate, or build a free tool for marketing purposes — lead generation, SEO value, or brand awareness. Also use when the user mentions "engineering as marketing," "free tool," "marketing tool," "calculator," "generator," "interactive tool," "lead gen tool," "build a tool for leads," "free resource," "ROI calculator," "grader tool," "audit tool," "should I build a free tool," or "tools for lead gen." Use this whenever someone wants to build something useful and give it away to attract leads or earn links. For downloadable content lead magnets (ebooks, checklists, templates), see lead-magnets.

    Also in 25 projects that use this

  • coreyhaines31Skill

    marketing-council

    When the user wants several expert takes on a marketing decision, or asks what a famous marketer would say about it: a simulated board (Seth Godin, David Ogilvy, April Dunford, Byron Sharp, and more), each grounded in their documented frameworks, where they disagree, and a recommendation. To execute, hand off to the relevant skill.

    Also in 18 projects that use this

  • ukunal91appSkill

    community-marketing

    Build and leverage online communities to drive product growth and brand loyalty. Use when the user wants to create a community strategy, grow a Discord or Slack community, manage a forum or subreddit, build brand advocates, increase word-of-mouth, drive community-led growth, engage users post-signup, or turn customers into evangelists. Trigger phrases: "build a community," "community strategy," "Discord community," "Slack community," "community-led growth," "brand advocates," "user community," "forum strategy," "community engagement," "grow our community," "ambassador program," "community flywheel.

    Also in 35 projects that use this

  • Hussain-ElfalahSkill

    andreessen

    Also in 4 projects that use this

  • Hussain-ElfalahSkill

    business-investment-advisor

    Also in 4 projects that use this

  • +4 more from Cesarjoquin
  • +1 more from Hussain-Elfalah

The file

We split this skill into the rules it gives an agent

1 rule. 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 69 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    No orphans. Every page needs at least one internal link pointing at it, and the sitemap is not a link.

    line 58

“Common” is measured: kept by at least 6 in 10 of the 69 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

ShapeFitsCosts
Flat, 2 levelsSmall sites, portfoliosStops scaling once a nav item has 20 children
Moderate, 3 levelsMost SaaS and content sitesUsually the right answer
Deep, 4 or moreLarge catalogs, big docsScales, 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

TypeDepthSectionsURL shape
SaaS marketing2 to 3Home, Features, Pricing, Blog, Docs/features/{name}, /blog/{slug}
Content site2 to 3Home, Blog, Categories, About/blog/{slug}, /blog/category/{slug}
Ecommerce3 to 4Home, Categories, Products/{category}/{subcategory}/{product}
Documentation3 to 4Home, Guides, Reference/docs/{section}/{page}
SaaS plus content3 to 4Home, Product, Blog, Resources, Docs/product/{feature}, /blog/{slug}
Small business1 to 2Home, 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 mirror the URL path exactly, 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.

Sources

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.