Agent Skill Search

Portable skill catalog search for AI agents. MCP server + CLI.

Skills folders eat your agent's context window — every SKILL.md loads whether the task needs it or not. Move them into a catalog and the agent fetches a skill only when it's relevant. Use grep-like search terms to find the right one for your task.

Install

# recommended — isolated tool install
uv tool install agent-skill-search
# or
pip install agent-skill-search

The PyPI distribution is agent-skill-search — the name skill-search on PyPI belongs to an unrelated package. The commands stay skill-search and skill-search-mcp.

Usage

CLI

skill-search --version               # show version
skill-search update                # upgrade to the latest release
skill-search update --check        # show current version only

# Shorthand: `skill-search "<query>"` == `skill-search search "<query>"`.
skill-search "react performance"

# Default catalog dir is `~/.agents/skills-catalog` (persist a custom one with
# `skill-search dirs --set DIR`). Override per command with `--dirs` or
# `SKILL_CATALOG_DIRS=dir1:dir2`. Bare `skill-search` prints help plus the
# active dirs.

export SKILL_CATALOG_DIRS="$HOME/.hermes/skills"

skill-search search "react performance"
skill-search search "planning|prd|guide"   # multiple keywords (OR search)
skill-search view "vercel-react-best-practices"
skill-search list

# Also scan well-known agent skills dirs (opencode, claude, codex, ...).
# Same-named skills are deduplicated; off by default.
skill-search --include-known list        # or SKILL_INCLUDE_KNOWN=1

# `add` COPIES skill dirs into the default catalog (`~/.agents/skills-catalog`
# unless changed with `dirs --set`); the source tree is left untouched.
skill-search add ~/.hermes/skills

# Always shows the active dirs (stderr); inspect or change the default:
skill-search dirs                # show default, config file, known dirs, active dirs
skill-search dirs --set ~/skills # persist DIR as the default catalog
skill-search dirs --reset        # back to ~/.agents/skills-catalog (also: `dirs --set ""`)

MCP server

One command installs it into your client:

skill-search install claude-code   # or opencode / codex / gemini / openclaw / hermes / pi / claude-desktop / chatgpt

See INSTALL.md for per-client details, manual config snippets, the ChatGPT remote-HTTP setup, and troubleshooting.

Agents without an MCP connection can use the CLI directly. Opt in to append a short usage snippet to existing CLAUDE.md/AGENTS.md files (marker-checked, append-only, never created from scratch):

skill-search install gemini --cli-hint

License

MIT — see LICENSE.