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 packages ship agent skills. (dev.to shows the series navigation once Part 2 is published.)

TL;DR

Write project instructions once in AGENTS.md → agent-kit derives CLAUDE.md, .gemini/GEMINI.md, .github/copilot-instructions.md, and CONVENTIONS.md. No more drift.
It mirrors skills from your installed packages and your project into every agent's directory (.claude/skills/, .cursor/skills/, …).
Keep nested skills/ folders Claude Code can't read natively — agent-kit flattens them into the layout it requires on sync.
Start: npm i -D @mongez/agent-kit && npx agent-kit init

The problem: every agent wants its own file

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.)

The fix: derive everything from one file

@mongez/agent-kit is a small CLI + TypeScript library that closes both gaps:

Derive every per-agent instructions file from a single AGENTS.md.
Sync skills out of your installed 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.

60-second start

npx agent-kit init

It outputs:

$ npx agent-kit init
✔ Created AGENTS.md
✔ Derived 4 file(s) (4 changed): claude, gemini, copilot, aider

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.

A killer feature: nested skill folders

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.

The part nobody else does

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.

Pick your agent

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.

With packages in node_modules that ship skills, agent-kit sync prints something like:

$ npx agent-kit sync
✔ Derived 4 file(s) (0 changed): claude, gemini, copilot, aider
✔ Exported 24 skill(s) from 3 package(s) to: claude
[agent-kit 12:39:25 AM] ℹ Claude Code picks up new skills on the next prompt. Other agents (Cursor, Copilot, Codex, Gemini, Kiro, Antigravity) may need a window or session reload.

Why it stays out of your way

Stateless — every sync reads disk truth. No lockfile, no cache, no drift between runs.
Idempotent — re-running when nothing changed is a no-op; files that already match aren't rewritten.
TypeScript-first — the CLI is a thin wrapper over deriveAll, syncSkills, findProjectRoot, and friends, all fully typed.
MIT licensed, dependency-light.

Try it

npm install -D @mongez/agent-kit
npx agent-kit init

GitHub: https://github.com/hassanzohdy/agent-kit
Docs: https://mongez.js.org/agent-kit/overview/
npm: https://www.npmjs.com/package/@mongez/agent-kit

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.

推荐订阅源

DEV Community