aibits
v0.1.4
Published
Installer for agent artifacts: skills, subagents, and rules
Maintainers
Readme
aibits
Installer for agent skills, subagents, and rules. 🧩
npx aibits add owner/kitHighly inspired by Vercel’s npx skills — same verbs, same source shapes, same flags. aibits is the mixed-kit version: one add can ship a skill, a subagent, and a rule, and each lands where Cursor or Claude Code already looks.
Why this exists
npx skills is the right UX for skills. Real agent setups are rarely skills-only.
| Kind | What it is |
| -------- | ------------------------------------------------------- |
| skill | On-demand workflow (SKILL.md in a named directory) |
| subagent | Isolated specialist with its own prompt / model / tools |
| rule | Persistent guidance (.md / .mdc) |
One npx aibits add owner/kit installs the whole kit. You should not need three tools.
Kept from skills: same commands (add / list / remove / update / init), same sources (owner/repo, git URL, GitHub tree URL, local path), and the same flags (-g, -a, -y, --copy, --all). Extra authoring verb: new. --copy is accepted and ignored — aibits always copies.
What we added:
- ✨ Kinds — one kit can ship skills, subagents, and rules; filter with
--kind - Picker — long lists stay in a terminal-sized window; mixed kits get kind tabs
- Native dests — Cursor and Claude Code get the paths and file shapes they actually load
- Per-agent frontmatter —
cursor:/claude-code:overrides hoist into native dest files aibits.deps— artifacts can pull other artifacts (or sources) along on add- 🛡️ Safer updates — dirty dests are not overwritten; you get diffs for a 3-way merge
initscaffolds a kit, not only aSKILL.mdnewcreates one artifact (skill, subagent, or rule) in convention dirs
A skills-only repo still works. aibits is a compatible superset, not a fork that abandons that case.
Install a kit
npx aibits add owner/kitProject install is the default; -g is user-global. CI-friendly with -y.
What to pass add
Two GitHub shorthand forms:
| Source | What happens |
| --------------------------- | ------------------------------------------------------- |
| owner/kit | Clone the repo, then ask which artifacts to install |
| skills/my-skill@owner/kit | Install that artifact only (no picker) |
npx aibits add owner/kit
npx aibits add skills/my-skill@owner/kit
npx aibits add agents/reviewer@owner/kit
npx aibits add rules/typescript@owner/kitThe path before @ is skills/…, agents/…, or rules/… (or the kind ids skill/, subagent/, rule/). Pin a git ref with #:
npx aibits add skills/my-skill@owner/kit#v1.2.0owner/kit@skills/my-skill is not valid — path goes first.
Other sources (still interactive unless you name an artifact with @):
npx aibits add https://github.com/owner/kit
npx aibits add https://github.com/owner/kit/tree/main/skills/foo
npx aibits add [email protected]:owner/kit.git
npx aibits add ./my-kit
npx aibits add skills/my-skill@./my-kit-y / --all skip prompts (owner/kit -y installs everything in the source).
Options
| Option | Description |
| ------------------- | -------------------------------------------------- |
| -g, --global | Install user-global instead of project |
| -a, --agent <id> | Target agent (cursor, claude-code, or *) |
| -k, --kind <kind> | Filter kind (skill, subagent, rule) |
| -s, --name <name> | Filter by artifact name |
| -y, --yes | Skip confirmation prompts (keeps local dest edits) |
| --force | Overwrite dests even if they were edited |
| --accept | Keep dest, record it as this install (after merge) |
| --copy | Accepted no-op; install always copies |
| --all | All artifacts, all agents, no prompts |
| -l, --list | List artifacts without installing |
Examples
# One skill from a kit
npx aibits add skills/my-skill@owner/kit
# Skills and subagents only (picker still runs unless -y)
npx aibits add owner/kit --kind skill --kind subagent
# Cursor + Claude Code, global, non-interactive
npx aibits add owner/kit -a cursor -a claude-code -g -y
# Preview what a source contains
npx aibits add owner/kit --listScope
| Scope | Flag | Use case |
| ----------- | --------- | ------------------------- |
| Project | (default) | Shared with the repo |
| Global | -g | Available across projects |
aibits copies into native dests (.cursor/…, .claude/…). Those files are yours to edit. Re-adding a kit does not clobber local dest edits; dirty dests get the same 3-way merge treatment as update. --force overwrites. --accept records dest as the install after you merge. --copy is accepted for npx skills compatibility and does nothing. Symlinking is not used.
Other commands
| Command | Description |
| ------------------------------ | ---------------------------------------------- |
| npx aibits list | List project and global installs (alias: ls) |
| npx aibits remove [names…] | Remove what aibits installed (alias: rm) |
| npx aibits update [names…] | Update from the original source |
| npx aibits init [name] | Scaffold a mixed kit |
| npx aibits new [kind] [name] | Create a skill, subagent, or rule |
npx aibits list
npx aibits list -p # project only
npx aibits remove reviewer -y
npx aibits update
npx aibits init my-kit
npx aibits new skill my-skill
npx aibits newlist badges dirty when the live dest no longer matches the last install. update skips unchanged artifacts, applies clean ones, and does not overwrite dirty dests — it writes upstream aside, prints unified diffs, and exits 1 so you can merge.
Remove only deletes dests aibits recorded and that still look like its install. Hand-written files in the same folder stay put.
Author a kit
my-kit/
skills/foo/SKILL.md
agents/reviewer.md
rules/typescript.mdConvention dirs plus agent-native trees (.cursor/…, .claude/…, .agents/skills/) are both discovered. Unknown files are skipped, not errors. node_modules, .git, and dist are not scanned.
npx aibits init my-kit
npx aibits new # pick skill / subagent / rule, then name
npx aibits new skill foo
npx aibits add ./my-kit -yPer-agent frontmatter
The body is the portable prompt. Envelope fields can differ per agent. Dest files hoist the target agent’s block onto top-level fields, then strip cursor: / claude-code: / aibits: so the dest is native. Missing override is fine — install still succeeds.
---
name: code-reviewer
description: Review diffs against project rules.
model: inherit
cursor:
readonly: true
claude-code:
tools: [Read, Grep, Glob]
---Cursor rules map Claude paths → globs when globs is absent (and the other way around for Claude).
Dependencies (aibits.deps)
Any kind can declare extra artifacts to install alongside it. Artifact deps have two forms: ~/skills/my-skill is a path in this kit (~ is the kit root, not $HOME); skills/my-skill@user/repo is that artifact from another source. A whole kit (owner/repo, URL, local path) still works as a source dep.
Dest files strip the aibits: block (Cursor and Claude do not load it). The source kit keeps it.
---
name: reviewer
description: Reviews diffs against project rules.
aibits:
deps:
- ~/skills/example
- skills/my-skill@jakubtobiasz/my-skills-repo
- owner/other-kit
---| Dep | Meaning |
| ---------------------------- | ----------------------------------------------------------- |
| ~/skills/example | Same-kit artifact at that path (~ = kit root) |
| skills/my-skill@owner/repo | That skill from owner/repo |
| owner/other-kit | Whole kit (same shapes as add: URL, tree URL, local path) |
Relative local paths in deps resolve from the kit root. owner/repo@skills/foo is not valid here either.
Add pulls those deps even if you filtered them out of the picker (-k, -s). Transitive same-kit deps come too. Missing same-kit names are a warning, not a hard fail. The CLI prints what it is pulling and what required it:
→ Also installing 2 dependencies:
skill/helper required by skill/parent
skill/leaf required by skill/helper
→ Also adding 1 source:
owner/other-kit required by skill/parentaibits add owner/kit --list shows deps: under each artifact that has them.
Where files land
v1 agents: Cursor and Claude Code.
| Agent | Kind | Project | Global |
| ----------- | -------- | -------------------------- | ---------------------------- |
| Cursor | skill | .cursor/skills/<name>/ | ~/.cursor/skills/<name>/ |
| Cursor | subagent | .cursor/agents/<name>.md | ~/.cursor/agents/<name>.md |
| Cursor | rule | .cursor/rules/<name>.mdc | ~/.cursor/rules/<name>.mdc |
| Claude Code | skill | .claude/skills/<name>/ | ~/.claude/skills/<name>/ |
| Claude Code | subagent | .claude/agents/<name>.md | ~/.claude/agents/<name>.md |
| Claude Code | rule | .claude/rules/<name>.md | ~/.claude/rules/<name>.md |
Claude Code’s global root is CLAUDE_CONFIG_DIR or ~/.claude.
Requirements
Node.js 22+.
