agent-catalog-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{agent_catalog_cli-0.1.0 → agent_catalog_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-catalog-cli
-Version: 0.1.0
+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
@@ -38,37 +38,48 @@ Names and descriptions come from YAML frontmatter (`name`, `description`); rules
 uv run agent-catalog init /path/to/source
 ```
 
-### `index-skills <target_dir>` / `index-plugins <target_dir>`
+### `add skills <target_dir>` / `add agents <target_dir>` / `add rules <target_dir>`
 
-Additive scans for patterned skill collections, discovered recursively anywhere under `target_dir`. Each immediate `<skill>/` subfolder containing a `SKILL.md` is indexed and **appended** to the existing `.agent-catalog.json` (deduped by absolute path, so re-runs and overlap with `init` are safe).
+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.
 
-- `index-skills` — folders named `skills/` (`skills/<skill>/`).
-- `index-plugins` — folders named `claude-plugin/` and `cursor-plugin/` (`claude-plugin/<skill>/`, `cursor-plugin/<skill>/`).
+- `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 index-skills /path/to/source
-uv run agent-catalog index-plugins /path/to/source
+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` / `pick-agents` / `pick-rules`
+### `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.
 
-Loads the cache and opens on the full catalog as 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-rules --target ./proj  # copy into another project root
-uv run agent-catalog pick-agents --assistant .claude --overwrite
+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
 ```
 
-### `pick-skills:filter` / `pick-agents:filter` / `pick-rules:filter`
+### `install-skill`
 
-Same as the base pickers, but pre-narrow the catalog by a filter TERM (case-insensitive substring on the artifact **name**) before the picker opens — handy for large catalogs. If TERM is omitted you are prompted for it. Live type-to-filter still applies on top.
+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 pick-skills:filter wiki     # only skills whose name contains "wiki"
-uv run agent-catalog pick-rules:filter           # prompts for a filter term
+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).

{agent_catalog_cli-0.1.0 → agent_catalog_cli-0.2.0}/README.md

@@ -27,37 +27,48 @@ Names and descriptions come from YAML frontmatter (`name`, `description`); rules
 uv run agent-catalog init /path/to/source
 ```
 
-### `index-skills <target_dir>` / `index-plugins <target_dir>`
+### `add skills <target_dir>` / `add agents <target_dir>` / `add rules <target_dir>`
 
-Additive scans for patterned skill collections, discovered recursively anywhere under `target_dir`. Each immediate `<skill>/` subfolder containing a `SKILL.md` is indexed and **appended** to the existing `.agent-catalog.json` (deduped by absolute path, so re-runs and overlap with `init` are safe).
+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.
 
-- `index-skills` — folders named `skills/` (`skills/<skill>/`).
-- `index-plugins` — folders named `claude-plugin/` and `cursor-plugin/` (`claude-plugin/<skill>/`, `cursor-plugin/<skill>/`).
+- `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 index-skills /path/to/source
-uv run agent-catalog index-plugins /path/to/source
+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` / `pick-agents` / `pick-rules`
+### `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.
 
-Loads the cache and opens on the full catalog as 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-rules --target ./proj  # copy into another project root
-uv run agent-catalog pick-agents --assistant .claude --overwrite
+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
 ```
 
-### `pick-skills:filter` / `pick-agents:filter` / `pick-rules:filter`
+### `install-skill`
 
-Same as the base pickers, but pre-narrow the catalog by a filter TERM (case-insensitive substring on the artifact **name**) before the picker opens — handy for large catalogs. If TERM is omitted you are prompted for it. Live type-to-filter still applies on top.
+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 pick-skills:filter wiki     # only skills whose name contains "wiki"
-uv run agent-catalog pick-rules:filter           # prompts for a filter term
+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).

agent_catalog_cli-0.2.0/agents_catalog/app.py

@@ -0,0 +1,289 @@
+"""Typer CLI: index AI-assistant artifacts and copy selected ones into a project."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import questionary
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from . import cache as cache_mod
+from . import destinations as dest_mod
+from . import scanner
+from .installer import CopyResult, install
+from .models import Artifact, Catalog, Kind
+
+# The agent-catalog management skill ships inside the package so the CLI can install it.
+SELF_SKILL_DIR = Path(__file__).resolve().parent / "skills" / "agent-catalog"
+
+app = typer.Typer(
+    help="Scan a directory for AI-assistant skills, rules and subagents, then copy selected ones into a project.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+console = Console()
+
+_KIND_LABEL = {"skill": "skills", "agent": "agents", "rule": "rules"}
+
+add_app = typer.Typer(
+    help="Additively index skill, plugin, agent and rule collections into the cache.",
+    no_args_is_help=True,
+)
+pick_app = typer.Typer(
+    help="Interactively select indexed artifacts and copy them into a project.",
+    no_args_is_help=True,
+)
+app.add_typer(add_app, name="add")
+app.add_typer(pick_app, name="pick")
+
+# Shared parameter defaults reused across the `add` / `pick` subcommands (DRY).
+TARGET_DIR_ARG = typer.Argument(
+    ...,
+    exists=True,
+    file_okay=False,
+    dir_okay=True,
+    readable=True,
+    resolve_path=True,
+    help="Directory to scan for skill/plugin/agent/rule collections.",
+)
+TERM_ARG = typer.Argument(
+    None,
+    metavar="[TERM]",
+    help=(
+        "Optional case-insensitive substring matched against artifact name and "
+        "description to pre-filter the picker. Omit to list everything."
+    ),
+)
+TARGET_OPT = typer.Option(
+    Path.cwd(), "--target", "-t", resolve_path=True, help="Project root to copy into."
+)
+ASSISTANT_OPT = typer.Option(
+    None, "--assistant", "-a", help="Skip the prompt and use this assistant root."
+)
+OVERWRITE_OPT = typer.Option(
+    False,
+    "--overwrite",
+    help=(
+        "Replace artifacts that already exist at the destination (skills merge over the "
+        "folder, overwriting overlapping files; single files are replaced). Without it, "
+        "existing targets are skipped."
+    ),
+)
+
+
+@app.command()
+def init(
+    target_dir: Path = typer.Argument(
+        ...,
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        readable=True,
+        resolve_path=True,
+        help="Directory to scan for .agents/.cursor/.claude/.github/.codex configs.",
+    ),
+) -> None:
+    """Scan TARGET_DIR and cache discovered skills, subagents and rules."""
+    catalog = scanner.scan(target_dir)
+    path = cache_mod.write_cache(catalog)
+
+    table = Table(title="Indexed artifacts")
+    table.add_column("Kind")
+    table.add_column("Count", justify="right")
+    table.add_row("Skills", str(len(catalog.skills)))
+    table.add_row("Agents", str(len(catalog.agents)))
+    table.add_row("Rules", str(len(catalog.rules)))
+    console.print(table)
+    console.print(f"Cache written to [bold]{path}[/bold]")
+
+
+def _add(new: list[Artifact], kind: Kind) -> None:
+    catalog = cache_mod.append_artifacts(new)
+    total = len(catalog.by_kind(kind))
+    console.print(
+        f"Added [bold]{len(new)}[/bold] {kind}(s); cache now has {total} {kind}(s)."
+    )
+
+
+@add_app.command("skills")
+def add_skills(target_dir: Path = TARGET_DIR_ARG) -> None:
+    """Find skills/<skill> packages under TARGET_DIR and add them to the cache."""
+    _add(scanner.scan_collections(target_dir, scanner.SKILL_COLLECTION_DIRS), "skill")
+
+
+# Suspended for now: re-enable by uncommenting to restore `add plugins`.
+# @add_app.command("plugins")
+# def add_plugins(target_dir: Path = TARGET_DIR_ARG) -> None:
+#     """Find claude-plugin/<skill> and cursor-plugin/<skill> packages under TARGET_DIR and add them."""
+#     _add(scanner.scan_collections(target_dir, scanner.PLUGIN_COLLECTION_DIRS), "skill")
+
+
+@add_app.command("agents")
+def add_agents(target_dir: Path = TARGET_DIR_ARG) -> None:
+    """Find *.md under agents/ folders anywhere under TARGET_DIR and add them to the cache."""
+    _add(scanner.scan_agent_collections(target_dir), "agent")
+
+
+@add_app.command("rules")
+def add_rules(target_dir: Path = TARGET_DIR_ARG) -> None:
+    """Find rules under rules//instructions/ folders (plus memory files) under TARGET_DIR and add them."""
+    _add(scanner.scan_rule_collections(target_dir), "rule")
+
+
+def _load_catalog() -> Catalog:
+    try:
+        return cache_mod.read_cache()
+    except FileNotFoundError:
+        console.print(
+            "[red]No cache found.[/red] Run [bold]agent-catalog init <target_dir>[/bold] first."
+        )
+        raise typer.Exit(code=1)
+
+
+def _choice_label(a: Artifact) -> str:
+    desc = a.description.strip().replace("\n", " ")
+    if len(desc) > 100:
+        desc = desc[:97] + "..."
+    suffix = f" - {desc}" if desc else ""
+    return f"[{a.source_root}] {a.name}{suffix}"
+
+
+def _filter(artifacts: list[Artifact], term: Optional[str]) -> list[Artifact]:
+    if not term:
+        return artifacts
+    t = term.lower()
+    return [a for a in artifacts if t in a.name.lower() or t in a.description.lower()]
+
+
+def _pick(
+    kind: Kind,
+    target: Path,
+    assistant: Optional[str],
+    overwrite: bool,
+    term: Optional[str] = None,
+) -> None:
+    catalog = _load_catalog()
+    artifacts = _filter(catalog.by_kind(kind), term)
+    label = _KIND_LABEL[kind]
+
+    if not artifacts:
+        suffix = f" matching '{term}'" if term else ""
+        console.print(f"[yellow]No {label}{suffix} indexed.[/yellow]")
+        raise typer.Exit(code=0)
+
+    choices = [questionary.Choice(title=_choice_label(a), value=a) for a in artifacts]
+    selected: list[Artifact] = (
+        questionary.checkbox(
+            f"Select {label} to copy (type to filter, Space to toggle, Enter to confirm):",
+            choices=choices,
+            use_search_filter=True,
+            use_jk_keys=False,
+        ).ask()
+        or []
+    )
+    if not selected:
+        console.print("[yellow]Nothing selected.[/yellow]")
+        raise typer.Exit(code=0)
+
+    if assistant is None:
+        assistant = questionary.select(
+            "Copy into which coding assistant?",
+            choices=dest_mod.ASSISTANTS,
+        ).ask()
+    if assistant is None:
+        console.print("[yellow]No assistant chosen.[/yellow]")
+        raise typer.Exit(code=0)
+    if assistant not in dest_mod.ASSISTANTS:
+        console.print(f"[red]Unknown assistant '{assistant}'.[/red]")
+        raise typer.Exit(code=1)
+
+    dest_dir = dest_mod.destination_dir(target, assistant, kind)
+    results = install(selected, dest_dir, overwrite=overwrite)
+    _print_results(results)
+
+
+def _print_results(results: list[CopyResult]) -> None:
+    for r in results:
+        if r.status == "copied":
+            console.print(f"[green]copied[/green] {r.artifact.name} -> {r.destination}")
+        elif r.status == "skipped":
+            console.print(
+                f"[yellow]skipped[/yellow] {r.artifact.name} (exists; use --overwrite) -> {r.destination}"
+            )
+        else:
+            console.print(f"[red]missing[/red] {r.artifact.name} (source gone: {r.artifact.path})")
+
+
+@pick_app.command("skills")
+def pick_skills(
+    term: Optional[str] = TERM_ARG,
+    target: Path = TARGET_OPT,
+    assistant: Optional[str] = ASSISTANT_OPT,
+    overwrite: bool = OVERWRITE_OPT,
+) -> None:
+    """Select indexed skills and copy them into a project. TERM is optional; when given it pre-filters by name/description."""
+    _pick("skill", target, assistant, overwrite, term=term)
+
+
+@pick_app.command("agents")
+def pick_agents(
+    term: Optional[str] = TERM_ARG,
+    target: Path = TARGET_OPT,
+    assistant: Optional[str] = ASSISTANT_OPT,
+    overwrite: bool = OVERWRITE_OPT,
+) -> None:
+    """Select indexed subagents and copy them into a project. TERM is optional; when given it pre-filters by name/description."""
+    _pick("agent", target, assistant, overwrite, term=term)
+
+
+@pick_app.command("rules")
+def pick_rules(
+    term: Optional[str] = TERM_ARG,
+    target: Path = TARGET_OPT,
+    assistant: Optional[str] = ASSISTANT_OPT,
+    overwrite: bool = OVERWRITE_OPT,
+) -> None:
+    """Select indexed rules and copy them into a project. TERM is optional; when given it pre-filters by name/description."""
+    _pick("rule", target, assistant, overwrite, term=term)
+
+
+@app.command("install-skill")
+def install_skill(
+    target: Path = typer.Option(
+        Path.cwd(),
+        "--target",
+        "-t",
+        resolve_path=True,
+        help="Root to install into ('.' for the current workspace, '~' for global).",
+    ),
+    assistant: str = typer.Option(
+        ".cursor", "--assistant", "-a", help="Assistant folder convention to install under."
+    ),
+    overwrite: bool = typer.Option(
+        False, "--overwrite", help="Replace the skill if it already exists at the destination."
+    ),
+) -> None:
+    """Install the bundled agent-catalog management skill into TARGET/<assistant>/skills/."""
+    if assistant not in dest_mod.ASSISTANTS:
+        console.print(f"[red]Unknown assistant '{assistant}'.[/red]")
+        raise typer.Exit(code=1)
+    if not (SELF_SKILL_DIR / "SKILL.md").is_file():
+        console.print(f"[red]Bundled skill not found at {SELF_SKILL_DIR}.[/red]")
+        raise typer.Exit(code=1)
+
+    artifact = Artifact(
+        kind="skill",
+        name=SELF_SKILL_DIR.name,
+        description="agent-catalog management skill",
+        path=str(SELF_SKILL_DIR),
+        source_root="agents_catalog",
+    )
+    dest_dir = dest_mod.destination_dir(target, assistant, "skill")
+    _print_results(install([artifact], dest_dir, overwrite=overwrite))
+
+
+if __name__ == "__main__":
+    app()

{agent_catalog_cli-0.1.0 → agent_catalog_cli-0.2.0}/agents_catalog/cache.py

@@ -29,12 +29,16 @@ def read_cache(directory: Path | None = None) -> Catalog:
     return Catalog.from_dict(data)
 
 
-def append_skills(new_skills: list[Artifact], directory: Path | None = None) -> Catalog:
-    """Additively merge new skills into the cache (deduped by absolute path)."""
+def append_artifacts(new: list[Artifact], directory: Path | None = None) -> Catalog:
+    """Additively merge new artifacts into the cache by kind (deduped by path)."""
     try:
         catalog = read_cache(directory)
     except FileNotFoundError:
         catalog = Catalog(source=str((directory or Path.cwd()).resolve()))
-    catalog.skills = scanner.dedup(catalog.skills + new_skills)
+    for artifact in new:
+        catalog.by_kind(artifact.kind).append(artifact)
+    catalog.skills = scanner.dedup(catalog.skills)
+    catalog.agents = scanner.dedup(catalog.agents)
+    catalog.rules = scanner.dedup(catalog.rules)
     write_cache(catalog, directory)
     return catalog

{agent_catalog_cli-0.1.0 → agent_catalog_cli-0.2.0}/agents_catalog/scanner.py

@@ -20,9 +20,11 @@ ROOT_RULE_FILES = {".github": ("custom-instructions.md",)}
 # Directories skipped while searching for memory files.
 SKIP_DIRS = {".git", ".venv", "node_modules", "__pycache__", ".obsidian"}
 
-# Patterned skill-collection folder names indexed by the additive index-* commands.
+# Patterned collection folder names indexed by the additive `add` subcommands.
 SKILL_COLLECTION_DIRS = {"skills"}
 PLUGIN_COLLECTION_DIRS = {"claude-plugin", "cursor-plugin"}
+AGENT_COLLECTION_DIRS = {"agents"}
+RULE_COLLECTION_DIRS = {"rules", "instructions"}
 
 
 def _read_text(path: Path) -> str:
@@ -126,35 +128,80 @@ def _rule_artifact(file: Path, root_name: str) -> Artifact:
     )
 
 
-def _scan_root(root: Path, root_name: str) -> tuple[list[Artifact], list[Artifact], list[Artifact]]:
-    skills: list[Artifact] = []
-    agents: list[Artifact] = []
-    rules: list[Artifact] = []
+def _find_skill_dirs(base: Path) -> list[Path]:
+    """Resolved package dirs of every SKILL.md under ``base``."""
+    return [m.parent.resolve() for m in base.rglob(SKILL_FILE) if m.is_file()]
+
 
-    skill_dirs: list[Path] = []
-    for skill_md in root.rglob(SKILL_FILE):
-        if skill_md.is_file():
-            skills.append(_skill_artifact(skill_md, root_name))
-            skill_dirs.append(skill_md.parent.resolve())
+def _inside_skill(path: Path, skill_dirs: list[Path]) -> bool:
+    rp = path.resolve()
+    return any(rp == d or d in rp.parents for d in skill_dirs)
 
-    def inside_skill(p: Path) -> bool:
-        rp = p.resolve()
-        return any(rp == d or d in rp.parents for d in skill_dirs)
 
-    for agents_dir in root.rglob("agents"):
-        if not agents_dir.is_dir() or inside_skill(agents_dir):
+def _is_skipped(path: Path, base: Path) -> bool:
+    try:
+        rel = path.relative_to(base)
+    except ValueError:
+        return False
+    return any(part in SKIP_DIRS for part in rel.parts)
+
+
+def _collect_agents(
+    base: Path,
+    skill_dirs: list[Path],
+    source_root: str | None = None,
+    exclude_skip: bool = False,
+) -> list[Artifact]:
+    """``*.md`` directly under any ``agents/`` dir, ignoring skill-internal ones.
+
+    ``source_root`` overrides the recorded root; when ``None`` the containing
+    folder name is used (the collection-add convention)."""
+    out: list[Artifact] = []
+    for agents_dir in base.rglob("agents"):
+        if not agents_dir.is_dir() or _inside_skill(agents_dir, skill_dirs):
+            continue
+        if exclude_skip and _is_skipped(agents_dir, base):
             continue
+        sr = agents_dir.name if source_root is None else source_root
         for file in sorted(agents_dir.glob("*.md")):
             if file.is_file():
-                agents.append(_agent_artifact(file, root_name))
+                out.append(_agent_artifact(file, sr))
+    return out
+
 
-    rule_dirs = list(root.rglob("rules")) + list(root.rglob("instructions"))
+def _collect_rules(
+    base: Path,
+    skill_dirs: list[Path],
+    source_root: str | None = None,
+    exclude_skip: bool = False,
+) -> list[Artifact]:
+    """``*.md`` / ``*.mdc`` recursively under any ``rules/`` or ``instructions/`` dir."""
+    out: list[Artifact] = []
+    rule_dirs = sorted(
+        (d for name in RULE_COLLECTION_DIRS for d in base.rglob(name)),
+        key=str,
+    )
     for rules_dir in rule_dirs:
-        if not rules_dir.is_dir() or inside_skill(rules_dir):
+        if not rules_dir.is_dir() or _inside_skill(rules_dir, skill_dirs):
+            continue
+        if exclude_skip and _is_skipped(rules_dir, base):
             continue
+        sr = rules_dir.name if source_root is None else source_root
         for file in sorted(rules_dir.rglob("*")):
-            if file.is_file() and file.suffix in RULE_SUFFIXES and not inside_skill(file):
-                rules.append(_rule_artifact(file, root_name))
+            if (
+                file.is_file()
+                and file.suffix in RULE_SUFFIXES
+                and not _inside_skill(file, skill_dirs)
+            ):
+                out.append(_rule_artifact(file, sr))
+    return out
+
+
+def _scan_root(root: Path, root_name: str) -> tuple[list[Artifact], list[Artifact], list[Artifact]]:
+    skill_dirs = _find_skill_dirs(root)
+    skills = [_skill_artifact(d / SKILL_FILE, root_name) for d in skill_dirs]
+    agents = _collect_agents(root, skill_dirs, source_root=root_name)
+    rules = _collect_rules(root, skill_dirs, source_root=root_name)
 
     for filename in ROOT_RULE_FILES.get(root_name, ()):
         candidate = root / filename
@@ -193,6 +240,23 @@ def scan_collections(target_dir: Path, folder_names: set[str]) -> list[Artifact]
     return out
 
 
+def scan_agent_collections(target_dir: Path) -> list[Artifact]:
+    """Index ``*.md`` under any ``agents/`` folder anywhere under target_dir."""
+    target_dir = target_dir.resolve()
+    skill_dirs = _find_skill_dirs(target_dir)
+    return _collect_agents(target_dir, skill_dirs, exclude_skip=True)
+
+
+def scan_rule_collections(target_dir: Path) -> list[Artifact]:
+    """Index rules under any ``rules/`` / ``instructions/`` folder anywhere under
+    target_dir, plus CLAUDE.md / AGENTS.md memory files."""
+    target_dir = target_dir.resolve()
+    skill_dirs = _find_skill_dirs(target_dir)
+    rules = _collect_rules(target_dir, skill_dirs, exclude_skip=True)
+    rules.extend(_scan_memory_files(target_dir))
+    return rules
+
+
 def dedup(artifacts: list[Artifact]) -> list[Artifact]:
     seen: set[str] = set()
     out: list[Artifact] = []

agent_catalog_cli-0.2.0/agents_catalog/skills/agent-catalog/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: agent-catalog
+description: Manage a catalog of AI-assistant skills, subagents and rules with the agent-catalog CLI, and install selected ones into the current workspace or the global agent skills. Use when the user wants to catalog, index, search, find, add, or install skills/subagents/rules, or set up reusable agent assets in a workspace.
+---
+
+# agent-catalog
+
+Drive the `agent-catalog` CLI to build a catalog of reusable AI-assistant assets (skills, subagents, rules) and install the right ones into the workspace you operate in or into the global agent skills.
+
+## Prerequisite
+
+The `agent-catalog` command. From the CLI repo: `uv run agent-catalog ...`. Installed globally: `pip install agent-catalog-cli`, then `agent-catalog ...`. Examples below use the bare command.
+
+## Build / refresh the catalog (non-interactive)
+
+These commands take a directory and write/append `.agent-catalog.json` in the current directory. Safe to run unattended.
+
+- `agent-catalog init <dir>` — scan the config roots `.agents/ .cursor/ .claude/ .github/ .codex/` under `<dir>` (overwrites the cache).
+- `agent-catalog add skills <dir>` — additively index `skills/<skill>/` packages found anywhere under `<dir>`.
+- `agent-catalog add plugins <dir>` — additively index `claude-plugin/<skill>/` and `cursor-plugin/<skill>/` packages.
+- `agent-catalog add agents <dir>` — additively index `*.md` under any `agents/` folder.
+- `agent-catalog add rules <dir>` — additively index `*.md` / `*.mdc` under any `rules/` or `instructions/` folder, plus `CLAUDE.md` / `AGENTS.md` memory files.
+
+`add ...` append and dedupe by absolute path, so re-runs and overlap with `init` are safe.
+
+## Discover / search (read the cache directly)
+
+To list or filter what is available before installing, read `.agent-catalog.json`. It has `skills`, `agents`, `rules` arrays; each entry carries `name`, `description`, `path`, `source_root`. Filter on `name`/`description` to pick targets — no extra tooling needed.
+
+## Install into the workspace or globally (via CLI)
+
+Installation is done with the `pick` commands. `--target` chooses the root and `--assistant` the folder convention; together they decide where files land (`<target>/<assistant>/skills/<name>/`).
+
+- Current workspace: `agent-catalog pick skills --target . --assistant .cursor` → `./.cursor/skills/<name>/`
+- Global agent skills: `agent-catalog pick skills --target ~ --assistant .cursor` → `~/.cursor/skills/<name>/`
+- Pre-filter a large catalog: `agent-catalog pick skills <term> --target . --assistant .cursor` (optional `<term>`, case-insensitive over name/description).
+- Subagents and rules: same flags with `pick agents` / `pick rules`.
+- Add `--overwrite` to replace assets that already exist at the destination.
+
+`pick ...` opens an interactive checkbox (requires a TTY): run the command, then the human selects entries (type to filter, Space to toggle, Enter to confirm) and chooses the assistant if `--assistant` was omitted. `init` and `add ...` need no interaction.
+
+## Install this skill
+
+This management skill ships inside the package. Install it directly (non-interactive):
+
+- Workspace: `agent-catalog install-skill --target . --assistant .cursor` → `./.cursor/skills/agent-catalog/`
+- Global: `agent-catalog install-skill --target ~ --assistant .cursor` → `~/.cursor/skills/agent-catalog/`
+
+Add `--overwrite` to refresh an existing copy.
+
+## When not to use
+
+- One-off file copies of a single known path — just copy it.
+- Authoring or editing skill contents — use `create-skill`. This skill catalogs and installs existing assets; it does not write them.

{agent_catalog_cli-0.1.0 → agent_catalog_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-catalog-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "Scan a directory for AI-assistant skills, rules and subagents and copy selected ones into a chosen assistant's folder layout."
 readme = "README.md"
 requires-python = ">=3.12"

{agent_catalog_cli-0.1.0 → agent_catalog_cli-0.2.0}/uv.lock

@@ -4,7 +4,7 @@ requires-python = ">=3.12"
 
 [[package]]
 name = "agent-catalog-cli"
-version = "0.1.0"
+version = "0.1.1"
 source = { editable = "." }
 dependencies = [
     { name = "questionary" },

agent_catalog_cli-0.1.0/agents_catalog/app.py

@@ -1,292 +0,0 @@
-"""Typer CLI: index AI-assistant artifacts and copy selected ones into a project."""
-
-from __future__ import annotations
-
-from pathlib import Path
-from typing import Optional
-
-import questionary
-import typer
-from rich.console import Console
-from rich.table import Table
-
-from . import cache as cache_mod
-from . import destinations as dest_mod
-from . import scanner
-from .installer import install
-from .models import Artifact, Catalog, Kind
-
-app = typer.Typer(
-    help="Scan a directory for AI-assistant skills, rules and subagents, then copy selected ones into a project.",
-    no_args_is_help=True,
-    add_completion=False,
-)
-console = Console()
-
-_KIND_LABEL = {"skill": "skills", "agent": "agents", "rule": "rules"}
-
-
-@app.command()
-def init(
-    target_dir: Path = typer.Argument(
-        ...,
-        exists=True,
-        file_okay=False,
-        dir_okay=True,
-        readable=True,
-        resolve_path=True,
-        help="Directory to scan for .agents/.cursor/.claude/.github/.codex configs.",
-    ),
-) -> None:
-    """Scan TARGET_DIR and cache discovered skills, subagents and rules."""
-    catalog = scanner.scan(target_dir)
-    path = cache_mod.write_cache(catalog)
-
-    table = Table(title="Indexed artifacts")
-    table.add_column("Kind")
-    table.add_column("Count", justify="right")
-    table.add_row("Skills", str(len(catalog.skills)))
-    table.add_row("Agents", str(len(catalog.agents)))
-    table.add_row("Rules", str(len(catalog.rules)))
-    console.print(table)
-    console.print(f"Cache written to [bold]{path}[/bold]")
-
-
-def _index_collections(target_dir: Path, folders: set[str]) -> None:
-    new = scanner.scan_collections(target_dir, folders)
-    catalog = cache_mod.append_skills(new)
-    console.print(
-        f"Indexed [bold]{len(new)}[/bold] skill(s); cache now has {len(catalog.skills)} skill(s)."
-    )
-
-
-@app.command("index-skills")
-def index_skills(
-    target_dir: Path = typer.Argument(
-        ...,
-        exists=True,
-        file_okay=False,
-        dir_okay=True,
-        readable=True,
-        resolve_path=True,
-        help="Directory to search for skills/<skill> packages.",
-    ),
-) -> None:
-    """Find skills/<skill> packages under TARGET_DIR and add them to the cache."""
-    _index_collections(target_dir, scanner.SKILL_COLLECTION_DIRS)
-
-
-@app.command("index-plugins")
-def index_plugins(
-    target_dir: Path = typer.Argument(
-        ...,
-        exists=True,
-        file_okay=False,
-        dir_okay=True,
-        readable=True,
-        resolve_path=True,
-        help="Directory to search for claude-plugin/<skill> and cursor-plugin/<skill> packages.",
-    ),
-) -> None:
-    """Find claude-plugin/<skill> and cursor-plugin/<skill> packages under TARGET_DIR and add them to the cache."""
-    _index_collections(target_dir, scanner.PLUGIN_COLLECTION_DIRS)
-
-
-def _load_catalog() -> Catalog:
-    try:
-        return cache_mod.read_cache()
-    except FileNotFoundError:
-        console.print(
-            "[red]No cache found.[/red] Run [bold]agent-catalog init <target_dir>[/bold] first."
-        )
-        raise typer.Exit(code=1)
-
-
-def _choice_label(a: Artifact) -> str:
-    desc = a.description.strip().replace("\n", " ")
-    if len(desc) > 100:
-        desc = desc[:97] + "..."
-    suffix = f" - {desc}" if desc else ""
-    return f"[{a.source_root}] {a.name}{suffix}"
-
-
-def _filter(artifacts: list[Artifact], term: Optional[str]) -> list[Artifact]:
-    if not term:
-        return artifacts
-    t = term.lower()
-    return [a for a in artifacts if t in a.name.lower()]
-
-
-def _pick(
-    kind: Kind,
-    target: Path,
-    assistant: Optional[str],
-    overwrite: bool,
-    term: Optional[str] = None,
-) -> None:
-    catalog = _load_catalog()
-    artifacts = _filter(catalog.by_kind(kind), term)
-    label = _KIND_LABEL[kind]
-
-    if not artifacts:
-        suffix = f" matching '{term}'" if term else ""
-        console.print(f"[yellow]No {label}{suffix} indexed.[/yellow]")
-        raise typer.Exit(code=0)
-
-    choices = [questionary.Choice(title=_choice_label(a), value=a) for a in artifacts]
-    selected: list[Artifact] = (
-        questionary.checkbox(
-            f"Select {label} to copy (type to filter, Space to toggle, Enter to confirm):",
-            choices=choices,
-            use_search_filter=True,
-            use_jk_keys=False,
-        ).ask()
-        or []
-    )
-    if not selected:
-        console.print("[yellow]Nothing selected.[/yellow]")
-        raise typer.Exit(code=0)
-
-    if assistant is None:
-        assistant = questionary.select(
-            "Copy into which coding assistant?",
-            choices=dest_mod.ASSISTANTS,
-        ).ask()
-    if assistant is None:
-        console.print("[yellow]No assistant chosen.[/yellow]")
-        raise typer.Exit(code=0)
-    if assistant not in dest_mod.ASSISTANTS:
-        console.print(f"[red]Unknown assistant '{assistant}'.[/red]")
-        raise typer.Exit(code=1)
-
-    dest_dir = dest_mod.destination_dir(target, assistant, kind)
-    results = install(selected, dest_dir, overwrite=overwrite)
-
-    for r in results:
-        if r.status == "copied":
-            console.print(f"[green]copied[/green] {r.artifact.name} -> {r.destination}")
-        elif r.status == "skipped":
-            console.print(
-                f"[yellow]skipped[/yellow] {r.artifact.name} (exists; use --overwrite) -> {r.destination}"
-            )
-        else:
-            console.print(f"[red]missing[/red] {r.artifact.name} (source gone: {r.artifact.path})")
-
-
-@app.command("pick-skills")
-def pick_skills(
-    target: Path = typer.Option(
-        Path.cwd(), "--target", "-t", resolve_path=True, help="Project root to copy into."
-    ),
-    assistant: Optional[str] = typer.Option(
-        None, "--assistant", "-a", help="Skip the prompt and use this assistant root."
-    ),
-    overwrite: bool = typer.Option(
-        False,
-        "--overwrite",
-        help="Replace artifacts that already exist at the destination (skills merge over the folder, overwriting overlapping files; single files are replaced). Without it, existing targets are skipped.",
-    ),
-) -> None:
-    """Interactively select indexed skills and copy them into a project."""
-    _pick("skill", target, assistant, overwrite)
-
-
-@app.command("pick-agents")
-def pick_agents(
-    target: Path = typer.Option(
-        Path.cwd(), "--target", "-t", resolve_path=True, help="Project root to copy into."
-    ),
-    assistant: Optional[str] = typer.Option(
-        None, "--assistant", "-a", help="Skip the prompt and use this assistant root."
-    ),
-    overwrite: bool = typer.Option(
-        False,
-        "--overwrite",
-        help="Replace artifacts that already exist at the destination (skills merge over the folder, overwriting overlapping files; single files are replaced). Without it, existing targets are skipped.",
-    ),
-) -> None:
-    """Interactively select indexed subagents and copy them into a project."""
-    _pick("agent", target, assistant, overwrite)
-
-
-@app.command("pick-rules")
-def pick_rules(
-    target: Path = typer.Option(
-        Path.cwd(), "--target", "-t", resolve_path=True, help="Project root to copy into."
-    ),
-    assistant: Optional[str] = typer.Option(
-        None, "--assistant", "-a", help="Skip the prompt and use this assistant root."
-    ),
-    overwrite: bool = typer.Option(
-        False,
-        "--overwrite",
-        help="Replace artifacts that already exist at the destination (skills merge over the folder, overwriting overlapping files; single files are replaced). Without it, existing targets are skipped.",
-    ),
-) -> None:
-    """Interactively select indexed rules and copy them into a project."""
-    _pick("rule", target, assistant, overwrite)
-
-
-def _resolve_term(term: Optional[str]) -> Optional[str]:
-    return term if term else questionary.text("Filter term:").ask()
-
-
-@app.command("pick-skills:filter")
-def pick_skills_filter(
-    term: Optional[str] = typer.Argument(None, help="Pre-filter by substring in name."),
-    target: Path = typer.Option(
-        Path.cwd(), "--target", "-t", resolve_path=True, help="Project root to copy into."
-    ),
-    assistant: Optional[str] = typer.Option(
-        None, "--assistant", "-a", help="Skip the prompt and use this assistant root."
-    ),
-    overwrite: bool = typer.Option(
-        False,
-        "--overwrite",
-        help="Replace artifacts that already exist at the destination (skills merge over the folder, overwriting overlapping files; single files are replaced). Without it, existing targets are skipped.",
-    ),
-) -> None:
-    """Pre-filter indexed skills by a term, then select and copy them."""
-    _pick("skill", target, assistant, overwrite, term=_resolve_term(term))
-
-
-@app.command("pick-agents:filter")
-def pick_agents_filter(
-    term: Optional[str] = typer.Argument(None, help="Pre-filter by substring in name."),
-    target: Path = typer.Option(
-        Path.cwd(), "--target", "-t", resolve_path=True, help="Project root to copy into."
-    ),
-    assistant: Optional[str] = typer.Option(
-        None, "--assistant", "-a", help="Skip the prompt and use this assistant root."
-    ),
-    overwrite: bool = typer.Option(
-        False,
-        "--overwrite",
-        help="Replace artifacts that already exist at the destination (skills merge over the folder, overwriting overlapping files; single files are replaced). Without it, existing targets are skipped.",
-    ),
-) -> None:
-    """Pre-filter indexed subagents by a term, then select and copy them."""
-    _pick("agent", target, assistant, overwrite, term=_resolve_term(term))
-
-
-@app.command("pick-rules:filter")
-def pick_rules_filter(
-    term: Optional[str] = typer.Argument(None, help="Pre-filter by substring in name."),
-    target: Path = typer.Option(
-        Path.cwd(), "--target", "-t", resolve_path=True, help="Project root to copy into."
-    ),
-    assistant: Optional[str] = typer.Option(
-        None, "--assistant", "-a", help="Skip the prompt and use this assistant root."
-    ),
-    overwrite: bool = typer.Option(
-        False,
-        "--overwrite",
-        help="Replace artifacts that already exist at the destination (skills merge over the folder, overwriting overlapping files; single files are replaced). Without it, existing targets are skipped.",
-    ),
-) -> None:
-    """Pre-filter indexed rules by a term, then select and copy them."""
-    _pick("rule", target, assistant, overwrite, term=_resolve_term(term))
-
-
-if __name__ == "__main__":
-    app()