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

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/

foldersnpm 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 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 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 justagent-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.

npx agent-kit sync

npx agent-kit sync --target claude,cursor,codex

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 helps others find it.

source & further reading

dev.to — original article When Vibe Coding Stops Working Building a Self-Healing AI Agent: How to Run Untrusted Code Safely Without Blowing Up Your Server Why Your MCP Integrations Break Silently — And How We Built DriftGuard to Close the Gap