Agents Search — Discovery and Management
Discover, search, and manage Claude Code sub-agents installed under ~/.claude/agents/.
Supports four sub-commands: search, list, fetch, and invalidate.
Arguments
$0 — sub-command: search, list, fetch, or invalidate. If not provided, default to list.
$1 — query string (for search), agent name (for fetch), or --fetch flag (for invalidate).
Sub-Commands
Read-only compute labels for search and list
Read agent definitions as data. These two sub-commands never install, fetch, synchronize,
or change an agent, a catalog, or a runtime setting.
Use a valid, explicitly authored dotbabel.compute declaration when it is available.
An installed native projection can omit that private metadata. In that case, read the
matching canonical source only through an existing, verified Dotbabel projection manifest
and an explicitly known source root. Verify the source identity and hash before using it.
Never guess a source root or follow an unverified generated comment. If the canonical
declaration cannot be verified, report undeclared/legacy.
Keep the authored mode, requirement and binding separate from the installed native model
and effort fields. mode: inherit belongs to the inherit group. Otherwise, group only
by an explicitly declared valid requirement. A dynamic or pinned declaration without an
explicit class belongs to undeclared/legacy, with its mode shown in the demand cell.
An absent or invalid declaration also belongs there; identify invalid metadata instead of
silently treating it as inheritance. Do not infer a demand class from a model name, a tool
list, a missing native model, or a normalized default. These labels describe declared demand,
not measured model quality or native enforcement.
Show native selectors and effort exactly as written, or unset when absent. A native
model: inherit remains a native control; it does not establish canonical inheritance.
search <query>
Find installed agents whose name or description matches a query string.
Steps:
Use Glob to enumerate all files at ~/.claude/agents/*.md.
For each file, use Read to load its content (frontmatter + body). Parse YAML frontmatter
(the block between the first --- and the second ---) to extract:
name (string)
model and effort (native values, may be absent — display unset)
- Canonical compute mode, explicit requirement and binding, using the read-only rules above
tools (array or comma-separated string, may be absent — default to "")
description (string — use only the first line if multi-line)
Perform a case-insensitive substring match of <query> against both name and the first
line of description. Include a file if either field matches.
If one or more agents match, render a markdown table:
| Name | Compute demand | Native model | Native effort | Tools | Description |
| ---- | -------------- | ------------ | ------------- | ----- | ----------- |
| ... | ... | ... | ... | ... | ... |
Tools column: join array entries with ", " or display the raw string; truncate to 40 chars
with … if longer.
Description column: first line of the description field only.
If no agents match, output exactly:
No agents found matching '<query>'
If Glob returns no results (no agents installed), check ~/.claude/cache/agents-catalog.md — if it exists and is less than 12 hours old (use Bash(stat -c %Y ~/.claude/cache/agents-catalog.md 2>/dev/null || stat -f %m ~/.claude/cache/agents-catalog.md 2>/dev/null || echo 0) to check mtime), display results from the catalog instead and note they are from the cached remote catalog.
list
List all installed agents grouped by explicitly declared canonical compute demand.
Steps:
Use Glob to enumerate all files at ~/.claude/agents/*.md.
For each file, Read its frontmatter and extract the same fields as search.
Resolve canonical metadata only through the read-only rules above.
Group agents in this fixed order:
- mechanical — explicit canonical requirement
mechanical
- routine — explicit canonical requirement
routine
- deep — explicit canonical requirement
deep
- frontier — explicit canonical requirement
frontier
- exceptional — explicit canonical requirement
exceptional
- inherit — explicit canonical
mode: inherit
- undeclared/legacy — no verified explicit class or inheritance declaration
For each non-empty group, render a section header and a table. Sort names within
the group alphabetically. Show the canonical mode/class/binding in Compute demand;
keep native controls in their own columns:
### Frontier
| Name | Compute demand | Native model | Native effort | Tools | Description |
| ---- | -------------- | ------------ | ------------- | ----- | ----------- |
If ~/.claude/agents/ does not exist or contains no .md files, output:
No agents installed. Run `/agents:search fetch <name>` to install one.
If Glob returns no results (no agents installed), check ~/.claude/cache/agents-catalog.md — if it exists and is less than 12 hours old (use Bash(stat -c %Y ~/.claude/cache/agents-catalog.md 2>/dev/null || stat -f %m ~/.claude/cache/agents-catalog.md 2>/dev/null || echo 0) to check mtime), display results from the catalog instead and note they are from the cached remote catalog.
fetch <name>
Read a specific agent's full definition and offer install / view options.
Steps:
- Construct the local path
~/.claude/agents/<name>.md.
- Attempt
Read on that path.
- If found locally: display the agent's frontmatter fields (one per line,
key: value)
followed by the full body. Then present the user with options:
- Already installed — offer to re-display or customize.
- Customize — open the file for editing via a follow-up Edit call.
- View only — no further action.
- If not found locally: check whether
~/.claude/cache/agents-catalog.md exists via Read.
If the catalog exists, search it for a section or entry matching <name> (case-insensitive).
If a match is found, display the matching content and offer the user three options:
- Install — write the agent definition to
~/.claude/agents/<name>.md using Write.
- Customize — show the content and ask the user to provide edits before writing.
- View only — no further action.
If the catalog does not exist or contains no match, output:
Agent '<name>' not found locally or in catalog.
Run `/agents:search invalidate --fetch` to refresh the catalog, then try again.
invalidate [--fetch]
Clear the local agent catalog cache, optionally refreshing it from GitHub.
Steps:
If --fetch flag is present: Read the mtime of ~/.claude/cache/agents-catalog.md
now (before deleting anything) using
Bash(stat -c %Y ~/.claude/cache/agents-catalog.md 2>/dev/null || stat -f %m ~/.claude/cache/agents-catalog.md 2>/dev/null || echo 0).
Store the result for informational use later.
Check whether ~/.claude/cache/agents-catalog.md exists via Read.
- If it exists, delete it using
Bash: rm ~/.claude/cache/agents-catalog.md.
- If it does not exist, note "No cache file found."
Without --fetch (cache clear only):
Output:
Cache cleared.
With --fetch (clear and refresh — user explicitly requested a fresh fetch):
- Fetch the catalog using
WebFetch from:
https://raw.githubusercontent.com/VoltAgent/awesome-claude-code-subagents/main/README.md
Use HTTPS only (SEC-3).
If the fetch succeeds, ensure ~/.claude/cache/ exists
(Bash: mkdir -p ~/.claude/cache) and save the content to
~/.claude/cache/agents-catalog.md using Write.
Output:
Catalog refreshed. <N> bytes written to ~/.claude/cache/agents-catalog.md
If the fetch fails (network error, non-200, timeout), do not hard-fail (REL-1).
Warn the user:
Warning: Could not fetch catalog (network error). Existing cache cleared.
Run `/agents:search invalidate --fetch` again when connectivity is restored.
Do not throw or abort; return gracefully.
Cache TTL
Whenever search or list falls back to ~/.claude/cache/agents-catalog.md for data,
check whether the cache is stale before using it:
Run Bash(stat -c %Y ~/.claude/cache/agents-catalog.md 2>/dev/null || stat -f %m ~/.claude/cache/agents-catalog.md 2>/dev/null || echo 0) to get mtime.
If (now - mtime) > 43200 seconds (12 hours), display an inline notice:
(Cache is stale — last updated more than 12 h ago. Run `/agents:search invalidate --fetch` to refresh.)
Then continue with the stale data rather than blocking the user.
Tool Usage
All file I/O uses Claude Code built-in tools — this is a skill, not a shell script:
| Operation |
Tool |
| Enumerate agents |
Glob |
| Read file content / frontmatter |
Read |
| Search catalog content |
Grep |
| Write / install agent |
Write |
| Delete cache file |
Bash(rm <path>) |
| Create cache directory |
Bash(mkdir -p <path>) |
| Check file mtime |
Bash(stat -c %Y <path>) (GNU) / Bash(stat -f %m <path>) (BSD/macOS) |
| Fetch remote catalog |
WebFetch |
Key Principles
- Case-insensitive everywhere. All name and description matching is case-insensitive.
- Graceful degradation. Network failures in
invalidate --fetch warn and continue; they
never abort the session or raise an unhandled error (REL-1).
- HTTPS only. The catalog URL must always use
https:// (SEC-3).
- Read before write. Use
Read to check existing files before Write to avoid blind
overwrites without user confirmation.
- User drives installs. Never silently write to
~/.claude/agents/ without presenting
options and getting implicit or explicit user consent.
- Canonical group order is fixed.
list uses mechanical → routine → deep → frontier →
exceptional → inherit → undeclared/legacy. Native selectors remain separate metadata;
never turn their spelling into a demand class, quality ranking, or enforcement claim.
1---2# dotbabel:generated projection=sha256:44043e576a4fa9bd48597a15fd07f6e460d0617ac35a8df0dfa18381bc3fb7b0 source=skills/agents-search/SKILL.md — do not edit directly3argument-hint: search <query> | list | fetch <name> | invalidate [--fetch]4description: |5 Discover, search, and manage Claude Code agents. Use when you want to find available agents, list installed agents, or refresh the agent catalog. Triggers on: "search agents", "list agents", "find agent", "what agents", "agent catalog".6name: agents-search-37metadata:8 source: https://skillmd.com/skills/kaiohenricunha/agents-search-39---1011# Agents Search — Discovery and Management1213Discover, search, and manage Claude Code sub-agents installed under `~/.claude/agents/`.14Supports four sub-commands: `search`, `list`, `fetch`, and `invalidate`.1516## Arguments1718- `$0` — sub-command: `search`, `list`, `fetch`, or `invalidate`. If not provided, default to `list`.19- `$1` — query string (for `search`), agent name (for `fetch`), or `--fetch` flag (for `invalidate`).2021---2223## Sub-Commands2425### Read-only compute labels for `search` and `list`2627Read agent definitions as data. These two sub-commands never install, fetch, synchronize,28or change an agent, a catalog, or a runtime setting.2930Use a valid, explicitly authored `dotbabel.compute` declaration when it is available.31An installed native projection can omit that private metadata. In that case, read the32matching canonical source only through an existing, verified Dotbabel projection manifest33and an explicitly known source root. Verify the source identity and hash before using it.34Never guess a source root or follow an unverified generated comment. If the canonical35declaration cannot be verified, report **undeclared/legacy**.3637Keep the authored mode, requirement and binding separate from the installed native `model`38and `effort` fields. `mode: inherit` belongs to the **inherit** group. Otherwise, group only39by an explicitly declared valid `requirement`. A dynamic or pinned declaration without an40explicit class belongs to **undeclared/legacy**, with its mode shown in the demand cell.41An absent or invalid declaration also belongs there; identify invalid metadata instead of42silently treating it as inheritance. Do not infer a demand class from a model name, a tool43list, a missing native model, or a normalized default. These labels describe declared demand,44not measured model quality or native enforcement.4546Show native selectors and effort exactly as written, or `unset` when absent. A native47`model: inherit` remains a native control; it does not establish canonical inheritance.4849### `search <query>`5051Find installed agents whose name or description matches a query string.5253**Steps:**54551. Use `Glob` to enumerate all files at `~/.claude/agents/*.md`.562. For each file, use `Read` to load its content (frontmatter + body). Parse YAML frontmatter57 (the block between the first `---` and the second `---`) to extract:58 - `name` (string)59 - `model` and `effort` (native values, may be absent — display `unset`)60 - Canonical compute mode, explicit requirement and binding, using the read-only rules above61 - `tools` (array or comma-separated string, may be absent — default to `""`)62 - `description` (string — use only the first line if multi-line)633. Perform a **case-insensitive substring match** of `<query>` against both `name` and the first64 line of `description`. Include a file if either field matches.654. If one or more agents match, render a markdown table:6667 ```68 | Name | Compute demand | Native model | Native effort | Tools | Description |69 | ---- | -------------- | ------------ | ------------- | ----- | ----------- |70 | ... | ... | ... | ... | ... | ... |71 ```7273 - `Tools` column: join array entries with `", "` or display the raw string; truncate to 40 chars74 with `…` if longer.75 - `Description` column: first line of the `description` field only.76775. If no agents match, output exactly:7879 ```80 No agents found matching '<query>'81 ```82836. If Glob returns no results (no agents installed), check `~/.claude/cache/agents-catalog.md` — if it exists and is less than 12 hours old (use `Bash(stat -c %Y ~/.claude/cache/agents-catalog.md 2>/dev/null || stat -f %m ~/.claude/cache/agents-catalog.md 2>/dev/null || echo 0)` to check mtime), display results from the catalog instead and note they are from the cached remote catalog.8485---8687### `list`8889List all installed agents grouped by explicitly declared canonical compute demand.9091**Steps:**92931. Use `Glob` to enumerate all files at `~/.claude/agents/*.md`.942. For each file, `Read` its frontmatter and extract the same fields as `search`.95 Resolve canonical metadata only through the read-only rules above.963. Group agents in this fixed order:97 - **mechanical** — explicit canonical requirement `mechanical`98 - **routine** — explicit canonical requirement `routine`99 - **deep** — explicit canonical requirement `deep`100 - **frontier** — explicit canonical requirement `frontier`101 - **exceptional** — explicit canonical requirement `exceptional`102 - **inherit** — explicit canonical `mode: inherit`103 - **undeclared/legacy** — no verified explicit class or inheritance declaration1044. For each non-empty group, render a section header and a table. Sort names within105 the group alphabetically. Show the canonical mode/class/binding in `Compute demand`;106 keep native controls in their own columns:107108 ```markdown109 ### Frontier110111 | Name | Compute demand | Native model | Native effort | Tools | Description |112 | ---- | -------------- | ------------ | ------------- | ----- | ----------- |113 ```1141155. If `~/.claude/agents/` does not exist or contains no `.md` files, output:116117 ```118 No agents installed. Run `/agents:search fetch <name>` to install one.119 ```1201216. If Glob returns no results (no agents installed), check `~/.claude/cache/agents-catalog.md` — if it exists and is less than 12 hours old (use `Bash(stat -c %Y ~/.claude/cache/agents-catalog.md 2>/dev/null || stat -f %m ~/.claude/cache/agents-catalog.md 2>/dev/null || echo 0)` to check mtime), display results from the catalog instead and note they are from the cached remote catalog.122123---124125### `fetch <name>`126127Read a specific agent's full definition and offer install / view options.128129**Steps:**1301311. Construct the local path `~/.claude/agents/<name>.md`.1322. Attempt `Read` on that path.133 - **If found locally:** display the agent's frontmatter fields (one per line, `key: value`)134 followed by the full body. Then present the user with options:135 - Already installed — offer to re-display or customize.136 - Customize — open the file for editing via a follow-up Edit call.137 - View only — no further action.1383. **If not found locally:** check whether `~/.claude/cache/agents-catalog.md` exists via `Read`.139 - If the catalog exists, search it for a section or entry matching `<name>` (case-insensitive).140 If a match is found, display the matching content and offer the user three options:141 - Install — write the agent definition to `~/.claude/agents/<name>.md` using `Write`.142 - Customize — show the content and ask the user to provide edits before writing.143 - View only — no further action.144 - If the catalog does not exist or contains no match, output:145146 ```147 Agent '<name>' not found locally or in catalog.148 Run `/agents:search invalidate --fetch` to refresh the catalog, then try again.149 ```150151---152153### `invalidate [--fetch]`154155Clear the local agent catalog cache, optionally refreshing it from GitHub.156157**Steps:**1581591. **If `--fetch` flag is present:** Read the mtime of `~/.claude/cache/agents-catalog.md`160 now (before deleting anything) using161 `Bash(stat -c %Y ~/.claude/cache/agents-catalog.md 2>/dev/null || stat -f %m ~/.claude/cache/agents-catalog.md 2>/dev/null || echo 0)`.162 Store the result for informational use later.1631642. Check whether `~/.claude/cache/agents-catalog.md` exists via `Read`.165 - If it exists, delete it using `Bash`: `rm ~/.claude/cache/agents-catalog.md`.166 - If it does not exist, note "No cache file found."1671683. **Without `--fetch`** (cache clear only):169 Output:170171 ```172 Cache cleared.173 ```1741754. **With `--fetch`** (clear and refresh — user explicitly requested a fresh fetch):176 - Fetch the catalog using `WebFetch` from:177 `https://raw.githubusercontent.com/VoltAgent/awesome-claude-code-subagents/main/README.md`178 - Use HTTPS only (SEC-3).179 - If the fetch succeeds, ensure `~/.claude/cache/` exists180 (`Bash: mkdir -p ~/.claude/cache`) and save the content to181 `~/.claude/cache/agents-catalog.md` using `Write`.182 Output:183184 ```185 Catalog refreshed. <N> bytes written to ~/.claude/cache/agents-catalog.md186 ```187188 - If the fetch fails (network error, non-200, timeout), **do not hard-fail** (REL-1).189 Warn the user:190191 ```192 Warning: Could not fetch catalog (network error). Existing cache cleared.193 Run `/agents:search invalidate --fetch` again when connectivity is restored.194 ```195196 Do not throw or abort; return gracefully.197198---199200## Cache TTL201202Whenever `search` or `list` falls back to `~/.claude/cache/agents-catalog.md` for data,203check whether the cache is stale before using it:2042051. Run `Bash(stat -c %Y ~/.claude/cache/agents-catalog.md 2>/dev/null || stat -f %m ~/.claude/cache/agents-catalog.md 2>/dev/null || echo 0)` to get mtime.2062. If `(now - mtime) > 43200` seconds (12 hours), display an inline notice:207208 ```209 (Cache is stale — last updated more than 12 h ago. Run `/agents:search invalidate --fetch` to refresh.)210 ```211212 Then continue with the stale data rather than blocking the user.213214---215216## Tool Usage217218All file I/O uses Claude Code built-in tools — this is a skill, not a shell script:219220| Operation | Tool |221| ------------------------------- | ----------------------------------------------------------------------- |222| Enumerate agents | `Glob` |223| Read file content / frontmatter | `Read` |224| Search catalog content | `Grep` |225| Write / install agent | `Write` |226| Delete cache file | `Bash(rm <path>)` |227| Create cache directory | `Bash(mkdir -p <path>)` |228| Check file mtime | `Bash(stat -c %Y <path>)` (GNU) / `Bash(stat -f %m <path>)` (BSD/macOS) |229| Fetch remote catalog | `WebFetch` |230231---232233## Key Principles2342351. **Case-insensitive everywhere.** All name and description matching is case-insensitive.2362. **Graceful degradation.** Network failures in `invalidate --fetch` warn and continue; they237 never abort the session or raise an unhandled error (REL-1).2383. **HTTPS only.** The catalog URL must always use `https://` (SEC-3).2394. **Read before write.** Use `Read` to check existing files before `Write` to avoid blind240 overwrites without user confirmation.2415. **User drives installs.** Never silently write to `~/.claude/agents/` without presenting242 options and getting implicit or explicit user consent.2436. **Canonical group order is fixed.** `list` uses mechanical → routine → deep → frontier →244 exceptional → inherit → undeclared/legacy. Native selectors remain separate metadata;245 never turn their spelling into a demand class, quality ranking, or enforcement claim.