Guide · Agent skill
How to use the Skill Catalog Builder agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Skill Catalog Builder is an agent skill for hosts that load skills from more than one folder, such as a project folder and a user folder. It scans those folders in a fixed precedence order, reads only the metadata at the top of each SKILL.md, and reports duplicate skill names and skipped entries before any full instructions are loaded. This guide explains what it does, how to install it, how to trigger it, and what to check before running its script.
Skill Catalog Builderrohitg00/ai-engineering-from-scratch · MIT Download the skill Quick start
- 1Download and unzip. Download the skill ZIP from this page and unzip it into a folder named skill-catalog-builder.
- 2Place it in a skills folder. Put the folder in ~/.claude/skills/ for personal use or .claude/skills/ for a single project, or upload the ZIP under Settings → Capabilities → Skills.
- 3Check Python 3 and access. Confirm python3 runs and that you can read every directory you plan to pass as a scope.
- 4Review the policy and contract. Read references/discovery-contract.md and assets/scope-policy.json, and confirm the precedence order fits your host.
- 5Review the script. Read scripts/build_catalog.py before running it, since it executes on your local filesystem.
- 6Run the build. Run python3 scripts/build_catalog.py project=PATH user=PATH with scopes from highest to lowest precedence.
- 7Inspect before loading. Check the collisions and omitted arrays, then load only the selected SKILL.md body.
What the skill makes the agent do
An agent skill is a folder containing a SKILL.md file with instructions the agent can load. When a host reads skills from several directories, two skills can share a name, and loading every full instruction body costs context. This skill sets out a discovery step to handle both problems.
The skill follows three disclosure levels. First, the catalog stage reads each skill's name, description, scope and path for routing. Second, activation loads only the selected SKILL.md body under an explicit size budget. Third, execution support loads a directly named file, such as references/schema.md, only when needed.
The host owns the scope locations, precedence order, collision behaviour and budgets. The catalog builder keeps those choices visible in its output: the catalog budget, selected entries, collision resolutions and omissions.
Install the skill in Claude
Download the skill ZIP from this page and unzip it. To make it available to your own Claude Code setup, place the folder in ~/.claude/skills/. To make it available only inside one project, place it in that project's .claude/skills/ folder.
In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside the project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Check the requirements before you run it
The bundled script runs with python3, so Python 3 must be installed. The script needs read access to the skill directories you pass as project=PATH and user=PATH. It runs scripts and does not use the network.
- Python 3 available as python3
- Read access to each directory you pass in
- No network use
Run the catalog build with explicit scopes
List scopes from highest to lowest precedence. The source example passes a project scope and then a user scope. Before you rely on that order, review assets/scope-policy.json, because it is an example host policy and its order is not universal.
Read references/discovery-contract.md first so you know the disclosure levels and path rules. Then run the build command. Its JSON output includes collisions and omitted arrays.
- Read references/discovery-contract.md
- Review assets/scope-policy.json and do not assume its order applies to your host
- Inspect the collisions and omitted arrays in the JSON output
python3 scripts/build_catalog.py project=PATH user=PATHTrigger the skill with natural requests
This skill is infrastructure for an agent host rather than a task skill, so it is triggered by a host that needs multi-directory discovery. Its description covers building a bounded catalog across explicit discovery scopes and reporting collisions before instruction bodies are loaded. A request should make clear that you want skills discovered across several folders with duplicate names reported.
Example request: "Build a skill catalog from my project and user skill folders, and tell me about any duplicate skill names before loading anything."
- "Scan my project and user skill folders and list any name collisions."
- "Build a bounded skill catalog and show what was omitted."
- "Before activating a skill, check the catalog for duplicate names."
Follow the safe activation order
The skill sets a strict order. Run discovery, inspect collisions and omissions, then load only the selected SKILL.md body. Load a direct reference only when that body names it.
Equal-precedence duplicates must not be resolved by filesystem order. Collisions should be resolved by the scope precedence the host defines.
- Never execute a bundled script during discovery
- Never choose an equal-precedence duplicate by incidental filesystem order
- Portable references must be regular files in the skill directory or one immediate subdirectory; absolute paths, .., backslashes, symlinks and deeper chains are rejected
What people use it for
- Letting a host resolve a project skill and a user skill that share a name in a predictable way.
- Reporting which skill entries were skipped, so a developer can see why a skill was not loaded.
- Keeping agent context small by reading only metadata until a skill is selected.
- Studying how progressive disclosure of skills is structured in a host's design.
Frequently asked questions
How do I install the skill-catalog-builder skill?
Download the ZIP from this page and unzip it. Put the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder, or upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
What do I need to run it?
You need Python 3, since the bundled script is run with python3, and read access to the skill directories you pass as project=PATH and user=PATH. The skill runs scripts and does not use the network.
Is the Skill Catalog Builder free, and what licence does it use?
The skill is listed under the MIT licence, as stated in its SKILL.md. The source does not mention pricing, so check the repository for any other terms.
Is it safe to run the bundled script?
The script runs on your local filesystem, so review scripts/build_catalog.py before running it, especially in environments where code must be reviewed first. The skill itself says never to execute a bundled script during discovery.
Why does the catalog report collisions and omissions?
Collisions show skills that share a name, and omissions show skipped entries. Reporting them before any instruction body loads makes the agent's choice of skill deterministic and explainable.
Who should not use this skill?
Ordinary users who just want to use a skill do not need it. It is also unnecessary for hosts that load only a single skill folder, where collision handling adds nothing.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are building or configuring an agent host that reads SKILL.md folders from several directories and you want predictable, explainable handling of duplicate names. If you only want to install and use a task skill, or your host loads a single skill folder, it is not the right tool and you can skip it.
Download the skill