Eliminating AI Agent Instruction Drift with agent-kit

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

Hasan Zohdy introduced @mongez/agent-kit to solve the fragmentation of AI coding tool instructions. The system automatically synchronizes a single source of truth across multiple proprietary agent configuration paths.

Why This Matters

Different AI agents require instructions in different files (e.g., .github/copilot-instructions.md vs .gemini/GEMINI.md), leading to manual duplication and ‘drift’ where agents disagree on project conventions. This fragmentation forces developers to maintain near-identical copies of documentation, increasing the risk of inconsistent agent behavior across a single codebase.

Key Insights

• The emerging open standard for project instructions is AGENTS.md, natively read by Codex, Cursor, Amp, OpenCode, and Goose (2026).
• Instruction derivation allows one file to populate CLAUDE.md, .gemini/GEMINI.md, .github/copilot-instructions.md, and CONVENTIONS.md simultaneously.
• @mongez/agent-kit enables npm packages to ship ‘skills’ (SKILL.md files) that are automatically mirrored into agent directories like .claude/skills/ upon installation.
• Automated flattening solves Claude Code’s limitation where it only discovers skills at the top level of .claude/skills/, converting nested paths like backend/auth into flat names like backend-auth.

Working Examples

Installation and initialization of the agent-kit CLI.

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

Adding agent-kit sync to package scripts to ensure instructions stay fresh after every install.

{
"scripts": {
"postinstall": "agent-kit sync"
}
}

Targeting specific agents for skills export or running derive-only mode for Gemini and Aider.

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

Practical Applications

• Use case: Library authors bundling SKILL.md files in npm packages so that any developer installing the dependency automatically grants their coding agent knowledge of how to use the library.

Pitfall: Manual copy-pasting of skills into .claude/skills/, which leads to folder collisions and maintenance overhead as skill sets grow.

References:

• [type: text, text: ‘I would like you to help me draft an email that expresses my interest in a particular job vacancy but highlights that I am currently working in another role and wish to keep my application confidential.’}]