---
description: When and how to update AGENTS.md, rules, and skills after new conventions
alwaysApply: true
---

# Maintaining agent docs

Rules and skills **load automatically** but **do not self-update**. Update them when the user establishes a durable convention.

## Update when the user says (or clearly means)

- "Remember this" / "Save as convention" / "Add to project rules"
- "Document this for future agents"
- "We always do X in this project" (and it is not already in rules/skills)

## Where to put new knowledge

| Kind of knowledge | Update |
|-------------------|--------|
| Always true, 1–5 bullets | `.cursor/rules/*.mdc` (pick existing file or create new, <50 lines) |
| Multi-step workflow | `.cursor/skills/{name}/SKILL.md` |
| Project map / onboarding | `AGENTS.md` (index only — link to rules/skills) |

## Do not auto-update when

- One-off task instructions ("fix this bug today")
- Experimental code not yet agreed as standard
- User did not ask to persist the pattern

## After updating

- Keep rules concise; split if a file grows past ~50 lines.
- Tell the user which file(s) changed in one sentence.

Use skill `.cursor/skills/capture-convention/` for the full workflow.