Update AGENTS.md
This skill follows a two-file convention: AGENTS.md is the single source of truth, and CLAUDE.md is a one-line pointer containing exactly @AGENTS.md. pi reads AGENTS.md directly; Claude Code reads CLAUDE.md, which imports it. Maintain AGENTS.md — never duplicate content across the two files.
Steps
- Ground yourself in the repo — don't invent:
- Stack: read
package.json (dependencies + scripts), the lockfile (bun/pnpm/npm — tells you the package manager), framework config, tsconfig, and linter/formatter config.
- Layout: list the real top-level and
src/ dirs; open a few to learn what each actually holds.
- Conventions: infer from existing code — import alias, state/data libraries, auth, testing, formatting — and cite real paths.
- Write/refresh
AGENTS.md using the skeleton below. Keep it dense and specific: every line should save an agent a lookup. No filler, no restating generic framework docs.
- Ensure
CLAUDE.md is exactly @AGENTS.md (create or replace). If CLAUDE.md already holds real content and there's no AGENTS.md, migrate that content into AGENTS.md first, then reduce CLAUDE.md to the one-line pointer.
- Preserve tool-managed blocks verbatim — e.g.
<!-- BEGIN:nextjs-agent-rules -->…<!-- END:nextjs-agent-rules --> is rewritten by next dev. Keep it in place and commit it with your changes (removing it only re-creates an uncommitted diff).
Section skeleton (AGENTS.md)
## Stack
- framework + versions, package manager, db/orm, auth, styling, state, lint/format — one bullet each, real versions
## Repo Layout
- `dir/` — what lives here and the one rule an agent must know (cite real paths)
## Runtime Patterns
- how requests / data / sessions actually flow; the non-obvious wiring
## Conventions
- import alias, where to add X before creating new, naming, do / don't
## Agent Behavior
- repo-specific rules: what to run before committing, what never to touch, gotchas
Guardrails
- Match the terseness of the repo's existing AGENTS.md files (~40–110 lines). If it's growing long, cut — link to code instead of explaining it.
- Never document a path or pattern you haven't verified in the tree (e.g. don't reference an old
sessions.ts if the code now lives in src/lib/sessions/).
- No license boilerplate, no table of contents, no "this file provides guidance" preamble.
- Leave committing/PRs to the
commit / ship skills.
1---2name: update-agents-md3description: Generate or refresh a repo's AGENTS.md (the source-of-truth agent context file) and its one-line CLAUDE.md pointer. Use when the user says 'update the claude.md', 'update AGENTS.md', 'analyze this project and update the context file', 'write an AGENTS.md', or after a stack/structure change makes the current file stale.4---56# Update AGENTS.md78This skill follows a two-file convention: **`AGENTS.md` is the single source of truth**, and **`CLAUDE.md` is a one-line pointer** containing exactly `@AGENTS.md`. pi reads `AGENTS.md` directly; Claude Code reads `CLAUDE.md`, which imports it. Maintain AGENTS.md — never duplicate content across the two files.910## Steps11121. **Ground yourself in the repo — don't invent:**13 - *Stack:* read `package.json` (dependencies + `scripts`), the lockfile (bun/pnpm/npm — tells you the package manager), framework config, `tsconfig`, and linter/formatter config.14 - *Layout:* list the real top-level and `src/` dirs; open a few to learn what each actually holds.15 - *Conventions:* infer from existing code — import alias, state/data libraries, auth, testing, formatting — and cite real paths.162. **Write/refresh `AGENTS.md`** using the skeleton below. Keep it dense and specific: every line should save an agent a lookup. No filler, no restating generic framework docs.173. **Ensure `CLAUDE.md` is exactly `@AGENTS.md`** (create or replace). If CLAUDE.md already holds real content and there's no AGENTS.md, migrate that content into AGENTS.md first, then reduce CLAUDE.md to the one-line pointer.184. **Preserve tool-managed blocks verbatim** — e.g. `<!-- BEGIN:nextjs-agent-rules -->…<!-- END:nextjs-agent-rules -->` is rewritten by `next dev`. Keep it in place and commit it with your changes (removing it only re-creates an uncommitted diff).1920## Section skeleton (AGENTS.md)2122```23## Stack24- framework + versions, package manager, db/orm, auth, styling, state, lint/format — one bullet each, real versions2526## Repo Layout27- `dir/` — what lives here and the one rule an agent must know (cite real paths)2829## Runtime Patterns30- how requests / data / sessions actually flow; the non-obvious wiring3132## Conventions33- import alias, where to add X before creating new, naming, do / don't3435## Agent Behavior36- repo-specific rules: what to run before committing, what never to touch, gotchas37```3839## Guardrails4041- Match the terseness of the repo's existing AGENTS.md files (~40–110 lines). If it's growing long, cut — link to code instead of explaining it.42- Never document a path or pattern you haven't verified in the tree (e.g. don't reference an old `sessions.ts` if the code now lives in `src/lib/sessions/`).43- No license boilerplate, no table of contents, no "this file provides guidance" preamble.44- Leave committing/PRs to the `commit` / `ship` skills.
therapys