mongez-agent-kit-authoring-skills

Authoring skills for agent-kit

There are two reasons to write skills, and they share the exact same folder layout:

1. Your own project's skills — drop a single skills/ folder at your project root, organize it into nested category folders, and agent-kit sync mirrors it into .claude/skills/ (and friends), flattening the nesting. This is the common case; see the overview's "Organize your project's own skills" section for the quick start.
2. Skills shipped from a package — if you maintain a library that benefits from a coding-agent skill (a model registration pattern, a CLI command shape, a domain convention), ship that skill inside your package. Anyone using agent-kit sync downstream receives it automatically.

The rest of this page covers the layout and conventions that apply to both, with package-specific notes (the files field, distribution) called out where they differ.

Folder layout

Place your skill folders inside your package, conventionally under skills/. Each skill is a directory containing a SKILL.md (plus any supporting files).

my-package/
├── package.json
├── src/
└── skills/
    ├── using-the-thing/
    │   ├── SKILL.md
    │   └── examples/
    │       └── example.ts
    └── another-skill/
        └── SKILL.md

Nested organization (for larger skill sets)

You can group skills under category folders — agent-kit walks skills/ recursively, so any directory containing a SKILL.md becomes a skill, no matter how deep:

my-app/
└── skills/
    ├── backend/
    │   ├── auth/SKILL.md           ← skill, name "backend/auth"
    │   └── db/SKILL.md             ← skill, name "backend/db"
    ├── frontend/
    │   └── page-builder/SKILL.md   ← skill, name "frontend/page-builder"
    └── shared-utility/SKILL.md     ← skill, name "shared-utility" (flat OK too)

A directory containing SKILL.md is treated as a leaf — we don't recurse into it. So skills/backend/SKILL.md plus skills/backend/auth/SKILL.md would yield only backend (with auth/ treated as supporting content). This matches the warlock-style "root + subskills" convention used in @warlock.js/ai, @warlock.js/scheduler, etc.