skillgrep

Search local Agent Skill collections without loading them all into every agent session.

Agents normally advertise every enabled skill's name and description, then load the selected SKILL.md on demand. skillgrep keeps infrequent private or team collections outside that catalog. One routing skill searches their metadata and resolves only the chosen file.

It does not clone, update, install, or execute registered skills.

Install

$ npx skills add vrslev/skillgrep

The skill invokes the dependency-free CLI with uvx skillgrep.

Configure

$ uvx skillgrep add ~/code/team-skills --name team
added  team  2

The name becomes the stable namespace in results such as team:release-workflow. It defaults to the directory name.

Configuration follows the XDG application convention:

${XDG_CONFIG_HOME:-~/.config}/skillgrep/config.json

There is no standard Agent Skills configuration directory. Normal setup uses add, rm, and ls; manual configuration is optional:

{
  "version": 1,
  "registries": {
    "personal": "~/code/personal-skills",
    "team": "~/code/team-skills"
  }
}

The file is created with mode 600 on POSIX systems. Set SKILLGREP_CONFIG or pass --config to use another location.

Example

$ uvx skillgrep q "release incident"
team:incident-release-check  Verify release state and collect incident evidence before taking action.
personal:release-notes  Draft concise release notes from a local Git history.
Next: skillgrep path <registry:skill> [<registry:skill> ...] (choose one or more results, then read each returned SKILL.md).

$ uvx skillgrep path team:incident-release-check personal:release-notes
/Users/example/code/team-skills/delivery/incident-release-check/SKILL.md
/Users/example/code/personal-skills/writing/release-notes/SKILL.md

q returns at most three one-line matches by default; --top N changes the limit. Result lines on stdout omit paths, remotes, and configuration locations. Successful searches also print a next-command hint to stderr, preserving an explicit --config argument when supplied. Pass one or more chosen result identifiers to path, then read each returned SKILL.md completely. Searches with no matches print no hint.

path reveals only the selected files. Ranking is deterministic and uses the query, skill name, and description—no embeddings or model calls.

Commands

skillgrep add PATH [--name NAME]  Register a local collection
skillgrep rm NAME                 Remove a registry
skillgrep ls [--paths]            List registries and skill counts
skillgrep q QUERY [--top N]       Query names and descriptions
skillgrep path SKILL [SKILL ...]  Print selected SKILL.md paths

Registry-qualified identifiers prevent collisions between collections. Duplicate names inside one registry are errors.

Privacy and trust

• Runtime commands read only explicitly registered local directories and make no network requests. Installation and uvx package retrieval require network access.
• Registry paths stay in the local XDG config rather than agent settings or a public dotfiles repository.
• Descriptions are search metadata; do not put secrets in skill frontmatter.
• Registered collections must be trusted because selected files become agent instructions.
• Symlinked skill files resolving outside their registered root are ignored.

How this differs from native discovery

The comparison reflects documented behavior available on 2026-08-26.

Native discovery remains preferable for a small, frequently used set. skillgrep covers the larger searchable tail. It is agent-mediated discovery, not a patch to an agent's native prompt assembler.