ax-init
Skill96 starsChanged 2 days agoMITView on GitHub
Bootstrap a repository's agent layer - a short root AGENTS.md, a .scratch/ cross-session work area, and an optional docs/ skeleton. Run when starting a new repo or retrofitting an existing one for agent work.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- Contexera/dsh-agent-teamword for word, first seen Nov 8, 2026
Other versions1 project uses a version of this.
Word for word · 1
- Contexera/dsh-agent-team★ 96100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- .scratch/AGENTS.mdAGENTS.md
- ax-reviewSkill
- codebase-ablationSkill
- codebase-designSkill
- diagnosing-bugsSkill
- discussionSkill
- grillingSkill
- researchSkill
- scratch-reviewSkill
- tddSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 4 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 21
Read the top-level tree, then the smallest authoritative files: README.md, build manifests, test and lint config, existing architecture …
- Very specific: line 24
If the repo does not expose a fact, write > TODO: — never invent commands, architecture, or policies.
- Distinctive: line 37
Write it in the repository's dominant documentation language (translate the headings.
- Very specific: line 45
Add to .gitignore (create the entries.
- Very specific: line 52
Create the directories active/ and local/ (empty.
- Distinctive: line 61
Do not pre-create empty subsystem pages.
- Very specific: line 73
Every command in the generated files comes from the repo or is marked > TODO:.
- Very specific: line 78
Every ticket shown as ready has both completed blockers and information readiness: settled decisions, closed required reading, available …
- Very specific: line 80
If docs/ was created, every routing row points at a file that exists.
- Distinctive: line 81
All generated files use the repository's dominant documentation language consistently.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
ax-init
ax = agent experience: the layer an agent needs to work in a repository across sessions. This skill builds it:
| Piece | Role | Default |
Root AGENTS.md | Only the rules every task must know, plus routing. Loaded into every session, so it stays short (~60 lines) | always |
.scratch/ | Cross-session work items: design snapshots, research, tickets, reviews, and validation evidence — never an authority on current behavior | always |
docs/ skeleton | Maintained engineering docs: docs/README.md routing index + docs/AGENTS.md maintenance discipline | only when the repo warrants maintained docs |
The pattern is proven in real agent-driven repositories (Loom, dsh-agent-team): a fat root guide drowns every session, so the root file routes instead of explaining; in-progress work lives in .scratch/active/ where it can change hourly without polluting history; durable conclusions graduate into docs/ when the work closes.
Map the repository before writing
- Read the top-level tree, then the smallest authoritative files:
README.md, build manifests, test and lint config, existing architecture docs. - Infer the stack from real files (
package.json,Cargo.toml,pyproject.toml,go.mod,Makefile, CI config); prefer exact commands the repo already uses over ecosystem defaults. - Extract only durable contributor knowledge: purpose and scope, top-level directory responsibilities, build/test/lint/run commands, conventions, boundaries, secret-handling rules.
- If the repo does not expose a fact, write
> TODO:— never invent commands, architecture, or policies. - Greenfield repos: a new or empty repository has little to extract. Take facts from the session's plan and the user — stack choice, commands, boundaries — and write them as chosen conventions,
> TODO:whatever is not yet decided. The root file is then a statement of intent the code grows into, not a report of what exists; expect a tightening pass once the stack actually lands.
Write the root AGENTS.md
Short by design. Five parts, in this order:
- Scope and authority — what this repository is, in one short paragraph, then the authority order: source and tests define current behavior; maintained
docs/explains it;.scratch/is work history and never overrides either. - Reading discipline — start from the files a task names, expand by need, do not read the whole repo; route through
docs/README.mdwhen it exists. - Always-on constraints — at most ~8 rules every task genuinely needs: the build/test entrypoints, the few architecture guardrails that are easy to violate, commit discipline.
- Pointers — one line each for
docs/AGENTS.md(if present) and.scratch/AGENTS.md. - Nothing else. Long structure maps, per-command detail, and research history belong in
docs/and.scratch/, not in the file every session loads.
Write it in the repository's dominant documentation language (translate the headings; keep technical terms as-is). A greenfield repo has no dominant language yet — ask, or default to the conversation's language.
Create the .scratch work area
Copy assets/scratch-AGENTS.md to .scratch/AGENTS.md and assets/scratch-README.md to .scratch/README.md. The templates define the work-item structure (active/<work>/ with a continuation README, spec.md, tickets, materials, reviews, and validation), information authority, ticket readiness, stateless delegation, the closing lifecycle, and git tracking. DESIGN.md is read only as a legacy snapshot name. Keep the generic core stable across repositories; put genuine repository differences under ## Local conventions instead of rewriting shared rules. Templates are English; when the repository's documentation language is not, translate the prose while keeping the structure, heading order, and technical terms.
On a greenfield repo, the design work that follows initialization starts as an active/<work>/ item, not in docs/ — until source lands, active/ is the primary design authority (the template says so).
Add to .gitignore (create the entries; keep the file's existing content):
.scratch/active/
.scratch/local/Create the directories active/ and local/ (empty; local/ is ignored anyway).
Add the docs skeleton when warranted
Skip it for small repos — a root file plus .scratch/ is enough, and an empty routing index pointing at nothing is worse than no index. Create it when the repo already has (or will soon grow) multiple maintained docs — architecture pages, runbooks, domain models:
assets/docs-README.md→docs/README.md: task-based routing table ("you want to do X → read Y") plus a fact-ownership table (which document owns which class of fact). Fill rows from the repo's real documents; two honest rows beat ten stub rows.assets/docs-AGENTS.md→docs/AGENTS.md: maintenance discipline — one fact one home, a change that invalidates a documented fact updates the owning document in the same change, uncertain facts as> TODO:, no empty shells for modules that do not exist.
Do not pre-create empty subsystem pages. The skeleton is governance, not filler. A terminology or domain page is typically the first real page once terms stabilize — add it then, not empty.
Re-runs and retrofitting
Re-running on an already-initialized repository adds missing pieces — most often the docs/ skeleton once the repo grows into needing one — and never silently regenerates or overwrites files that already exist.
For an existing .scratch/AGENTS.md or .scratch/README.md, first compare it with the current asset. Report generic-core differences separately from the AGENTS file's ## Local conventions and the README's live open/archive index data. With the user's go-ahead, upgrade the generic core while preserving intentional local extensions and current index data; without that approval, change no existing file. A missing local-conventions section is not itself a reason to discard repository-specific rules: classify and preserve them in the proposed upgrade.
Never overwrite an existing root AGENTS.md. When one exists, read it, separate always-on rules from long-form explanation, and propose the restructure: rules stay in the root file, explanation moves to docs/ pages (create the skeleton in the same pass if it is missing), work-history notes move to .scratch/. Apply it only with the user's go-ahead, since the existing file may be load-bearing for other tooling.
Validation checklist
- Every command in the generated files comes from the repo or is marked
> TODO:. - Root
AGENTS.mdfits on one screen and contains no content that belongs indocs/or.scratch/. - The
.gitignoreentries are committed together with the skeleton, before anyactive/work could leak into a commit. .scratch/AGENTS.mdand.scratch/README.mdexist;.gitignorecoversactive/andlocal/without ignoring.scratch/archive/(verify withgit check-ignore).- An existing repository's template differences have been reported, and every remaining difference is an intentional local extension recorded under
## Local conventions. - Every ticket shown as
readyhas both completed blockers and information readiness: settled decisions, closed required reading, available access, and evaluable acceptance. - A fresh agent can route from the root guide to the scratch contract and tell what a worker receives, where review and acceptance evidence live, and who marks completion.
- If
docs/was created, every routing row points at a file that exists. - All generated files use the repository's dominant documentation language consistently.
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
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.

