One AGENTS.md for Every Coding Agent: Auto-Derive CLAUDE.md, GEMINI.md & Copilot Instructions

A developer created the open-source tool `@mongez/agent-kit` to solve the fragmentation of AI coding agent instructions across different tools. The CLI and TypeScript library derives per-agent files—including `CLAUDE.md`, `.gemini/GEMINI.md`, `.github/copilot-instructions.md`, and `CONVENTIONS.md`—from a single `AGENTS.md` source of truth, eliminating drift from maintaining multiple near-identical copies. The tool also automatically mirrors skills from installed npm packages into each agent's skills directory with collision-proof folder names.

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.