{"slug": "one-agents-md-for-every-coding-agent-auto-derive-claude-md-gemini-md-copilot", "title": "One AGENTS.md for Every Coding Agent: Auto-Derive CLAUDE.md, GEMINI.md & Copilot Instructions", "summary": "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.", "body_md": "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.)\n\n**TL;DR**\n\n`AGENTS.md`\n\n→ `agent-kit`\n\nderives `CLAUDE.md`\n\n, `.gemini/GEMINI.md`\n\n, `.github/copilot-instructions.md`\n\n, and `CONVENTIONS.md`\n\n. No more drift.`.claude/skills/`\n\n, `.cursor/skills/`\n\n, …).`skills/`\n\nfolders`npm i -D @mongez/agent-kit && npx agent-kit init`\n\nAI coding tools are converging on how they work — but not on *where* they read project instructions. The result is fragmentation.\n\nOne agent reads `AGENTS.md`\n\n.\n\nAnother expects `CLAUDE.md`\n\n.\n\nGitHub Copilot wants `.github/copilot-instructions.md`\n\n.\n\nGemini CLI looks for `.gemini/GEMINI.md`\n\n.\n\nAider uses `CONVENTIONS.md`\n\n.\n\n[ 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.\n\nSo 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.\n\nThe skills story has the same shape: reusable `SKILL.md`\n\nfiles are great, but you end up hand-copying their folders into `.claude/skills/`\n\n, `.cursor/skills/`\n\n, `.codex/skills/`\n\n… and hoping nothing collides. (More on skills — plus a folder-organization win — below.)\n\n[ @mongez/agent-kit](https://www.npmjs.com/package/@mongez/agent-kit) is a small CLI + TypeScript library that closes both gaps:\n\n`AGENTS.md`\n\n.`node_modules`\n\npackages into each agent's skills directory — with flat, collision-proof folder names and a safety marker so your hand-written skills are never clobbered.\n\n```\n              AGENTS.md\n                  │\n                  ▼\n          @mongez/agent-kit\n                  │\n   ┌──────────────┼───────────────┬────────────────────┐\n   ▼              ▼               ▼                    ▼\nCLAUDE.md   .gemini/GEMINI.md   .github/...md     CONVENTIONS.md\n```\n\nOne source of truth. Every agent stays in sync. No copy-pasting, no drift.\n\n```\nnpm install -D @mongez/agent-kit\n```\n\nThe npm package is\n\n`@mongez/agent-kit`\n\n, but the CLI binary is just`agent-kit`\n\n. You install with the scope, you invoke without it.\n\n```\nnpx agent-kit init\n```\n\nThis writes a starter `AGENTS.md`\n\nat your project root (only if one doesn't already exist) and derives every per-tool file from it — `CLAUDE.md`\n\n, `.gemini/GEMINI.md`\n\n, `.github/copilot-instructions.md`\n\n, `CONVENTIONS.md`\n\n.\n\nThen wire it into `postinstall`\n\nso it stays fresh forever:\n\n```\n{\n  \"scripts\": {\n    \"postinstall\": \"agent-kit sync\"\n  }\n}\n```\n\nFrom now on, every `install`\n\nre-derives the per-tool files from `AGENTS.md`\n\n**and** mirrors skills from your installed packages into `.claude/skills/`\n\n. Edit `AGENTS.md`\n\n, run `npx agent-kit sync`\n\n, and every supported agent picks up the change.\n\nThis 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.)\n\nagent-kit removes the limit. Keep a single `skills/`\n\nfolder at your project root, organized into category folders as deep as you like:\n\n```\nskills/                      →     .claude/skills/\n├── backend/                          backend-auth/\n│   ├── auth/SKILL.md                 backend-jobs/\n│   └── jobs/SKILL.md                 frontend-forms/\n├── frontend/                         deployment/\n│   └── forms/SKILL.md\n└── deployment/SKILL.md\n```\n\nOn `agent-kit sync`\n\n, it walks the tree and flattens each path into a unique top-level name (`backend/auth`\n\n→ `backend-auth`\n\n). You organize for humans; Claude gets the flat layout it requires. No manifest, no registration — a folder with a `SKILL.md`\n\n*is* a skill. Part 2 goes deeper on the naming and safety rules.\n\nHere's the idea worth pausing on: `agent-kit sync`\n\nwalks your `node_modules/`\n\nfor any package that ships a `skills/`\n\nfolder, and mirrors those skills into your agent's directory automatically.\n\nThat means a library author can bundle agent skills *with* their package. You `npm install`\n\nthe dependency, and your coding agent immediately knows how to use it — no docs-spelunking, no copy-paste. A few `@mongez/*`\n\npackages already do this today.\n\nThat's a big enough idea that it gets its own post — Part 2 of this series — including the safety guarantees (a `.agent-kit-managed`\n\nsentinel so your own skills are never overwritten) and the collision-proof flat naming.\n\n`agent-kit sync --target`\n\naccepts `claude`\n\n, `cursor`\n\n, `codex`\n\n, `copilot`\n\n, `kiro`\n\n, `antigravity`\n\n, `opencode`\n\n, `amp`\n\n, `goose`\n\n. The default is `claude`\n\nonly — writing into every agent's skills directory on a project that uses none of them would just litter your tree.\n\n```\n# Default — claude\nnpx agent-kit sync\n\n# Multiple agents on the same project\nnpx agent-kit sync --target claude,cursor,codex\n\n# Derive-only agents (Gemini, Aider) — skip the skills export\nnpx agent-kit sync --derive-only\n```\n\nOr pin it in `package.json`\n\nso contributors don't have to remember:\n\n```\n{\n  \"scripts\": { \"postinstall\": \"agent-kit sync\" },\n  \"agentKit\": { \"targets\": [\"claude\", \"cursor\"] }\n}\n```\n\nThe derive step always emits all four derived files regardless of `targets`\n\n— the array gates only the **skills** export.\n\n`deriveAll`\n\n, `syncSkills`\n\n, `findProjectRoot`\n\n, and friends, all fully typed.\n\n```\nnpm install -D @mongez/agent-kit\nnpx agent-kit init\n```\n\nPart 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.\n\nIf it saved you some boilerplate, a ⭐ on [GitHub](https://github.com/hassanzohdy/agent-kit) helps others find it.", "url": "https://wpnews.pro/news/one-agents-md-for-every-coding-agent-auto-derive-claude-md-gemini-md-copilot", "canonical_source": "https://dev.to/hassanzohdy/one-agentsmd-for-every-coding-agent-auto-derive-claudemd-geminimd-copilot-instructions-2053", "published_at": "2026-05-29 20:49:29+00:00", "updated_at": "2026-05-29 21:11:09.759011+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-products", "ai-infrastructure", "ai-research"], "entities": ["AGENTS.md", "CLAUDE.md", "GitHub Copilot", "Gemini CLI", "Aider", "Codex", "Cursor", "Amp"], "alternates": {"html": "https://wpnews.pro/news/one-agents-md-for-every-coding-agent-auto-derive-claude-md-gemini-md-copilot", "markdown": "https://wpnews.pro/news/one-agents-md-for-every-coding-agent-auto-derive-claude-md-gemini-md-copilot.md", "text": "https://wpnews.pro/news/one-agents-md-for-every-coding-agent-auto-derive-claude-md-gemini-md-copilot.txt", "jsonld": "https://wpnews.pro/news/one-agents-md-for-every-coding-agent-auto-derive-claude-md-gemini-md-copilot.jsonld"}}