# One AGENTS.md for Every Coding Agent: Auto-Derive CLAUDE.md, GEMINI.md & Copilot Instructions > Source: > Published: 2026-05-29 20:49:29+00:00 Part 1 of a 2-part series.This post covers the whole tool and the "one source of truth" problem. Part 2 goes deep on the most novel piece — letting your npm packagesshipagent skills. (dev.to shows the series navigation once Part 2 is published.) **TL;DR** `AGENTS.md` → `agent-kit` derives `CLAUDE.md` , `.gemini/GEMINI.md` , `.github/copilot-instructions.md` , and `CONVENTIONS.md` . No more drift.`.claude/skills/` , `.cursor/skills/` , …).`skills/` folders`npm i -D @mongez/agent-kit && npx agent-kit init` AI coding tools are converging on how they work — but not on *where* they read project instructions. The result is fragmentation. One agent reads `AGENTS.md` . Another expects `CLAUDE.md` . GitHub Copilot wants `.github/copilot-instructions.md` . Gemini CLI looks for `.gemini/GEMINI.md` . Aider uses `CONVENTIONS.md` . [ AGENTS.md](https://agents.md/) is emerging as the open standard — Codex, Cursor, Amp, OpenCode, and Goose read it natively — but the holdouts above each still want their own file at their own path. So if your team uses more than one agent, you're maintaining several near-identical copies of the same instructions. The moment someone edits one and not the others, they drift apart — and your agents start disagreeing about your own conventions inside the same project. The skills story has the same shape: reusable `SKILL.md` files are great, but you end up hand-copying their folders into `.claude/skills/` , `.cursor/skills/` , `.codex/skills/` … and hoping nothing collides. (More on skills — plus a folder-organization win — below.) [ @mongez/agent-kit](https://www.npmjs.com/package/@mongez/agent-kit) is a small CLI + TypeScript library that closes both gaps: `AGENTS.md` .`node_modules` packages into each agent's skills directory — with flat, collision-proof folder names and a safety marker so your hand-written skills are never clobbered. ``` AGENTS.md │ ▼ @mongez/agent-kit │ ┌──────────────┼───────────────┬────────────────────┐ ▼ ▼ ▼ ▼ CLAUDE.md .gemini/GEMINI.md .github/...md CONVENTIONS.md ``` One source of truth. Every agent stays in sync. No copy-pasting, no drift. ``` npm install -D @mongez/agent-kit ``` The npm package is `@mongez/agent-kit` , but the CLI binary is just`agent-kit` . You install with the scope, you invoke without it. ``` npx agent-kit init ``` This writes a starter `AGENTS.md` at your project root (only if one doesn't already exist) and derives every per-tool file from it — `CLAUDE.md` , `.gemini/GEMINI.md` , `.github/copilot-instructions.md` , `CONVENTIONS.md` . Then wire it into `postinstall` so it stays fresh forever: ``` { "scripts": { "postinstall": "agent-kit sync" } } ``` From now on, every `install` re-derives the per-tool files from `AGENTS.md` **and** mirrors skills from your installed packages into `.claude/skills/` . Edit `AGENTS.md` , run `npx agent-kit sync` , and every supported agent picks up the change. This one quietly fixes a real annoyance. **Claude Code only discovers skills at the top level of .claude/skills/** — no nested folders. So as your skill set grows, everything piles into one flat, unsorted heap. (People hit this constantly and assume nesting just isn't possible.) agent-kit removes the limit. Keep a single `skills/` folder at your project root, organized into category folders as deep as you like: ``` skills/ → .claude/skills/ ├── backend/ backend-auth/ │ ├── auth/SKILL.md backend-jobs/ │ └── jobs/SKILL.md frontend-forms/ ├── frontend/ deployment/ │ └── forms/SKILL.md └── deployment/SKILL.md ``` On `agent-kit sync` , it walks the tree and flattens each path into a unique top-level name (`backend/auth` → `backend-auth` ). You organize for humans; Claude gets the flat layout it requires. No manifest, no registration — a folder with a `SKILL.md` *is* a skill. Part 2 goes deeper on the naming and safety rules. Here's the idea worth pausing on: `agent-kit sync` walks your `node_modules/` for any package that ships a `skills/` folder, and mirrors those skills into your agent's directory automatically. That means a library author can bundle agent skills *with* their package. You `npm install` the dependency, and your coding agent immediately knows how to use it — no docs-spelunking, no copy-paste. A few `@mongez/*` packages already do this today. That's a big enough idea that it gets its own post — Part 2 of this series — including the safety guarantees (a `.agent-kit-managed` sentinel so your own skills are never overwritten) and the collision-proof flat naming. `agent-kit sync --target` accepts `claude` , `cursor` , `codex` , `copilot` , `kiro` , `antigravity` , `opencode` , `amp` , `goose` . The default is `claude` only — writing into every agent's skills directory on a project that uses none of them would just litter your tree. ``` # Default — claude npx agent-kit sync # Multiple agents on the same project npx agent-kit sync --target claude,cursor,codex # Derive-only agents (Gemini, Aider) — skip the skills export npx agent-kit sync --derive-only ``` Or pin it in `package.json` so contributors don't have to remember: ``` { "scripts": { "postinstall": "agent-kit sync" }, "agentKit": { "targets": ["claude", "cursor"] } } ``` The derive step always emits all four derived files regardless of `targets` — the array gates only the **skills** export. `deriveAll` , `syncSkills` , `findProjectRoot` , and friends, all fully typed. ``` npm install -D @mongez/agent-kit npx agent-kit init ``` Part 2 goes deep on skills — organizing your own in nested folders, and shipping them inside an npm package so it *teaches* the agent how to use itself. Feedback and feature requests welcome. If it saved you some boilerplate, a ⭐ on [GitHub](https://github.com/hassanzohdy/agent-kit) helps others find it.