# Weisberg Agent Tools Codex Md Author > AGENTS.md Authoring Skill - Skill: `tomevault-io/weisberg-agent-tools-codex-md-author` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/weisberg-agent-tools-codex-md-author` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/weisberg-agent-tools-codex-md-author/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/weisberg-agent-tools-codex-md-author --- # AGENTS.md Authoring Skill This skill guides the creation and refinement of AGENTS.md files — the persistent memory layer that transforms Codex from a generic coding assistant into a project-aware expert. A great AGENTS.md is **dense with signal, stripped of noise, and structured for instant utility**. The user provides some combination of: a request to create a AGENTS.md from scratch, an existing AGENTS.md to improve, a codebase to analyze, or a description of their project. --- ## What AGENTS.md Files Are (And Why They Matter) AGENTS.md files are Markdown files that Codex reads **automatically at the start of every session**. They inject project-specific knowledge into Codex's context window before a single message is exchanged. This means Codex arrives already knowing the architecture, conventions, commands, and current state of the project — not because of training, but because the AGENTS.md told it so. The magic is simple: **every token in a AGENTS.md is worth orders of magnitude more than the same token in a chat message**, because it applies to the entire session and shapes every action Codex takes. A project *without* a AGENTS.md forces Codex to rediscover the same things over and over. A project *with* a great AGENTS.md lets Codex hit the ground running, make fewer mistakes, and operate as if it's been on the team for months. --- ## The AGENTS.md Ecosystem Understanding the file hierarchy is essential for proper placement and scoping: **Discovery order** (all are loaded and concatenated): 1. `~/.Codex/AGENTS.md` — User-level, applies to every project on the machine. Ideal for personal conventions, preferred tools, global aliases, API keys patterns, etc. 2. `./AGENTS.md` (project root) — Project-wide context. The primary file. 3. `./Codex.local.md` (project root) — Local overrides, gitignored by convention. For machine-specific paths, personal API keys, local dev notes that shouldn't be committed. 4. `{subdirectory}/AGENTS.md` — Subsystem-specific guidance. Loaded when Codex is working in or near that directory. Use for monorepos, distinct modules, or specialized subsystems. **Import syntax** — Any AGENTS.md can inline another file: ``` @path/to/file.md @docs/architecture.md @.env.example ``` This is powerful: pull in living documentation, actual config files, or schema definitions rather than duplicating them. The referenced file's content appears inline at that position. **Size guidance**: Aim for the root AGENTS.md to be under 200 lines. Every line competes for context window space. Ruthless editing is a feature, not a failure. --- ## Anatomy of a Great AGENTS.md The best AGENTS.md files share a consistent structure. Not all sections are required for every project — include what's genuinely useful, omit what isn't. ### 1. Project Identity (2–5 lines) One tight paragraph: what is this project, what does it do, who uses it. This orients Codex immediately and shapes how it interprets everything that follows. ```markdown # ProjectName A TypeScript monorepo powering the customer-facing API and internal admin tooling for Acme Corp's B2B SaaS platform. Serves ~500 enterprise clients via REST API with ~2M req/day. Built by a team of 8, deployed to AWS via CDK. ``` **Anti-patterns**: Do not write a marketing pitch. Do not describe business history. One sentence about the domain, one about the technical reality. ### 2. Tech Stack Explicit enumeration of languages, frameworks, key libraries, and infrastructure. Be specific about versions only when version-specific behavior matters. ```markdown ## Stack - **Language**: TypeScript 5.3, Node 20 (ESM throughout — no CommonJS) - **Framework**: Fastify (not Express — different plugin model) - **ORM**: Drizzle (not Prisma — raw SQL when Drizzle won't do) - **Testing**: Vitest + @testing-library/react for components - **DB**: PostgreSQL 15 via RDS; Redis for cache/queues - **Infra**: AWS CDK (TypeScript), deployed via GitHub Actions ``` Note how each entry calls out what was *chosen over* the obvious alternative. This prevents Codex from recommending Prisma in a Drizzle project. ### 3. Essential Commands Every command Codex might need to run. Exact, copy-pasteable. No paraphrasing. ```markdown ## Commands ```bash pnpm install # install deps (pnpm only — npm/yarn break lockfile) pnpm dev # start all services with hot reload (uses Turborepo) pnpm build # production build pnpm test # run all tests pnpm test:watch # watch mode pnpm lint # ESLint + Prettier check pnpm lint:fix # auto-fix lint errors pnpm db:migrate # run pending migrations pnpm db:generate # generate Drizzle schema from DB pnpm typecheck # tsc --noEmit (no build output) ``` ``` **Critical**: Include the "don't do this" commands too: ```markdown > ⚠️ Never run `pnpm db:reset` in production. Never commit `.env.local`. ``` ### 4. Architecture How the pieces fit together. This section has the highest ROI of anything in the file — it's the map Codex uses to navigate every task. ```markdown ## Architecture ### Monorepo Structure ``` apps/ api/ # Fastify REST API — the core backend admin/ # Internal React app (Vite) worker/ # BullMQ job processors packages/ db/ # Drizzle schema + migrations (source of truth for all DB types) shared/ # Types/utils shared across apps (no runtime deps allowed here) ui/ # Shared React component library ``` ### Request Lifecycle Client → ALB → api/src/routes → service layer (src/services) → db package → PostgreSQL. Auth happens in a Fastify hook before routes execute. Never do auth logic inside route handlers. ### Key Patterns - Services are plain async functions, not classes. - Route handlers are thin — they validate input (Zod), call a service, return the result. - All DB access goes through `packages/db`. No raw `pg` calls in app code. - Errors: throw typed errors from services; the global error handler in `api/src/app.ts` formats them. ``` ### 5. Code Conventions The house style. What's enforced, what's preferred, what's forbidden. This is where you encode the decisions that never appear in config files. ```markdown ## Conventions ### TypeScript - `strict: true` — no `any`, no `// @ts-ignore` without a comment explaining why - Prefer `type` over `interface` except for public API contracts - Zod schemas live next to the route that uses them (not in a central schema file) ### Naming - Files: `kebab-case.ts` - React components: `PascalCase.tsx` - DB tables: `snake_case` (Drizzle convention) - Env vars: `SCREAMING_SNAKE_CASE`, always validated at startup via `src/config.ts` ### Testing - Unit tests: `*.test.ts` alongside the source file - Integration tests: `tests/integration/` — require a running DB - Tests use real DB with per-test transactions that roll back. No mocking the DB layer. - Mock external HTTP calls using `msw`, not Jest mocks ### Git - Commits: Conventional Commits (`feat:`, `fix:`, `chore:`, etc.) - PRs require passing CI + 1 review - Never force-push to `main` or `develop` ``` ### 6. Critical Context (The Secret Weapon) This is the most valuable section and the most neglected. It captures **non-obvious knowledge** — the things that only a senior team member would know, the gotchas, the things that look wrong but are intentional, the dragons. ```markdown ## Critical Context ### Known Gotchas - **ESM + Drizzle**: Drizzle's `migrate()` must be called with `import.meta.url` not `__dirname`. Already handled in `packages/db/src/migrate.ts` — don't change this pattern. - **Worker service account**: The `worker` app runs as a different IAM role than `api`. It has S3 write access but NOT SQS receive (uses BullMQ/Redis instead). - **Timestamps**: All timestamps stored as UTC in PostgreSQL. The admin app displays in user's timezone using `date-fns-tz`. Never use `new Date()` for insertion — use `sql\`NOW()\``. - **CORS**: The `allowedOrigins` config in `api/src/app.ts` reads from env. In dev, `*` is fine. In prod, it must exactly match the CloudFront distribution URL (no trailing slash). ### Currently In Progress - The `packages/ui` component library is being extracted from `apps/admin`. Some components still live in admin — check both places before creating new ones. - Auth is mid-migration from JWT-in-cookie to Clerk. Both systems are live simultaneously. New features should use Clerk (`src/auth/clerk.ts`). Don't touch `src/auth/legacy-jwt.ts`. ### Known Broken / Deferred - `pnpm test` in `apps/worker` fails on CI due to a Docker networking issue. Tests pass locally. Skip with `pnpm test --ignore-fail` in CI (tracked in GH issue #482). ``` ### 7. External Services & Integrations What APIs and services this project talks to, where credentials live, what the dev/prod split looks like. ```markdown ## External Services | Service | Purpose | Dev credential source | Prod credential | |---------|---------|----------------------|-----------------| | Stripe | Billing | `.env.local` (test mode key) | AWS Secrets Manager | | SendGrid | Email | Mocked via `msw` in tests | AWS Secrets Manager | | Datadog | APM/Logs | Not configured locally | Set via CDK | | OpenAI | Embeddings | `.env.local` | AWS Secrets Manager | All secrets accessed via `src/config.ts`. Never access `process.env` directly outside that file. ``` --- ## Authoring Principles ### Signal-to-Noise Ratio Is Everything Every line must earn its place. Ask: "Would Codex do the wrong thing without this?" If no, delete it. **High signal** (include): Non-obvious choices, things that contradict common defaults, current state of in-progress work, commands that aren't in package.json scripts, things that broke before and could break again. **Low signal** (omit): Things Codex already knows (React is a UI library, git is version control), things obvious from the directory structure, things that live in config files Codex can read, marketing/mission statements. ### Write for a Smart New Hire, Not a Robot Imagine explaining the project to a senior engineer on their first day. They're smart — skip the basics. They're new — don't skip the tribal knowledge. Write the things you'd say at the whiteboard, not the things in the README. ### Use Opinions, Not Just Facts "We use Fastify" is fine. "We use Fastify (not Express) — the plugin system is fundamentally different; don't suggest Express patterns" is better. AGENTS.md should encode *why* decisions were made, not just *what* they are. ### Keep It Fresh A stale AGENTS.md is worse than none — it actively misleads. Establish a team norm: when you change a major convention, you update AGENTS.md in the same PR. When you complete a migration, remove the in-progress warning. ### Structure for Skimming Codex processes the file linearly but needs key facts to be findable quickly within a session. Use consistent H2/H3 headers. Lead sections with the most important information. Put warnings and gotchas in blockquotes or bold text so they read as emphatic. --- ## Codex.local.md — The Personal Layer This file is for machine-specific and developer-specific context. Gitignore it by default: ```gitignore Codex.local.md ``` Appropriate content: ```markdown # Local Overrides ## My Environment - DB runs on port 5433 (not 5432 — conflicting local Postgres instance) - I use `mise` for runtime management, not `nvm` - Local dev uses the staging Stripe key (not test mode) — careful with actual charges ## Personal Workflow Notes - I keep a running `scratch.ts` in the root for experiments — never commit this - Turborepo remote cache is disabled on this machine (run `pnpm build --no-cache`) ``` --- ## Monorepo Subdirectory AGENTS.md Pattern For large monorepos, put subsystem-specific files in subdirectories: ``` packages/db/AGENTS.md # Drizzle schema conventions, migration workflow apps/admin/AGENTS.md # React-specific patterns, component library usage apps/api/AGENTS.md # Route structure, middleware order, error handling ``` These are loaded *in addition to* the root AGENTS.md when Codex is working in that subtree. They should assume the root file has been read — don't repeat project-wide context. --- ## Audit Checklist (for Improving Existing AGENTS.md Files) When given a AGENTS.md to improve, evaluate each section: **Completeness** - [ ] Can a new dev run the project with only this file? (Commands section) - [ ] Does it explain the architecture in enough detail to navigate the codebase? - [ ] Does it cover the top 5 most common mistakes someone would make? - [ ] Does it reflect the *current* state of the project, not a past state? **Concision** - [ ] Is every line adding information Codex wouldn't have otherwise? - [ ] Are there paragraphs that could be cut without losing meaning? - [ ] Are config-file-readable facts being re-stated here? **Structure** - [ ] Are headers consistent and descriptive? - [ ] Are warnings visually distinct? - [ ] Is the most important information near the top? **Currency** - [ ] Is the "in progress" work actually in progress? - [ ] Are there references to old libraries, old patterns, or old team members? - [ ] Do the commands actually work? --- ## Anti-Patterns to Actively Avoid **The README Clone**: Don't copy-paste the README into AGENTS.md. README is for humans on GitHub. AGENTS.md is for Codex in a coding session. Different audiences, different content. **The Philosophy Essay**: "We believe in clean code and separation of concerns" — useless. Tell Codex what *specifically* that means in this codebase. **The Comprehensive Encyclopedia**: A 1,000-line AGENTS.md that documents every possible edge case is self-defeating. Codex has a context window. Put the rare stuff in linked files using `@imports`. **The Aspirational AGENTS.md**: Documents how the codebase *should* work, not how it *does* work. "We follow clean architecture" — but the actual code doesn't. This causes Codex to write code that doesn't fit the existing patterns. **Missing the Gotchas**: Most AGENTS.md files document the happy path. The real value is in the edges. What fails silently? What seems like a bug but is intentional? What will waste two hours to debug? **Stale In-Progress Sections**: The "currently migrating from X to Y" note that's been there for 18 months because the migration was abandoned. This is actively harmful. --- ## Output Format When creating a AGENTS.md, produce a complete, ready-to-commit file in Markdown. Structure it with H2 section headers. Use code blocks for all commands and code snippets. Use blockquotes (`>`) or bold for warnings and critical notes. When auditing an existing AGENTS.md, provide: 1. A diagnosis of what's missing, stale, or noisy 2. The revised file in full 3. A brief changelog of what changed and why Always optimize for the engineer who reads it six months from now knowing nothing about today's context. --- > Source: [weisberg/agent_tools](https://github.com/weisberg/agent_tools) — distributed by [TomeVault](https://tomevault.io).