AGENTS.md Writer: Agent Skill (SKILL.md) for Claude Code, Codex and Cursor

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.

Prompt

Installs to .agents/skills/agents-md-writer-agent-skill-skill-md-for-claude-code-codex-and/

mkdir -p .agents/skills/agents-md-writer-agent-skill-skill-md-for-claude-code-codex-and && curl -sL "https://prompts-gpt.com/prompts/agents-md-writer-agent-skill-skill-md-for-claude-code-codex-and-cursor/raw" -o .agents/skills/agents-md-writer-agent-skill-skill-md-for-claude-code-codex-and/SKILL.md
SKILL.md
Preview
---
name: agents-md-writer-agent-skill-skill-md-for-claude-code-codex-and
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."
---

# AGENTS.md Writer: Agent Skill (SKILL.md) for Claude Code, Codex and Cursor

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.

## Prompt

```
---
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)
```
```

## Usage Notes

Save as .claude/skills/agents-md-writer/SKILL.md in one project (or ~/.claude/skills/agents-md-writer/ for all of them); Codex reads .agents/skills/agents-md-writer/SKILL.md. Then ask for the job in plain words and the agent loads it. Or install with: npx skills add prompts-gpt/skills --skill agents-md-writer.

Example output

At a glanceWhat the generated AGENTS.md covers for tidepool-apiExample: Python/FastAPI repo with an outdated CLAUDE.md
Commands listed
9 commands
Install, test, lint, format, typecheck, migrations
Directories mapped
7 folders
api, services, models, schemas, jobs, migrations, tests
Gotchas recorded
4 gotchas
Local Postgres, slow test, generated schemas, docs
Changes from old CLAUDE.md
6 changes
pip to uv, Flask notes removed, CLAUDE.md imports AGENTS.md

Example for: a Python/FastAPI repo, "tidepool-api", with an outdated CLAUDE.md and no AGENTS.md.

# AGENTS.md

## Project
Tidepool API: FastAPI backend for a marine-sensor dashboard. Postgres via SQLAlchemy 2.0, background jobs on Celery + Redis.

## Commands
- Install: uv sync
- Dev server: uv run uvicorn tidepool.main:app --reload
- Test all: uv run pytest
- Test one file: uv run pytest tests/readings/test_ingest.py
- Lint: uv run ruff check .
- Format: uv run ruff format .
- Typecheck: uv run mypy src/
- Build image: docker build -t tidepool-api . (unverified: Docker not available in survey environment)
- Migrations: uv run alembic upgrade head. ⚠️ Run only against your local DB, never the shared staging URL.

## Layout
- src/tidepool/api/: route modules, one file per resource
- src/tidepool/services/: business logic; routes call these, never the DB directly
- src/tidepool/models/: SQLAlchemy models
- src/tidepool/schemas/: Pydantic request/response models
- src/tidepool/jobs/: Celery tasks
- migrations/: Alembic revisions
- tests/: mirrors src/tidepool/ layout

## Conventions
- Put DB access in services/, not in route handlers.
- Raise errors from tidepool.errors (e.g. NotFoundError); the handler in main.py maps them to HTTP codes.
- Log with `get_logger(__name__)` from tidepool.log, not print or logging.getLogger.
- Name test files test_<module>.py and use fixtures from tests/conftest.py (db_session, client).
- Timestamps are UTC-aware datetimes; use tidepool.time.utcnow().

## Do
- Add an Alembic revision for every model change: uv run alembic revision --autogenerate -m "...".
- Keep Pydantic schemas separate from ORM models.

## Don't
- Edit migrations that are already merged to main; add a new revision instead.
- Call Celery tasks synchronously in routes; use .delay().
- Add dependencies with pip; use uv add.

## Gotchas
- Tests need DATABASE_URL pointing at a local Postgres; copy .env.example to .env.
- tests/jobs/test_retention.py is slow (~40s); skip with -m "not slow".
- src/tidepool/schemas/generated/ is produced by scripts/gen_schemas.py. Don't hand-edit it.
- Deeper schema rules: see docs/data-model.md.
# CLAUDE.md
@AGENTS.md

- Use plan mode before touching migrations/.

Changes from the old CLAUDE.md

  • Replaced pip install -r requirements.txt with uv sync, because requirements.txt was deleted and uv.lock is now the source.
  • Changed the test command from python -m pytest tests to uv run pytest, since the old one fails without the venv.
  • Removed "use black and isort" because Ruff now handles formatting and import order through CI.
  • Removed the Flask blueprint notes. The app moved to FastAPI.
  • Kept the owner's note about not editing merged migrations and moved it under Don't.
  • Moved the content into AGENTS.md and made CLAUDE.md import it.
Written by AI from this prompt. Your results will vary.

Save as .claude/skills/agents-md-writer/SKILL.md in one project (or ~/.claude/skills/agents-md-writer/ for all of them); Codex reads .agents/skills/agents-md-writer/SKILL.md. Then ask for the job in plain words and the agent loads it. Or install with: npx skills add prompts-gpt/skills --skill agents-md-writer.

Make it repeatable

Keep using this prompt without pasting it in every time.

Prompt details

By
Prompts-GPT editors
Published
How prompts are written and checked

Did this prompt work?

Keep exploring

More in AI Coding Agents