# Bootstrap Agents Md

> Bootstrap a repository's AI coding agent operating system — AGENTS.md, CLAUDE.md, 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".

- Skill: `nolly-studio/bootstrap-agents-md-3` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add nolly-studio/bootstrap-agents-md-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nolly-studio/bootstrap-agents-md-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: nolly-studio (https://skillmd.com/u/nolly-studio)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/nolly-studio/bootstrap-agents-md-3

---


# 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:

1. Root entrypoint docs (`AGENTS.md` + `CLAUDE.md`)
2. Deeper agent docs under `docs/agents/`
3. Durable plans under `docs/plans/`
4. Release notes under `docs/release.md`
5. Project skills under the repo's skills directory (e.g. `.agents/skills/`)
6. 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:

| File | Used for |
|------|----------|
| `references/agents-md-template.md` | `AGENTS.md` skeleton |
| `references/architecture-template.md` | `docs/agents/architecture.md` |
| `references/code-style-template.md` | `docs/agents/code-style.md` |
| `references/lessons-learned-template.md` | `docs/agents/lessons-learned.md` |
| `references/plans-readme-template.md` | `docs/plans/README.md` |
| `references/release-template.md` | `docs/release.md` |
| `references/skill-plan-mode.md` | `.agents/skills/plan-mode/SKILL.md` (create verbatim) |
| `references/skill-code-review.md` | `.agents/skills/code-review/SKILL.md` (adapt commands) |

## Phase 0: Gather evidence (before writing anything)

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
- [ ] Directory layout: apps, packages, primary data/control flow

If the repo already has a partial `AGENTS.md` or Cursor rules, **merge** — preserve unique local rules, deduplicate, and keep one source of truth.

## Deliverables

```
AGENTS.md                          # root entrypoint (living document)
CLAUDE.md                          # symlink -> AGENTS.md
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)

1. **Phase 0** evidence gathering (checklist above)
2. Write `docs/agents/architecture.md` and `docs/agents/code-style.md` from evidence, using the corresponding templates as structure
3. 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.`
4. Add `docs/release.md`, `docs/plans/README.md`, and seed `docs/agents/lessons-learned.md` from their templates
5. 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)
6. 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.
7. Run the **verification pass** below
8. 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)

1. **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
2. **Scripts over raw tools** — discover commands from `AGENTS.md` / `package.json` before running generic `tsc` / `eslint` / etc.
3. **Plan before large changes** — plan-mode doctrine for multi-file/architectural work; durable plans in `docs/plans/`
4. **Separation of concerns** — extract colocated modules instead of growing god-files
5. **Verify with project CI** — after changes, run the repo's canonical check script
6. **Don't invent architecture** — document what exists; if unclear, explore and ask

## 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`)
- [ ] 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)

## 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