Bootstrap a repository's AI coding agent operating system — AGENTS.md, CLAUDE.md, CONTEXT.md (domain language), docs/agents (architecture, code-style, lessons-learned), docs/plans, docs/release.md, and portable plan-mode/code-review skills — all rewritten from evidence gathered in the target repo. Use when setting up agent docs for a new or existing project. Triggers on "bootstrap agent system", "set up AGENTS.md", "port agent docs", "create agent operating system", "agent onboarding docs".
Bootstrap a repository's AI coding agent operating system — AGENTS.md, CLAUDE.md, CONTEXT.md (domain language), docs/agents (architecture, code-style, lessons-learned), docs/plans, docs/release.md, and portable plan-mode/code-review skills — all rewritten from evidence gathered in the target repo. Use when setting up agent docs for a new or existing project. Triggers on "bootstrap agent system", "set up AGENTS.md", "port agent docs", "create agent operating system", "agent onboarding docs".
license
MIT
metadata
{"version":"1.1.0","invocation":"both"}
Bootstrap Agent System
You are setting up this repository's AI coding agent operating system, modeled on a proven pattern. Port the system and doctrine, then rewrite all content for THIS repo based on evidence you gather here. Never paste product-specific details from another codebase unless they verifiably apply to this repo.
Goal
Give AI agents (Cursor, Claude Code, etc.) a single, living contract for how to work in this repo:
Root entrypoint docs (AGENTS.md + CLAUDE.md)
Root CONTEXT.md — the project's domain language (glossary + decisions)
Deeper agent docs under docs/agents/
Durable plans under docs/plans/
Release notes under docs/release.md
Project skills under the repo's skills directory (e.g. .agents/skills/)
Explicit rules that agents must use project scripts, keep docs living, and record lessons
Reference templates
This skill ships with templates in references/. Read each one when you reach the step that uses it:
Config first. If docs/agents/skills-config.md exists, read it before anything else — it records decisions already settled in the setup interview (harness, docs layout, tracker conventions, domain seeding). Never re-ask a decision recorded there. If the file does not exist (this skill was invoked directly), gather evidence and settle decisions yourself as described below.
Read these and take notes. Every claim in the docs you write must trace back to something you saw here:
package.json (root + each workspace): scripts, packageManager, workspaces
Lockfile(s): which package manager is actually in use
CI config (.github/workflows/, turbo.json, vercel.json, etc.): what "green" means
tsconfig.json / language configs: strictness flags agents must respect
Lint/format config (eslint, biome, oxlint, prettier, ultracite, etc.) and how it is invoked
Test setup: runner, file naming, colocation vs __tests__/
Existing docs: README.md, CONTRIBUTING.md, any existing AGENTS.md/CLAUDE.md/.cursor/rules — inventory overlaps so you consolidate instead of contradicting
Auth, database, migrations, deploy targets — only note what exists
If the repo already has a partial AGENTS.md or Cursor rules, merge — preserve unique local rules, deduplicate, and keep one source of truth. When merging surfaces contradictions, or you hit a choice only the user can own (docs layout, tracker conventions, which harness to target), collect those decisions and run them as one interview per the frontier-interview skill instead of asking ad hoc.
Deliverables
AGENTS.md # root entrypoint (living document)
CLAUDE.md # symlink -> AGENTS.md
CONTEXT.md # domain language: glossary + decisions (living document)
docs/
agents/
architecture.md # real system map, written from evidence
code-style.md # this repo's actual conventions
lessons-learned.md # seeded, append-only knowledge base
plans/
README.md # how durable plans work here
release.md # how THIS project ships
.agents/
skills/
plan-mode/SKILL.md # portable doctrine (references/skill-plan-mode.md)
code-review/SKILL.md # portable doctrine (references/skill-code-review.md)
<stack skills as applicable>
Process (in order)
Phase 0 evidence gathering (checklist above)
Write docs/agents/architecture.md and docs/agents/code-style.md from evidence, using the corresponding templates as structure
Write AGENTS.md from references/agents-md-template.md; then symlink: ln -sf AGENTS.md CLAUDE.md. If symlinks are not viable (e.g. Windows contributors without dev-mode), create CLAUDE.md containing only: See AGENTS.md — single source of truth.
Seed CONTEXT.md from references/context-md-template.md: extract candidate terms from schema/module names, README prose, and existing docs, then confirm definitions and capture head-only terms in one interview round (per the frontier-interview skill; skip the round if docs/agents/skills-config.md records domain seeding as done). In a greenfield repo the interview is the domain-modeling session
Add docs/release.md, docs/plans/README.md, and seed docs/agents/lessons-learned.md from their templates
Create .agents/skills/plan-mode/SKILL.md (verbatim from references/skill-plan-mode.md, stripping the template preamble) and .agents/skills/code-review/SKILL.md (from references/skill-code-review.md, adapting commands to this repo)
Add stack-specific skills only if the dependency is verified in package.json (AI SDK, workflow/durable-execution, React best practices, etc.). Do NOT port product-specific skills from other codebases. If the repo has a frontend (react/next/vue/svelte/tailwind verified in package.json), follow the design-md skill to create DESIGN.md and .agents/skills/frontend-design/ — it classifies the repo first and never overwrites an existing design language.
Run the verification pass below
Report a short summary: files created, what was adapted vs skipped, conflicts found with existing docs, recommended next skills for this stack
Operating doctrine (must be encoded in AGENTS.md + skills)
Living docs — when an agent is wrong or learns a non-obvious invariant, it appends to docs/agents/lessons-learned.md, ideally in the same change
Living language — when a change coins or clarifies a domain term, or settles a directional decision, it updates CONTEXT.md in the same change
Scripts over raw tools — discover commands from AGENTS.md / package.json before running generic tsc / eslint / etc.
Plan before large changes — plan-mode doctrine for multi-file/architectural work; durable plans in docs/plans/
Separation of concerns — extract colocated modules instead of growing god-files
Verify with project CI — after changes, run the repo's canonical check script
Don't invent architecture — document what exists; if unclear, explore and ask
Re-runs, stamps, and owned files
Stamp every emitted artifact. The first line of every file this skill creates is <!-- generated by bootstrap-agents-md v<version> --> (version from this skill's frontmatter). In emitted SKILL.md files, place the stamp immediately after the frontmatter.
Ownership by stamp. On re-run, a file carrying this skill's stamp may be updated — but living content the user or other agents added since (lessons, glossary terms, decisions, local rules) is always preserved, never regenerated away. A file without this skill's stamp is not yours: merge into it in place; never overwrite it and never create a duplicate beside it.
Delimited blocks in shared files. When inserting more than one line into a file you don't own, wrap the insertion in <!-- BEGIN generated: bootstrap-agents-md --> / <!-- END generated: bootstrap-agents-md --> and touch only what's inside those markers on re-run. Single-line insertions (e.g. a Quick Links entry) are idempotent instead: check for presence, add if absent.
Verification pass (required before finishing)
Every command listed in AGENTS.md exists in package.json scripts (or is a real workspace tool invocation) — run each read-only one to confirm
Every relative link in AGENTS.md and docs/agents/* resolves to an existing file
CLAUDE.md resolves to AGENTS.md content (cat CLAUDE.md)
Every term in CONTEXT.md was extracted from this repo or confirmed by the user — none invented; code anchors resolve
No section in any doc describes something you did not verify in this repo
No contradictions with pre-existing docs (README, CONTRIBUTING, lint configs)
AGENTS.md is scannable in under a minute (~100 lines)
Every emitted file carries this skill's generation stamp; no file without the stamp was overwritten
Constraints
Do not copy another product's architecture (web/agent/sandbox splits, specific auth providers, database branching setups, etc.) unless verified in THIS repo
Prefer accurate short docs over impressive long docs — an agent that trusts a wrong doc is worse than one with no doc
No secrets or env values in docs; reference .env.example instead
Match this repo's markdown tone and formatting
If the target already has a partial AGENTS.md, merge carefully rather than overwriting unique local rules
Done when
An agent opening this repo can find commands, architecture, style, and lessons within one hop from AGENTS.md
CLAUDE.md resolves to the same content
Plan and review workflows exist as skills
Every doc statement is evidence-backed and the verification pass is clean
