Docs

Using Agent Aisle

Install the CLI, add skills, and write your own.

Aisle 01

Install the CLI

Needs Node.js 20 or newer.

Run it without installing anything:

npx @agentsaisle/cli add explore

Or install it once and use the short name aisle:

npm i -g @agentsaisle/cli
aisle add explore

We don't use npm install for skills. It puts packages in node_modules, which agents don't read. The CLI puts the skill folder where your agent looks for it, for example .claude/skills/explore/.

If the install fails

EACCES: permission denied on a global install. npm can't write to a folder owned by root. Use npx above, or move npm's global folder into your home directory (no sudo needed):

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
npm i -g @agentsaisle/cli

Use ~/.bashrc instead of ~/.zshrc if you use bash. Node installed through nvm or Homebrew usually doesn't have this problem.

sh: aisle: command not found from npx. This happens when you run npx inside a clone of the Agent Aisle repository, because npx finds the local package and can't run it. Run the command from your own project folder instead, or pin the published version:

npx @agentsaisle/cli@latest add explore

Version looks old. Check aisle --version. If it prints an older number, run npm cache clean --force and install again.

Aisle 02

Commands

Command	What it does
aisle add <name>[@version] ...	Install one or more skills. Without a version you get the latest.
aisle add <owner>/<repo>[/path][@ref]	Install straight from any GitHub repo, even if it isn't listed. Shown as unverified.
aisle remove <name>	Delete the skill folder and its lockfile entry.
aisle list	Show installed skills and their versions, and flag ones that have an update.
aisle info <name>	Description, author, versions, clients and any scripts warning.
aisle search <query>	Search the registry by name, aisle, author or description, best match first.
aisle update [name]	Update one or all installed skills to the latest version. Skills installed from GitHub are skipped.
aisle audit <target> [--format pretty\|json\|sarif\|markdown] [--fail-on <level>]	Scan a skill for risky patterns without running anything in it. Target is a local folder, a registry name or a GitHub repo. See the Audit page.
aisle init [--profile <id>] [--no-rules \| --rules-only]	Install a starter bundle and add the Agent Aisle house rules to CLAUDE.md (AGENTS.md for Codex and Cursor). With --profile it never asks which bundle.

Flags for add, remove, list, init and update

Flag	What it does
--global, -g	Use the user-level skills folder (for example ~/.claude/skills) instead of the project.
--agent <name>	claude-code, codex or cursor. By default the CLI detects it from your project and falls back to claude-code.
--yes, -y	Skip confirmation prompts. Required when there is no terminal, for example in CI.
--dry-run	Show what would be installed or removed without changing anything.

Installs are recorded in aisle-lock.json in your project root (or your home folder with --global). Development files in a skill folder (evals/, preview/ and the top-level README.md) are not installed.

House rules

aisle init writes a short block of working rules (search before reading, change only what the task needs, run the checks before saying done) between  and  markers. Running it again replaces only that block and never touches the rest of the file. Use --rules-only to skip the skills or --no-rules to skip the rules.

Aisle 03

What a skill is

A skill is a folder with a SKILL.md file. The file starts with a name and a description, then explains to your agent how to do one job. Agents read the description to decide when a skill applies, and load the rest when it does.

---
name: commit
description: Write a clear git commit for the current changes. Use when asked to commit.
---

# Commit

1. Run git status and git diff.
2. Group the changes into logical commits.
3. Write a short imperative subject and explain why in the body.

Aisle 04

Write a good skill

Name it in lowercase kebab-case, and make the folder name and the name in the frontmatter identical.
Say what it does and when to use it in the description, in one or two sentences. That text is how an agent chooses the skill.
Do one job. If you find yourself writing "and also", split it into two skills.
Keep SKILL.md short. Put long reference material in separate files in the same folder and link to them.
Avoid scripts when you can. If a skill needs them, put them in a scripts/ folder. Users are warned and asked to confirm before installing, and reviewers read every script.
Try it yourself first in a clean project before you submit it.

Aisle 05

How installs stay safe

Every version is pinned to a full commit, so a later push to the author's repository can't change what you install.
The CLI downloads and copies files. It never runs anything from a skill.
Skills with scripts list the files. Community and unverified skills ask before installing; verified official skills, whose scripts a maintainer has read in full, list them without asking.
Verified means a maintainer read the skill and any scripts in full. Community skills are unverified until then, and labeled that way everywhere.
See something wrong? Use "Report this skill" on its page, or open an issue on GitHub.

Aisle 06

Aisles, kits and Elsewhere

Aisles group skills by what they are for. Each aisle shelves our own skills first, then community skills.
A kit is a bundle of skills that work together, such as the Motion portfolio site. Install one with aisle init --profile <kit-id>.
Elsewhere lists skills by other authors. We link to the author's GitHub page and show their license. We do not host them and the CLI does not install them.