Skill · Coding

agents-md-writer

Writes or refreshes a repo's AGENTS.md or CLAUDE.md from what's actually in the code: verified build, test and lint commands, a directory map, conventions, do and don't lists, and gotchas, kept under about 150 lines. Use when asked to create, write, update or clean up AGENTS.md, CLAUDE.md or agent instructions for a repo, or to 'set up this repo for Claude Code / Codex / Cursor'.

The skill itself. Agents read the name and description first and load the rest only when a task matches.

agents-md-writer/SKILL.md
---
name: agents-md-writer
description: "Writes or refreshes a repo's AGENTS.md or CLAUDE.md from what's actually in the code: verified build, test and lint commands, a directory map, conventions, do and don't lists, and gotchas, kept under about 150 lines. Use when asked to create, write, update or clean up AGENTS.md, CLAUDE.md or agent instructions for a repo, or to 'set up this repo for Claude Code / Codex / Cursor'."
---

# AGENTS.md writer

## Steps

1. Survey the repo before writing anything:
   - package scripts or Makefile targets: install, dev, test, lint, typecheck, build;
   - directory layout (top two levels) and where the entry points live;
   - conventions visible in the code: naming, file placement, error handling, test layout, import style;
   - existing docs: README, CONTRIBUTING, an older AGENTS.md or CLAUDE.md, .cursor/rules, CI config.
2. Check each command you plan to list by running it, or its cheapest safe form such as a single test file. Drop or fix any that fail. Don't run deploys, migrations against shared databases or anything destructive; list those with a warning instead.
3. Write the file with these sections, in order:
   - Project: one or two lines on what this is.
   - Commands: install, dev, test (all and single file), lint, typecheck, build.
   - Layout: a short map of key directories, one line each.
   - Conventions: rules seen in the code, written as instructions.
   - Do and Don't: short lists of things agents get wrong in this repo.
   - Gotchas: env vars needed, generated files not to edit, slow or flaky tests.
4. Point to docs instead of pasting them ("Schema rules: see docs/db.md").
5. When refreshing an existing file, check every line against the repo as it is now. Remove stale lines, fix commands that changed, and keep notes the owner wrote unless they're wrong. Summarize what you changed and why.
6. If the repo needs both files: Codex, Cursor and Copilot read AGENTS.md; Claude Code reads CLAUDE.md. Keep AGENTS.md as the source and make CLAUDE.md a line that imports it, `@AGENTS.md`, plus any Claude-only notes.

## Rules

- Under about 150 lines. Cut generic advice like "write clean code" or "add tests".
- Don't restate rules a linter, formatter or CI already enforces.
- Every command listed must run. Mark any you couldn't verify.
- Write rules as instructions ("Use the logger in src/log.ts, not console.log"), not descriptions.
- No secrets, tokens or internal hostnames.

## Example output

```
## Commands
- Install: pnpm install
- Test one file: pnpm vitest run src/cart/coupon.test.ts
- Typecheck: pnpm tsc --noEmit

## Don't
- Edit files in src/generated/ (run pnpm codegen instead)
```