Guide · Agent skill
How to use the Skill Registry Indexer agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Skill Registry Indexer (skill name: skill-registry) is an agent skill that keeps a catalogue of the other skills installed on your machine or in a project. Agent skills are folders of instructions that teach an AI agent a specific capability, and this skill makes the agent maintain an index listing each skill's name, trigger text and file path. This guide covers what it does, how to install it, how to trigger it with plain requests, and what it needs before you rely on it.
Skill Registry IndexerGentleman-Programming/gentle-ai · MIT Download the skill Quick start
- 1Download the ZIP. Get the skill-registry ZIP from the directory page.
- 2Unzip into a skills folder. Extract it into ~/.claude/skills/ for personal use or .claude/skills/ inside a project.
- 3Install gentle-ai. Make sure the gentle-ai command-line tool is available so the skill can run its refresh command.
- 4Run the refresh. From the project root, run gentle-ai skill-registry refresh --cwd <project>, adding --force after skill changes.
- 5Check the registry. Confirm .atl/skill-registry.md exists and that the skill count and paths look right.
- 6Trigger it after changes. Ask the agent to update skills or refresh the skill registry after you add, remove, rename or move a skill.
What the skill makes the agent do
After you install, remove, create, move or rename a skill, this skill tells the agent to refresh its registry. The registry is an index, not a summary: the original SKILL.md file stays the source of truth. The index lets another agent or sub-agent quickly find the right skill and read its original instructions by exact path.
The skill also covers delegation. When one agent hands work to sub-agents, it selects the matching registry rows and passes their SKILL.md paths, rather than compressing rules into a shorter version.
- Writes the registry to .atl/skill-registry.md in the project.
- Saves the registry to Engram as topic_key skill-registry when Engram is available.
- Skips the _shared and skill-registry folders when scanning by hand, and prefers project-level skills over user-level skills with the same name.
Install the skill from the ZIP or the Claude apps
Download the ZIP from the directory page and unzip it into one of two locations. Use ~/.claude/skills/ to make the skill available to you across projects, or use a project's .claude/skills/ folder to limit it to that project.
If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal: unzip into ~/.claude/skills/
- Per project: unzip into .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills, then upload
~/.claude/skills/Install the gentle-ai command-line tool
The skill's first choice is the gentle-ai command-line tool, which generates the registry. The skill expects this command, and it will fall back to manual scanning only if the command is unavailable.
Run the refresh command from your project root. Add --force after you change skills so the registry is rebuilt.
gentle-ai skill-registry refresh --cwd <project>Trigger the skill with natural requests
The skill activates on phrases in its trigger text. You do not need to name the skill. Typical requests include asking the agent to update skills, refresh the skill registry, or run the update after you have changed skills. The trigger text also includes the Spanish phrase actualizar skills.
You can also ask it directly after a change, for example once you have added or renamed a skill folder and want other agents to see it.
- "Update skills"
- "Refresh the skill registry"
- "Actualizar skills"
- "I just renamed a skill, update the skill registry"
What the output looks like and how to check it
When the refresh finishes, the agent reports the project name and the .atl/skill-registry.md path, the number of indexed skills, whether the cache was hit or regenerated, and any skipped or duplicate skills. If the project is not a project folder, the refresh is skipped and there is no registry to save.
Each registry row holds the skill name, its trigger or description text, its scope and its exact path, so you can open the source file directly to check it.
- Confirm .atl/skill-registry.md exists in the project.
- Check that the skill count matches what you expect.
- Look at reported duplicates and confirm the project-level copy is the one you want.
Safety notes: scripts and network
This skill runs scripts. The gentle-ai command performs the scan and writes the registry. The skill does not use the network, according to its listing. Because it writes files, review the output before committing it.
The skill writes a .atl/ folder into projects and adds .atl/ to .gitignore when possible, unless that is explicitly disabled. If you do not want either change, turn that off before you run the skill.
- Runs scripts: yes
- Uses network: no
- Writes: .atl/skill-registry.md and, when possible, a line in .gitignore
Tips for getting good results
Run the refresh after every change to the set of skills, using --force so the registry is rebuilt rather than reused. Keep each skill's description specific, because the trigger text is what agents match against when they choose a skill.
The skill's own style guide, docs/skill-style-guide.md, explains how skills should be written before they are indexed. The resolver file, skills/_shared/skill-resolver.md, explains how delegators use the index.
- Use --force after skill changes.
- Give each skill a clear, specific description.
- Read the style guide before writing new skills.
What people use it for
- Keeping an index of many custom skills across several projects so agents pick the right one.
- Giving a delegating agent the exact SKILL.md paths it needs before handing work to sub-agents.
- Refreshing the index after renaming or moving a skill so other agents do not read stale paths.
- Checking which skills are duplicated between a project and your user folder.
Frequently asked questions
Is the skill-registry agent skill free?
The skill is listed under the MIT licence. The gentle-ai tool it relies on is a separate project in the same repository, so check its own licence terms before relying on it.
What do I need to use the skill-registry skill?
You need an agent that supports skills, a place to put the skill folder such as ~/.claude/skills/, and the gentle-ai command-line tool for the refresh command. Without gentle-ai, the skill falls back to scanning folders by hand. Engram is optional for saving the registry.
Where do I install the skill?
Unzip the downloaded ZIP into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps you can upload it under Settings → Capabilities → Skills.
Does the skill need internet access?
No. The listing says it does not use the network, but it does run scripts, so review them as you would any script before running it.
Will it change my project files?
It writes .atl/skill-registry.md and adds .atl/ to .gitignore when possible. You can disable the .gitignore change, but if you do not want a .atl/ folder in your project, this skill is not a good fit.
Is this skill worth it if I only have one or two skills?
Probably not. The index adds little value with only a few skills. It is most useful for people who maintain many custom skills or who run multi-agent workflows.
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 maintain many custom agent skills across projects or run delegating workflows where sub-agents need exact skill file paths. Skip it if you have only a couple of skills, are not comfortable with command-line tools, or do not want a .atl/ folder written into your projects.
Download the skill