# Update Catalog

> Regenerate catalog.json and llms.txt in the bactopia-py repo root by introspecting pyproject.toml entry points and CLI modules. Use this skill whenever the user asks to update the catalog, refresh catalog.json, sync llms.txt, or after adding/removing/renaming CLI commands. Also use when the user mentions that catalog.json or llms.txt is out of date, stale, or drifted from the actual commands.

- Skill: `bactopia/update-catalog-2` (Agent Skill)
- Install (CLI): `npx get-skill add bactopia/update-catalog-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bactopia/update-catalog-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bactopia (https://skillmd.com/u/bactopia)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/bactopia/update-catalog-2

---


# Update Catalog

Regenerate the two discovery files at the bactopia-py repo root:

- **`catalog.json`** -- machine-readable index of every CLI command (name, description, entry point, category, tags)
- **`llms.txt`** -- AI-discovery surface describing the project, its commands, documentation links, and related projects

Both files drift when commands are added, removed, or renamed. This skill introspects the codebase and rewrites them to match reality.

## Steps

### 1. Safety check

Check for uncommitted edits before overwriting:

```
git status --porcelain catalog.json llms.txt
```

If either file is dirty, show the diff and confirm with the user before proceeding. These files are overwritten in place -- uncommitted changes would be lost.

### 2. Collect the authoritative command list

Read `pyproject.toml` and extract every entry under `[tool.poetry.scripts]`. This is the single source of truth for which commands exist and their entry points.

For each entry, note:
- **name**: the script name (e.g., `bactopia-prepare`)
- **entry_point**: the dotted path (e.g., `bactopia.cli.prepare:main`)
- **module_path**: convert the entry point to a file path (e.g., `bactopia/cli/prepare.py`)

### 3. Read each CLI module for its description

Open each module file and find the description. Commands define their description in one of two places -- check both:

1. **Docstring on the decorated function** -- the function decorated with `@click.command()` or `@click.group()` may have a docstring (e.g., `"""Scaffold Bactopia components."""`)
2. **`help=` parameter in `OPTION_GROUPS`** -- some modules define `click.rich_click.OPTION_GROUPS` with a top-level description

If neither is found, read the first 50 lines of the module for any module-level docstring or comment that describes the command's purpose.

### 4. Assign categories and tags

Infer the category from the module's location in the source tree:

| Module path pattern | Category |
|---|---|
| `cli/pipeline/` | `pipeline` |
| `cli/atb/` | `atb` |
| `cli/pubmlst/` | `pubmlst` |
| `cli/helpers/` | `utility` |
| Top-level `cli/` modules | Infer from purpose (see below) |

For top-level CLI modules, use these category assignments based on what the command does:

- `documentation` -- citations, workflows, status
- `input` -- prepare, search
- `data` -- datasets
- `environment` -- download, prune
- `analysis` -- summary
- `maintenance` -- update
- `development` -- lint, catalog, testing, review, docs, scaffold
- `utility` -- merge-schemas, sysinfo

Generate 3-6 tags per command based on key concepts from the description and the command's domain. Tags should be lowercase and use hyphens for multi-word tags. Look at the existing `catalog.json` for tag style reference.

### 5. Write catalog.json

Write `catalog.json` to the bactopia-py repo root.

Follow this exact schema (match the existing structure):

```json
{
  "name": "bactopia-py",
  "version": "<from pyproject.toml [tool.poetry] version>",
  "description": "Python CLI tools for working with Bactopia",
  "repository": "https://github.com/bactopia/bactopia-py",
  "license": "MIT",
  "python_requires": ">=3.10",
  "command_count": <total number of commands>,
  "commands": [
    {
      "name": "bactopia-<cmd>",
      "description": "<one-line description>",
      "entry_point": "<dotted.path:main>",
      "category": "<category>",
      "tags": ["tag1", "tag2", "..."]
    }
  ]
}
```

Important details:
- Read `pyproject.toml` `[tool.poetry] version` for the version value. Do NOT use `bactopia/__init__.py` -- its `__version__` is `metadata.version("bactopia")`, which resolves the *installed* distribution and silently returns a stale version in any environment with a non-editable install
- Read `pyproject.toml` for the `python_requires` value (under `[tool.poetry.dependencies]` as `python = "^3.10.0"` -- normalize to `>=3.10`)
- Use 2-space indentation (pretty-printed) so diffs are clean
- Order commands: user-facing commands first (alphabetically by name within each group), then pipeline utilities (alphabetically), matching the grouping in `pyproject.toml`
- `command_count` must equal the length of the `commands` array

### 6. Write llms.txt

Write `llms.txt` to the bactopia-py repo root.

Use this structure, updating counts and details to match the current state:

```
# bactopia-py

> Python CLI tools for working with Bactopia, a Nextflow pipeline for complete analysis of bacterial genomes.

<One paragraph describing what bactopia-py provides. Include the total command count, broken down by user-facing vs pipeline utility. Mention the key capabilities: input preparation, public database querying, environment building, dataset management, result summarization, pipeline linting, testing, and database integration. Note the tech stack: Python 3.10+, Poetry, and rich-click.>

## Documentation

- [README](https://github.com/bactopia/bactopia-py/blob/main/README.md): Full documentation with CLI help output for all commands
- [CHANGELOG](https://github.com/bactopia/bactopia-py/blob/main/CHANGELOG.md): Version history
- [Bactopia Documentation](https://bactopia.io/): Main Bactopia pipeline documentation

## Source Code

- [CLI Commands](https://github.com/bactopia/bactopia-py/tree/main/bactopia/cli): <N> user-facing CLI command implementations
- [Pipeline Utilities](https://github.com/bactopia/bactopia-py/tree/main/bactopia/cli/pipeline): <N> scripts called from Nextflow module shell blocks
- [Database Clients](https://github.com/bactopia/bactopia-py/tree/main/bactopia/databases): ENA, NCBI, PubMLST API clients
- [Parsers](https://github.com/bactopia/bactopia-py/tree/main/bactopia/parsers): Output parsers for 20+ bioinformatics tools
- [Lint System](https://github.com/bactopia/bactopia-py/tree/main/bactopia/lint): <N>+ lint rules for modules, subworkflows, and workflows
- [Tests](https://github.com/bactopia/bactopia-py/tree/main/tests): pytest test suite with <N> test modules
- [pyproject.toml](https://github.com/bactopia/bactopia-py/blob/main/pyproject.toml): Build configuration and entry points
- [catalog.json](https://github.com/bactopia/bactopia-py/blob/main/catalog.json): Machine-readable command catalog

## Related Projects

- [bactopia](https://github.com/bactopia/bactopia): Main Bactopia Nextflow pipeline
- [nf-bactopia](https://github.com/bactopia/nf-bactopia): Nextflow plugin providing utility functions for Bactopia pipelines

## Optional

- [AllTheBacteria](https://github.com/iqbal-lab-org/AllTheBacteria): ~2M pre-assembled bacterial genomes
- [PubMLST API Docs](https://bigsdb.readthedocs.io/en/latest/rest.html): Authentication setup for PubMLST commands
- [Citation](https://doi.org/10.1128/mSystems.00190-20): Petit III RA, Read TD, mSystems 2020
```

To fill in the dynamic counts:
- Count user-facing commands vs pipeline utilities from the `pyproject.toml` grouping (pipeline utilities are under the `# Pipeline utility scripts` comment)
- Count lint rules by running: `grep -c "def rule_" bactopia/lint/rules/*.py | awk -F: '{s+=$2} END {print s}'` (per-file counts must be summed; rule functions are named `rule_*`, not `check_*`)
- Count test modules by running: `find tests -name 'test_*.py' | wc -l` (tests live in subdirectories; `ls tests/test_*.py` misses them)

### 7. Show the result

After writing both files, show the user:
- `git diff --stat catalog.json llms.txt` to summarize changes
- Any commands that were added or removed compared to the previous version
- The new `command_count`

Do NOT stage or commit the files -- let the user review the diffs first.

## Notes

- The `pyproject.toml` `[tool.poetry.scripts]` section is the single source of truth. If a command exists there but not in `catalog.json`, it needs to be added. If it's in `catalog.json` but not in `pyproject.toml`, it needs to be removed.
- Some commands use `@click.group()` instead of `@click.command()` (e.g., `scaffold`). These are still single entry points and should appear as one entry in `catalog.json`.
- Pipeline utility scripts (in `cli/pipeline/`) are called from within Nextflow module shell blocks, not directly by users. They still get catalog entries but with category `pipeline`.
- Keep descriptions concise -- one line, no period at the end, starting with a verb or noun phrase.

