mongez-agent-kit-overview

name	mongez-agent-kit-overview
description	What agent-kit is, what it does, and when an agent should reach for it — the front-door mental model covering `AGENTS.md` derivation, npm-package skill distribution, custom `--path` scan roots (monorepos / linked dev packages), nested skill folders, flat folder naming (`<pkg-slug>-<skill-path>`), and the `.agent-kit-managed` sentinel.

Agent Kit

If you're working with AI coding agents — Claude Code, Cursor, Copilot, Codex, Aider, Gemini CLI — you've probably noticed two annoying chores. First, every agent reads its own project-instructions file from its own path, so the same content ends up copy-pasted across CLAUDE.md, .gemini/GEMINI.md, .github/copilot-instructions.md, and a half-dozen others. Second, your team's hard-won prompt patterns and skill files live in repos that downstream consumers can't reach — so everyone reinvents them.

agent-kit is a small CLI (and library) that solves both. Write your project instructions once in AGENTS.md — the emerging open standard read natively by Codex, Cursor, Amp, Jules, Factory, Windsurf, OpenCode, and others — and let agent-kit derive the agent-specific files. Ship your skills from any npm package and let agent-kit sync discover and mirror them into every agent's skills directory, with collision-free folder names.

Highlighted features

One AGENTS.md, every agent

Edit one file. agent-kit sync derives CLAUDE.md, .gemini/GEMINI.md, .github/copilot-instructions.md, CONVENTIONS.md, and others. They never drift again.

Skills travel with packages

Any npm package can ship a skills/ folder. agent-kit sync walks node_modules/, finds them, and mirrors each into .claude/skills/, .cursor/skills/, and friends — automatically pruned when the package is removed.

One tidy skills/ folder — nested how you think

Keep all your project's skills in a single skills/ folder at the root, grouped into category subfolders — skills/backend/auth/, skills/frontend/forms/, as deep as you like. Claude Code only reads a flat .claude/skills/, so agent-kit flattens each nested path into a unique name on sync (backend/auth → backend-auth). You organize for humans; agent-kit handles the flat requirement. The same layout is read from node_modules/ and any extra --path root (monorepo, linked dev package, vendor mirror).

Flat names, zero collisions

Skill folders are written as <pkg-slug>-<skill-path> — e.g. .claude/skills/warlock-js-core-add-connector/. Collisions impossible by construction. Claude Code routes by folder name, so naming = identity.

Sentinel-based prune

Only folders tagged with .agent-kit-managed get cleaned on re-sync. Your hand-authored skills sitting alongside ours stay completely untouched.

Stateless and idempotent

Every sync re-derives from disk. No lockfile, no cache, no "did sync forget to update state?" bugs. Run it twice — the second is a no-op.

Install

npm install -D @mongez/agent-kit
# or: yarn add -D @mongez/agent-kit
# or: pnpm add -D @mongez/agent-kit

The package is @mongez/agent-kit; the CLI binary is just agent-kit. Install with the scope, invoke without it.

Sixty-second walkthrough

Bootstrap a fresh project — no install needed. A starter AGENTS.md lands at the project root (only if missing), every per-tool file is derived from it, and agentKit.targets is seeded in package.json (defaulting to ["claude"], or --target claude,cursor to pick your own):

npx @mongez/agent-kit@latest init

Use the scoped name with npx when there's no local install — npx agent-kit … (unscoped) resolves a different package. init is a one-time scaffold, so always-latest npx is ideal; the recurring sync belongs as a pinned dev dependency (below).

Now install agent-kit locally as a dev dependency. Every step from here on (the postinstall script you're about to wire, ad-hoc npx agent-kit sync, CI) relies on the agent-kit binary being present in node_modules/.bin:

npm install -D @mongez/agent-kit
# or: yarn add -D @mongez/agent-kit
# or: pnpm add -D @mongez/agent-kit

Wire sync into postinstall so every future yarn install / npm install re-derives the per-tool files and mirrors skills from installed packages:

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

init may have already wired this for you. When @mongez/agent-kit is a declared dependency/devDependency and no postinstall exists, init writes the script above automatically and logs that it did. The zero-install npx @mongez/agent-kit@latest init bootstrap above can't (nothing in node_modules to run it), so re-run init after installing agent-kit locally — or add the script by hand.

From here, the workflow is: edit AGENTS.md once, run npx agent-kit sync (now safe — npx prefers the local binary), and every supported agent picks up the change.

Organize your project's own skills in one nested folder

You don't have to publish a package to benefit from skills. Drop a single skills/ folder at your project root and organize it however you think — grouped into category subfolders, nested as deep as you like:

my-app/
├── package.json
└── skills/
    ├── backend/
    │   ├── auth/SKILL.md
    │   └── jobs/SKILL.md
    ├── frontend/
    │   └── forms/SKILL.md
    └── deployment/SKILL.md

Claude Code only discovers skills at the top level of .claude/skills/ — no nested folders. That normally forces you to dump everything into one flat pile. agent-kit removes that constraint: it walks your nested skills/ recursively and flattens each path into a unique top-level name on sync.

npx agent-kit sync

.claude/skills/
  backend-auth/
  backend-jobs/
  frontend-forms/
  deployment/

You keep a tidy, human-readable source tree; Claude gets the flat layout it requires. Edit a SKILL.md, run sync (or agent-kit watch during active work), and the change lands. No naming ceremony — a directory containing a SKILL.md is a skill, and the folder path is its identity.

Pulling skills from a custom folder

By default, agent-kit reads skills/ from two places automatically: your project root and every package inside node_modules/. Working in a Yarn / pnpm workspaces monorepo, or with packages linked from outside node_modules/? Hand --path (or -p) one or more extra scan roots — agent-kit walks each one looking for the same skills/ layout. Inside any of those skills/ folders, SKILL.md files can sit at the top, in flat subdirs, or in nested category folders like skills/backend/auth/SKILL.md:

# Pull skills from a sibling workspace and a vendored mirror
npx agent-kit sync --path ../warlock.js/packages,vendor/our-skills

Skills discovered in --path roots take precedence over same-named entries from node_modules/ — handy for testing a local edit of an upstream skill without publishing.

Mental model

Source of truth → derivation → distribution.

AGENTS.md                                ← you write this once
   │
   ▼  agent-kit sync (derivation)
CLAUDE.md
.gemini/GEMINI.md
.github/copilot-instructions.md
CONVENTIONS.md

node_modules/@scope/pkg/skills/foo/SKILL.md
   │
   ▼  agent-kit sync (skills distribution)
.claude/skills/scope-pkg-foo/SKILL.md
.cursor/skills/scope-pkg-foo/SKILL.md

Where to go next

If you're a developer setting up agent-kit on your project:

• Agent integrations — copy-pasteable per-IDE walkthroughs (Claude Code, Cursor, Codex, Kiro, Gemini CLI, GitHub Copilot, Aider, Antigravity)
• CLI usage — every flag, every command, exact invocations
• Configuration — the agentKit block: targets, pick, omit, monorepo.projects
• Monorepos — aggregate sibling projects (backend, frontend, …) into one root skills dir
• Recipes — CI guardrail, programmatic API, watch mode, filtering

If you're a package author shipping skills with your own npm package:

• Authoring skills — folder layout, SKILL.md conventions, front-door pattern