Agent Skill Catalog
Build a read-only catalog from explicit local SKILL.md roots and optional
plugin roots. Never install, edit, or execute scanned content. Write only
to the selected output directory.
Two build outcomes exist; name the one you are delivering:
- Preview:
build_catalog.py with explicit roots and, for a fully offline
run, --no-github-discovery --no-github-images. Success is exit code 0 with a
readable index.html; missing Chinese descriptions stay pending and are not a
failure.
- Enriched completion (only when the user asks for full Chinese
descriptions): add
--require-complete-descriptions, complete the Agent-owned
description queue, then rebuild. Success is exit code 0 and
summary.pending_description_count == 0; exit code 3 means that mode is not
finished yet, not that the tool crashed.
Network is optional and off only when the flags above are used. Unless disabled,
a family-primary Skill without repository metadata triggers a bounded GitHub
search by Skill name (api.github.com), candidate repository checks, public
repository page reads for preview images, and one README excerpt per queue item.
Discovery and preview reads may reuse an existing gh/token login and never save
credentials. Use the offline flags when the library must stay off the network.
Workflow
Quick preview of the roots the user named (default first response):
- Choose
--root PATH, or a config labeling each root skill or plugin.
- Run
python scripts/build_catalog.py --root PATH --output-dir OUTPUT --no-github-discovery --no-github-images.
- Report exit code 0 and open
OUTPUT/index.html; state that Chinese descriptions are still pending and that no network was used.
Enriched completion, only when the user asked for full Chinese descriptions. It
still uses the offline flags unless the user separately accepts GitHub network
reads; asking for descriptions is not consent to discovery, images, or README
fetches:
- Run
python scripts/build_catalog.py --root PATH --output-dir OUTPUT --refresh --require-complete-descriptions --no-github-discovery --no-github-images (reuse --config for config builds; --refresh is required when OUTPUT already holds a catalog).
- On exit code 3, run
python scripts/description_queue.py next --root PATH --output-dir OUTPUT --batch-size 12 --no-github-readmes (reuse --config when applicable; drop the offline flags only when the user explicitly accepts those GitHub reads).
- Write evidence-backed Chinese results to
OUTPUT/description-batch.responses.json using response_contract, then run python scripts/description_queue.py apply --output-dir OUTPUT --input OUTPUT/description-batch.responses.json. Repeat until batch_count is zero; progress stays in catalog-curation.json.
- Rebuild with
--refresh --require-complete-descriptions plus the same offline flags; success means exit 0 and summary.pending_description_count == 0.
- Check
summary.image_evidence and every image.status; use only observed GitHub sources.
- Open
index.html, or serve it with python scripts/serve_catalog.py --output-dir OUTPUT --root PATH --require-complete-descriptions (add the same offline flags to keep refreshes offline).
Images and optional public introductions
Select actual Skill images before GitHub: manual/configured override, local frontmatter, sidecars, then local README images. Fetch GitHub images only for remaining gaps. All cover frames are 16:9; preserve originals and animation. See references/image-priority.md.
When the user requests public introductions and the invoking Agent has web access, prepare python scripts/description_queue.py next --root PATH --output-dir OUTPUT --web-research --no-github-readmes (or use the matching config). The Agent uses its available search/browser tools, opens exact-identity matches, and returns the batch contract with web_research: true, factual Chinese descriptions, and sources containing URL, title, retrieval date and identity evidence. Apply with the normal apply command and rebuild with the same roots/config. The details show clickable introduction sources. This mode includes Skills whose local description was already complete.
The Python scripts do not contain a search engine, invoke hidden models, or require a provider key. Search is supplied by the Agent runtime. If it cannot browse, or no exact match is verified, leave that research item unresolved and retain its local description. A normal offline preview never triggers public research.
Output Contract
The output directory contains catalog.json, description-enrichment.json, a
self-contained index.html, and output-owned image/curation files. Absolute
roots stay redacted unless --include-absolute-paths is explicit.
The page's expandable scan report distinguishes raw Skill entries from family cards and exposes unresolved roots, skipped linked directories, and GitHub switches. index_changes compares additions / no-longer-indexed entries only when scan_scope is unchanged; otherwise it starts a new baseline. A missing index entry is not proof of deletion. A shared installation-root README is not inherited as a child Skill's repository identity.
Boundaries
- The Agent, builder, and scanner never modify scanned roots: no installs, edits, deletions, or writes outside the selected output directory. The only source-writing feature in the product is an explicit, opt-in localhost-server deletion described below, which requires operator configuration and full-name confirmation and is never triggered by scanning, building, image selection, or refresh.
- Network is opt-out, not opt-in. Without the flags below, a build may search GitHub by Skill name, verify candidate repositories, read public repository pages and images for observed repositories, and read one README excerpt per queue item; these reads may reuse an existing local
gh/token login and never store credentials. Use --no-github-discovery --no-github-images for an offline build; the description queue additionally needs --no-github-readmes.
- The optional localhost server offers an explicit, opt-in deletion action for one top-level standalone Skill: it runs only when the serving config marks that root
allow_delete: true, the item is an independent top-level Skill, and the request confirms the full Skill name. It is disabled by default in every shipped config, including the Windows example. Never enable it unless the user asks, and a deleted Skill directory is removed from its root. The shipped static page and CLI defaults never delete anything.
- Manual images live in output-owned
curated-images/ and catalog-curation.json; unavailable proof stays missing evidence.
- Skills with the same observed or verified GitHub repository automatically share a family, including independently named Skills without a parent router. Details retain every member and its invocation. Nested entry-point and explicit product-affiliation evidence also remain supported. Different repositories, plugin identities, and unverified same-name matches stay separate; manual family overrides win.
- Refresh reuses recorded roots, config, and curation; HTTP callers cannot supply roots, config, or command arguments. The queue validates Agent-written Chinese copy; these Python scripts never call a hidden model or require a provider key. The Agent runtime that writes that copy is a separate boundary: it may send local Skill evidence to its own model provider, so only the fully offline script preview (
--no-github-discovery --no-github-images, with --no-github-readmes for the queue) is a claim that this tool makes no network request.
Resources
Read references/workflow.md first; load other references only for the matching
configuration, category, image, or prompt task. Maintainer-only evals and release
evidence stay outside the installed Skill boundary.
1---2name: agent-skill-catalog3description: "Build or refresh a local searchable skill catalog for Codex and other AI agents from explicit SKILL.md roots and optional plugin roots. Use for deterministic catalog JSON, desktop HTML, category evidence, GitHub preview images, family grouping, plugin aggregation, and bounded local refresh. Do not install, edit, or execute scanned skills."4license: MIT5metadata:6 source: https://skillmd.com/skills/mianbaofang/agent-skill-catalog7---89# Agent Skill Catalog1011Build a read-only catalog from explicit local `SKILL.md` roots and optional12plugin roots. Never install, edit, or execute scanned content. Write only13to the selected output directory.1415Two build outcomes exist; name the one you are delivering:1617- **Preview**: `build_catalog.py` with explicit roots and, for a fully offline18 run, `--no-github-discovery --no-github-images`. Success is exit code 0 with a19 readable `index.html`; missing Chinese descriptions stay pending and are not a20 failure.21- **Enriched completion** (only when the user asks for full Chinese22 descriptions): add `--require-complete-descriptions`, complete the Agent-owned23 description queue, then rebuild. Success is exit code 0 **and**24 `summary.pending_description_count == 0`; exit code 3 means that mode is not25 finished yet, not that the tool crashed.2627Network is optional and off only when the flags above are used. Unless disabled,28a family-primary Skill without repository metadata triggers a bounded GitHub29search by Skill name (`api.github.com`), candidate repository checks, public30repository page reads for preview images, and one README excerpt per queue item.31Discovery and preview reads may reuse an existing `gh`/token login and never save32credentials. Use the offline flags when the library must stay off the network.3334## Workflow3536Quick preview of the roots the user named (default first response):37381. Choose `--root PATH`, or a config labeling each root `skill` or `plugin`.392. Run `python scripts/build_catalog.py --root PATH --output-dir OUTPUT --no-github-discovery --no-github-images`.403. Report exit code 0 and open `OUTPUT/index.html`; state that Chinese descriptions are still pending and that no network was used.4142Enriched completion, only when the user asked for full Chinese descriptions. It43still uses the offline flags unless the user separately accepts GitHub network44reads; asking for descriptions is not consent to discovery, images, or README45fetches:46474. Run `python scripts/build_catalog.py --root PATH --output-dir OUTPUT --refresh --require-complete-descriptions --no-github-discovery --no-github-images` (reuse `--config` for config builds; `--refresh` is required when `OUTPUT` already holds a catalog).485. On exit code 3, run `python scripts/description_queue.py next --root PATH --output-dir OUTPUT --batch-size 12 --no-github-readmes` (reuse `--config` when applicable; drop the offline flags only when the user explicitly accepts those GitHub reads).496. Write evidence-backed Chinese results to `OUTPUT/description-batch.responses.json` using `response_contract`, then run `python scripts/description_queue.py apply --output-dir OUTPUT --input OUTPUT/description-batch.responses.json`. Repeat until `batch_count` is zero; progress stays in `catalog-curation.json`.507. Rebuild with `--refresh --require-complete-descriptions` plus the same offline flags; success means exit 0 and `summary.pending_description_count == 0`.518. Check `summary.image_evidence` and every `image.status`; use only observed GitHub sources.529. Open `index.html`, or serve it with `python scripts/serve_catalog.py --output-dir OUTPUT --root PATH --require-complete-descriptions` (add the same offline flags to keep refreshes offline).5354## Images and optional public introductions5556Select actual Skill images before GitHub: manual/configured override, local frontmatter, sidecars, then local README images. Fetch GitHub images only for remaining gaps. All cover frames are 16:9; preserve originals and animation. See `references/image-priority.md`.5758When the user requests public introductions and the invoking Agent has web access, prepare `python scripts/description_queue.py next --root PATH --output-dir OUTPUT --web-research --no-github-readmes` (or use the matching config). The Agent uses its available search/browser tools, opens exact-identity matches, and returns the batch contract with `web_research: true`, factual Chinese descriptions, and `sources` containing URL, title, retrieval date and identity evidence. Apply with the normal `apply` command and rebuild with the same roots/config. The details show clickable introduction sources. This mode includes Skills whose local description was already complete.5960The Python scripts do not contain a search engine, invoke hidden models, or require a provider key. Search is supplied by the Agent runtime. If it cannot browse, or no exact match is verified, leave that research item unresolved and retain its local description. A normal offline preview never triggers public research.6162## Output Contract6364The output directory contains `catalog.json`, `description-enrichment.json`, a65self-contained `index.html`, and output-owned image/curation files. Absolute66roots stay redacted unless `--include-absolute-paths` is explicit.6768The page's expandable scan report distinguishes raw Skill entries from family cards and exposes unresolved roots, skipped linked directories, and GitHub switches. `index_changes` compares additions / no-longer-indexed entries only when `scan_scope` is unchanged; otherwise it starts a new baseline. A missing index entry is not proof of deletion. A shared installation-root README is not inherited as a child Skill's repository identity.6970## Boundaries7172- The Agent, builder, and scanner never modify scanned roots: no installs, edits, deletions, or writes outside the selected output directory. The only source-writing feature in the product is an explicit, opt-in localhost-server deletion described below, which requires operator configuration and full-name confirmation and is never triggered by scanning, building, image selection, or refresh.73- Network is opt-out, not opt-in. Without the flags below, a build may search GitHub by Skill name, verify candidate repositories, read public repository pages and images for observed repositories, and read one README excerpt per queue item; these reads may reuse an existing local `gh`/token login and never store credentials. Use `--no-github-discovery --no-github-images` for an offline build; the description queue additionally needs `--no-github-readmes`.74- The optional localhost server offers an explicit, opt-in deletion action for one top-level standalone Skill: it runs only when the serving config marks that root `allow_delete: true`, the item is an independent top-level Skill, and the request confirms the full Skill name. It is disabled by default in every shipped config, including the Windows example. Never enable it unless the user asks, and a deleted Skill directory is removed from its root. The shipped static page and CLI defaults never delete anything.75- Manual images live in output-owned `curated-images/` and `catalog-curation.json`; unavailable proof stays `missing evidence`.76- Skills with the same observed or verified GitHub repository automatically share a family, including independently named Skills without a parent router. Details retain every member and its invocation. Nested entry-point and explicit product-affiliation evidence also remain supported. Different repositories, plugin identities, and unverified same-name matches stay separate; manual family overrides win.77- Refresh reuses recorded roots, config, and curation; HTTP callers cannot supply roots, config, or command arguments. The queue validates Agent-written Chinese copy; these Python scripts never call a hidden model or require a provider key. The Agent runtime that writes that copy is a separate boundary: it may send local Skill evidence to its own model provider, so only the fully offline script preview (`--no-github-discovery --no-github-images`, with `--no-github-readmes` for the queue) is a claim that this tool makes no network request.7879## Resources8081Read `references/workflow.md` first; load other references only for the matching82configuration, category, image, or prompt task. Maintainer-only evals and release83evidence stay outside the installed Skill boundary.