agent-catalog-cli

agent-catalog

A Typer CLI that scans a directory for AI-assistant artifacts (skills, rules, subagents), caches them, and lets you interactively copy selected ones into a chosen coding assistant's folder layout.

Install / run

This is a uv project.

uv sync
uv run agent-catalog --help

Commands

init <target_dir>

Scans target_dir for the config roots .agents/, .cursor/, .claude/, .github/, .codex/ and indexes:

• Skills: any folder containing SKILL.md (the whole package, including assets/, references/, examples/).
• Subagents: *.md files directly under an agents/ folder.
• Rules: *.md / *.mdc under rules/ and (recursively) instructions/ (e.g. .github/instructions/**/*.instructions.md), .github/custom-instructions.md, plus any CLAUDE.md / AGENTS.md memory files anywhere under the target (excluding .git, .venv, node_modules, etc.).

Names and descriptions come from YAML frontmatter (name, description); rules fall back to the filename plus the first few lines. Results are written to .agent-catalog.json in the current directory.

uv run agent-catalog init /path/to/source

add skills <target_dir> / add agents <target_dir> / add rules <target_dir>

Additive scans, discovered recursively anywhere under target_dir, appended to the existing .agent-catalog.json (deduped by absolute path, so re-runs and overlap with init are safe). skip dirs (.git, .venv, node_modules, …) are excluded.

• add skills — <skill>/ packages (containing SKILL.md) under folders named skills/.
• add agents — *.md files directly under any agents/ folder.
• add rules — *.md / *.mdc under any rules/ or instructions/ folder, plus CLAUDE.md / AGENTS.md memory files.

add plugins (folders named claude-plugin/ / cursor-plugin/) is temporarily suspended.

uv run agent-catalog add skills /path/to/source
uv run agent-catalog add agents /path/to/source
uv run agent-catalog add rules /path/to/source

pick skills [TERM] / pick agents [TERM] / pick rules [TERM]

Loads the cache and opens an interactive multi-select (Arrows to move, type to filter live, <Space> to toggle, Enter to confirm), asks which coding assistant to target, and copies the selected artifacts into that assistant's folder.

TERM is optional. When provided, the catalog is pre-narrowed by a case-insensitive substring matched against each artifact's name and description before the picker opens — handy for large catalogs. Live type-to-filter still applies on top. Omit TERM to list everything.

uv run agent-catalog pick skills                  # copy into ./ (cwd)
uv run agent-catalog pick skills wiki             # pre-filter to name/description containing "wiki"
uv run agent-catalog pick rules --target ./proj   # copy into another project root
uv run agent-catalog pick agents --assistant .claude --overwrite

install-skill

Installs the bundled agent-catalog management skill (shipped inside the package at agents_catalog/skills/agent-catalog/) into a chosen root. Non-interactive.

uv run agent-catalog install-skill --target . --assistant .cursor   # ./.cursor/skills/agent-catalog/
uv run agent-catalog install-skill --target ~ --assistant .cursor   # ~/.cursor/skills/agent-catalog/ (global)

• --target, -t — root to install into (default: cwd; ~ for global).
• --assistant, -a — assistant folder convention (default: .cursor).
• --overwrite — refresh an existing copy.

Options (all pick commands):

• --target, -t — project root to copy into (default: cwd).
• --assistant, -a — the target coding assistant whose folder convention the selected artifacts are copied into (one of .agents, .claude, .cursor, .codex, .github). This selects the destination root, combined with the per-kind subfolder to form the copy destination (e.g. <target>/.claude/skills/<name>/). It affects where files land only, not what is scanned or indexed. If omitted, the command asks you to choose one before copying.
• --overwrite — replace artifacts that already exist at the destination. Skills (directory packages) are merged over the existing folder, overwriting overlapping files but leaving any extra files in place; agents/rules (single files) are replaced. Without it, existing targets are left untouched and reported as skipped. Sources that no longer exist are reported as missing regardless of this flag.

Destination mapping

Per-assistant destinations are defined in agents_catalog/destinations.py:

These are sensible defaults; edit the tables in destinations.py to match evolving conventions.