what is this
A registry of patterns
patterns.directory is a registry of patterns: installable, searchable definitions of how a project is structured — so you and your coding agent stop re-deciding the layout on every project and every session.
← back to the directory01the gap
The category nobody filled
Look at what the ecosystem already packages. skills.sh packages skills. shadcn packages components. Other registries package agents, prompts, MCP servers. The unit keeps getting smaller and sharper.
But none of them package the thing a project actually is. Not the buttons. Not the helpers. The structure: the folder layout and the architecture that lives inside it. The decisions you make in the first ten minutes and then re-make, badly, for the rest of the project's life.
That is the missing primitive. A skill is a capability. A component is a part. A pattern is the shape everything else has to fit into — and until now it shipped with nothing.
02the cost
What guessing costs
The agent does not know where each thing goes, so it guesses. To guess well it reads — your tree, your existing files, your half-stated conventions. Reading burns tokens, and every token of inference is another chance to hallucinate a path, a name, a layer that was never there.
This is the tax. Tokens spent re-deriving what the project already decided. Hallucinations dressed as conventions. Then the session ends, the context is gone, and the next one starts from zero — dropping the same logic in a slightly different place, contradicting last week's choice, duplicating what already exists until the codebase holds many local answers and no shared one.
No single step is wrong. Each file, read on its own, looks fine. That is the trap: locally correct, globally incoherent. Vibe-code sprawl. The project grows and its shape dissolves, because nothing ever told the agent what the shape was supposed to be.
03the unit
A pattern is an architecture you install
A pattern is a small repository that carries a structure — the folders, the rules, the recipes, the reasoning — packaged so a human and an agent can both read it and put code in the right place from the first line. You install it the way you install anything else from git.
Every pattern is identified by a ref: owner/repo, or owner/repo/sub when one repo holds more than one. The ref is the handle — unique, stable, the thing you search for and the thing you install. The display name is just for humans; the ref is what the system trusts.
04the anatomy
Inside a pattern
A pattern is a handful of files, and each one has a job. patterns.yaml is the only structured file — everything else is plain markdown, split by who reads it and what it does: describe the structure, constrain it, act on it, justify it.
05the spine
patterns.yaml is the entry point
patterns.yaml is the one structured file, and the entry point for progressive disclosure — read first, before any of the heavier docs.
It carries metadata plus an index of what each folder contains. It is what the registry reads to index the pattern into search, and what the agent reads first — to learn what exists, where it lives, and how to use it — before pulling the rest.
Nothing here is the architecture itself. It is the map. The structure, the rules, the recipes are revealed at install time, not search time — so search stays cheap and the agent only loads the weight when it actually builds.
name: Hexagonal API
ref: acme/hexagonal-api
stack: [typescript, nestjs, postgres]
description: Ports-and-adapters layout for a NestJS service.
contents:
structure: [domain.md, schema.md]
rules: [naming-conventions.md]
recipes: [add-http-request.md, add-event-listener.md]
adrs: [0001-ports-and-adapters.md]06two halves
Discovery and distribution
The system splits in two, and they meet at the ref. Distribution is git-native: a pattern lives in its own repository, you install it straight from git, no account, nothing uploaded. Discovery is this site — a public page and a GET /api/search over the Index, so you can find a ref before you install it.
Publishing belongs to the discovery half, and it is light. You do not upload your pattern; you register its ref. The service reads that ref's patterns.yaml from git, validates it, and upserts a single row. The Index is a Postgres-backed, derived cache of each pattern's searchable identity — name, description, stack, ref, popularity — rebuildable from its ref at any time. The source of truth never leaves your repo; the Index only points at it.
07How it works
Find
Search the Index for a pattern whose structure fits the project you are starting.
$ npx patterns find <query>Add
Pull a pattern into your project straight from its git repo — no account, nothing to upload.
$ npx patterns add owner/repoBuild
Scaffold from what you added, so you and your agent start with the structure already in place.
$ npx patterns initPublish
Submit your pattern's ref. The service reads its patterns.yaml, validates it, and indexes one row — no upload.
the thesis
Today, structure is not aesthetics. It is cost, precision, speed, and scalability.
08Get started
Find a ref. Build.
Discovery is the read side: search the Index here, find the ref you want, then hand it back to the git-native CLI to install. The structure lives in the repo — this is just how you find it.
$ npx patterns find <query>