# Bootstrap agent context

> For coding agents: fetch this file, interview the human, then write `AGENTS.md` and optional `.agents/skills/`. Do not invent product decisions.

You are setting up durable agent context for a software repo. The goal is a thin, accurate instruction layer that survives a fresh chat. Auto-generated AGENTS.md files full of guessed conventions fail that test. Ask the human; write what they confirm.

## When to use

- Greenfield or existing repo with no `AGENTS.md` (or a useless auto-scaffold)
- Human asks to "set up Cursor / Codex / OpenCode context," "add skills," or "fix agent instructions"
- Repo has conflicting vendor files (`CLAUDE.md`, `.cursor/rules`, …) and needs one source of truth

## When not to use

- Human only wants a one-off task done; they did not ask for lasting project instructions
- You lack access to ask questions and the repo already has a clear, maintained `AGENTS.md`
- The request is "generate skills for everything" with no task boundary — push back and scope

## Standards (source of truth)

Use these open formats. Ignore vendor-only layouts as canonical.

| Concern | Standard | Location |
| --- | --- | --- |
| Project instructions | [AGENTS.md](https://agents.md/) | Repo root; nested `AGENTS.md` in packages if needed |
| Reusable workflows | [Agent Skills](https://agentskills.io/specification) | `.agents/skills/<name>/SKILL.md` |
| Site discovery for agents | [llms.txt](https://llmstxt.org/) | Site `/llms.txt` linking to clean `.md` pages (websites) |

Cursor, Codex, OpenCode, and others read `AGENTS.md` and `.agents/skills/`. If a tool also wants `CLAUDE.md` or `.cursor/rules`, derive or symlink from the standards above. Do not maintain two conflicting sources.

## Interview first

Ask in small batches (3–5 questions). Prefer concrete choices over open essays. Record answers before writing files.

### Product and boundaries

1. What is this project for, in one or two sentences?
2. Who is the user / audience? Who is *not*?
3. What must never appear (employer, pricing, PII, vendor lock-in, …)?
4. Explicit out-of-scope features or pages?

### How agents should work here

5. Required commands: install, dev, test, lint, build? Split **local development** (Windows/macOS/desktop) from **production/server** (Linux, systemd, cron, deploy) when they differ.
6. Non-negotiable engineering rules (language version, no force-push, commit only when asked, …)?
7. Tone for UI copy and docs (formal, neutral, terse)?
8. Files or dirs agents must not touch?

### Skills

9. Recurring workflows worth a skill (design QA, release, schema migrate)? Name the trigger in plain language.
10. Is that skill shared by the whole team (lives in the repo) or only useful to this developer (personal/global skill)?
11. Anything that should stay as a short section in `AGENTS.md` instead of a skill?

If the human is unsure, propose defaults labeled as drafts and wait for confirmation. Do not silently fill gaps with industry clichés.

You may glance at the repo so your questions are not naive — but **do not** turn detected files into answers. Seeing `package.json` or `requirements.txt` does not authorize writing stack, commands, or conventions into `AGENTS.md`. Ask; wait for a yes. Pre-checked multiple-choice menus inferred from the tree recreate the auto-generated AGENTS.md failure mode this playbook exists to prevent.

## Write AGENTS.md

Plain Markdown. No required schema. Put decisions agents need on every task; leave one-off tutorials out.

**Size budget:** aim for under ~150–200 lines. Longer files crowd the context window on every turn and humans stop maintaining them. If you need more room, move procedures into skills and keep `AGENTS.md` as the index of decisions.

Recommended shape (adapt names to the project):

1. **Identity** — what the product is; anonymity / branding constraints
2. **In scope / out of scope** — falsifiable lists
3. **Stack** — fixed choices ("Astro + FastAPI"), not a catalog of alternatives
4. **Commands** — copy-pasteable lines, split when environments differ:
   - **Local development** — what contributors run on their machine (install, dev server, test, lint)
   - **Production / server** — what runs on the host (deploy, systemd units, cron, bash one-liners, Docker compose in prod)
   Do not collapse both into one list if OS or tooling diverge (e.g. PowerShell vs bash, launchd vs systemd).
5. **Conventions** — only rules you would correct a teammate for breaking
6. **Safety** — secrets, prod data, destructive git operations
7. **Pointers** — where skills live; link to external playbooks if useful

Keep it short enough that a human will maintain it. Nested `AGENTS.md` in monorepo packages for package-local rules; nearest file wins for conflicts.

### What belongs elsewhere

| Content | Put it in |
| --- | --- |
| Multi-step workflow with scripts or long references | Skill under `.agents/skills/` |
| Human onboarding / marketing story | `README.md` |
| API reference | Docs site or `llms.txt` + `.md` pages |

## Write skills (when earned)

Create a skill only when the agent needs a repeatable procedure that would bloat `AGENTS.md`.

For a full interview → write loop focused on one skill (open standard, not a vendor skill-creator), use [Author an Agent Skill](https://qwertylab.dev/tools/skill-author.md).

### Project vs personal scope

| Scope | Location | Put it here when |
| --- | --- | --- |
| **Project** (shared) | `.agents/skills/` in the repo | Any teammate (or any agent session on this repo) should follow the same workflow |
| **Personal / global** | User-level skills dir for that tool (often `~/.agents/skills/` or the vendor equivalent) | The flow is one developer's habit, editor taste, or machine-specific setup |

Default to **project** only for workflows the product actually needs. Do not commit personal lint preferences, private release checklists, or one-person shortcuts into the repo — that bloats checkout for everyone. If unsure, ask: "Should every contributor's agent load this, or only you?"

```text
.agents/skills/<skill-name>/
├── SKILL.md          # required
├── scripts/          # optional
├── references/       # optional; load on demand
└── assets/           # optional
```

`SKILL.md` frontmatter (portable fields only):

```yaml
---
name: skill-name
description: What it does and when to use it. Include trigger keywords.
---
```

Rules:

- `name` matches the folder; lowercase, digits, single hyphens
- `description` must tell the agent *when* to load the skill
- Keep the body under ~500 lines; move detail into `references/`
- Skip vendor-only frontmatter (`paths`, `allowed-tools`, Codex UI yaml) in the portable skill unless the human asks for a vendor fork
- Progressive disclosure: metadata always visible; full body only when relevant; references only when needed

## Anti-patterns

- Pasting a "universal" AGENTS.md template with unchecked boxes (especially past the ~150–200 line budget)
- Encoding taste ("use beautiful code") instead of observable rules
- Duplicating the same rules into `CLAUDE.md`, `.cursorrules`, and `AGENTS.md`
- Skills that are always-on essays with no clear trigger
- Inventing stack or product claims the human never stated — including "answers" inferred from `package.json`, lockfiles, or folder layout without confirmation
- Dumping personal/global skills into `.agents/skills/` so the repo carries one developer's private workflows
- Committing secrets, `.env` samples with real keys, or prod URLs into agent docs

## Verification

1. Show the human a short summary of decisions you captured; get a yes before large writes
2. Write or update `AGENTS.md` (and only the **project** skills agreed — personal skills go outside the repo)
3. Re-read the files you wrote; fix contradictions with the interview; if `AGENTS.md` is drifting past ~200 lines, split into skills
4. Smoke test: in a fresh agent turn (or tell the human to), give only `AGENTS.md` and ask "what is out of scope?" — the answer must match the file
5. Reminder: treat `AGENTS.md` as living docs; update it when product decisions change

## Minimal command sequence

```text
1. List existing AGENTS.md, .agents/skills/, and vendor instruction files
2. Interview (batch questions)
3. Confirm summary with human
4. Write AGENTS.md
5. Add only the skills the human approved
6. Verify by re-reading + one scope question
```

## References

- AGENTS.md: https://agents.md/
- Agent Skills specification: https://agentskills.io/specification
- llms.txt: https://llmstxt.org/