Metadata-Version: 2.4
Name: agent-catalog-cli
Version: 0.2.0
Summary: Scan a directory for AI-assistant skills, rules and subagents and copy selected ones into a chosen assistant's folder layout.
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: questionary>=2.1.1
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.26.7
Description-Content-Type: text/markdown

# 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](https://docs.astral.sh/uv/) project.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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`](agents_catalog/destinations.py):

| Kind   | Default subfolder                                  |
| ------ | -------------------------------------------------- |
| skill  | `<assistant>/skills/<name>/`                       |
| agent  | `<assistant>/agents/<file>`                        |
| rule   | `<assistant>/rules/<file>` (`.github` -> `instructions/`) |

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