# agent-kit

> Authoring and distribution toolkit for AI coding agent artifacts. Treats `AGENTS.md` as a single source of truth and derives the tool-specific files each agent reads (`CLAUDE.md`, `.gemini/GEMINI.md`, `.github/copilot-instructions.md`, `CONVENTIONS.md`). Also syncs reusable skills bundled inside npm packages into per-agent skill directories with collision-free flat folder names.

The AI coding agent landscape fragmented into a dozen tool-specific config files. `AGENTS.md` is the open standard (Linux Foundation-stewarded; read natively by Codex, Cursor, Amp, Jules, Factory, Windsurf, OpenCode and others), but a handful of major agents still require their own file at their own path. `agent-kit` derives them so you write your project instructions once and every agent stays in sync. For skills, every destination folder is named `<pkg-slug>[-skill-path]` so two packages can never collide; SKILL.md content is copied verbatim.

## Docs

- [README](https://github.com/hassanzohdy/agent-kit/blob/main/README.md): Install, quick start, derivation targets, CLI reference, programmatic API
- [Documentation](https://mongez.js.org/agent-kit/overview/): Full docs — overview, agent integrations, CLI usage, authoring skills, recipes

## Skills

- [Overview](https://github.com/hassanzohdy/agent-kit/blob/main/skills/overview/SKILL.md): What agent-kit is, mental model, key principles, when to use vs not use
  - *Auto-trigger:* Project has `AGENTS.md`/`CLAUDE.md` or `.claude/skills/<pkg>-*` folders, or user asks what agent-kit is or how skill distribution works.
- [Agent integrations](https://github.com/hassanzohdy/agent-kit/blob/main/skills/agent-integrations/SKILL.md): Per-IDE setup walkthroughs (Claude Code, Cursor, Codex, Kiro, Gemini CLI, GitHub Copilot, Aider, Antigravity) — the `--target` flag, files created, and reload quirk for each
  - *Auto-trigger:* User asks how to set up agent-kit with a specific agent/IDE, which `--target` to use, or why their agent isn't picking up skills/instructions.
- [CLI usage](https://github.com/hassanzohdy/agent-kit/blob/main/skills/cli-usage/SKILL.md): Exact commands and flags for `init` / `sync` / `watch` (including `--path`, `--projects`, `--override`, `--target`), plus the programmatic API
  - *Auto-trigger:* User invokes `agent-kit init`/`sync`/`watch`, wires `postinstall`, hits a flag, or imports `deriveAll`/`syncSkills` from `@mongez/agent-kit`.
- [Configuration](https://github.com/hassanzohdy/agent-kit/blob/main/skills/configuration/SKILL.md): The `agentKit` block in `package.json` — `targets`, `pick` (allowlist), `omit` (denylist), `layout`/`layoutOverrides` (grouped vs flat export), `projectPrefix`, `monorepo.projects`, and how they resolve/compose
  - *Auto-trigger:* User edits or asks about the `agentKit` config block, filtering noisy dependency skills, or pinning default targets.
- [Monorepos](https://github.com/hassanzohdy/agent-kit/blob/main/skills/monorepos/SKILL.md): Aggregating sibling projects (backend, frontend, …) into one root skills dir via `--projects` / `agentKit.monorepo.projects`; per-project `node_modules` + config, project-dir-prefixed authored skills, shared-dep dedupe, root `omit` veto, vs `--path`
  - *Auto-trigger:* User works in a monorepo / full-stack repo, asks why a sub-project's skills aren't visible at the root, or mentions `--projects` / `monorepo.projects` / workspaces.
- [Recipes](https://github.com/hassanzohdy/agent-kit/blob/main/skills/recipes/SKILL.md): Cross-cutting patterns — per-workspace `AGENTS.md`, `pick`/`omit` filtering, a CI drift guardrail, the programmatic API, and watch mode
  - *Auto-trigger:* User wires CI to catch derived-file drift, composes more than one tool/package/environment, or asks for a multi-step setup recipe.
- [Authoring skills](https://github.com/hassanzohdy/agent-kit/blob/main/skills/authoring-skills/SKILL.md): How to lay out skills — both your project's own skills in a single nested `skills/` folder at the project root (flattened into `.claude/skills/` on sync), and reusable skills shipped from an npm package. Covers nested category organization, auto-discovery, flat destination naming, the front-door convention, and the `skills/index.md` contract for grouped export.
  - *Auto-trigger:* User is organizing their project's own `skills/` folder (nested category subfolders) or editing a `skills/**/SKILL.md` inside a publishable package, or asks how to structure/ship skills.
- [Troubleshooting](https://github.com/hassanzohdy/agent-kit/blob/main/skills/troubleshooting/SKILL.md): Symptom → cause → fix for the common failure modes — `agent-kit: command not found`, unscoped `npx agent-kit` fetching the wrong package, skills synced but invisible to the agent, `pick` matched nothing, slug collisions, `sync` errors when AGENTS.md is missing, a published package's `skills/` not reaching consumers, `--target` validation, watch ignoring `node_modules`, and `--override` clobbering hand-authored folders, packages not grouping, and a generic router description.
  - *Auto-trigger:* User reports any error/log line from agent-kit, says "command not found", "skills aren't showing up", "wrong package", "pick matched no installed packages", "collision", "AGENTS.md missing", or "my skill folder disappeared".

## Optional

- [llms-full.txt](https://github.com/hassanzohdy/agent-kit/blob/main/llms-full.txt): Full content of README + skills concatenated for one-shot ingestion