skillsearch

TUI-first installer and CLI wrapper for agent skills.

skillsearch lets you search skills from skills.sh, select them in a clean terminal UI, and install them through the upstream skills CLI without making you remember all of its commands.

Quick Start

Run the published package directly with npx:

npx skillsearch

Run with an initial search query:

npx skillsearch react hooks

Run a specific interactive command:

npx skillsearch find testing
npx skillsearch install seo -g -y

Use a direct passthrough command when you already know the source:

npx skillsearch add vercel-labs/agent-skills --skill frontend-design -a codex -y

What It Does

• search skills from skills.sh
• multi-select skills in a terminal UI
• install to .agents/skills by default
• support multiple target agents
• pass through common skills commands when you want raw CLI behavior
• run multi-source installs in the background with one skillsearch progress view

Default Behavior

If you just run:

npx skillsearch

skillsearch will:

1. open a search prompt
2. fetch matching skills
3. let you multi-select them
4. ask which agent(s) to install for
5. ask whether to install to project or global scope
6. install them through the upstream skills package

By default, the first agent choice is:

• Default (.agents/skills)

That maps to the upstream universal agent and installs to:

• project: .agents/skills
• global: ~/.config/agents/skills

Commands

Interactive Commands

These open the skillsearch TUI:

• find
• install
• i
• ins
• no command, just a query
• add when you pass a search query instead of a direct source

Examples:

npx skillsearch react hooks
npx skillsearch find terminal ui
npx skillsearch install accessibility -a claude-code

Direct Passthrough Commands

These are forwarded to the upstream skills CLI:

• add <source>
• list
• ls
• remove
• rm
• r
• update
• upgrade
• init

Examples:

npx skillsearch add vercel-labs/agent-skills --list
npx skillsearch list
npx skillsearch remove frontend-design
npx skillsearch update

Common Flags

These flags work in skillsearch interactive mode:

-a, --agent <id>   Preselect one or more agents
-g, --global       Install globally
-p, --project      Force project scope
-y, --yes          Skip prompts when possible
--all              Select all search results

Examples:

npx skillsearch install seo -g -y
npx skillsearch find terminal ui -a claude-code -a codex
npx skillsearch react --all -y

Supported Agents

skillsearch currently includes the wider upstream agent id set from the skills repo, including:

• universal
• claude-code
• codex
• opencode
• github-copilot
• cursor
• gemini-cli
• windsurf
• and many more

For interactive installs, you can search the agent list directly in the selector UI.

Direct Source Install Examples

List available skills in a repo:

npx skillsearch add vercel-labs/agent-skills --list

Install one skill directly:

npx skillsearch add vercel-labs/agent-skills --skill frontend-design -a universal -y

Install globally for Claude Code:

npx skillsearch add vercel-labs/agent-skills --skill frontend-design -a claude-code -g -y

Local Development

Clone the repo and run locally:

pnpm install
pnpm test
pnpm type-check
pnpm build
node dist/cli.mjs

Useful local commands:

node dist/cli.mjs --help
node dist/cli.mjs --version
node dist/cli.mjs add vercel-labs/agent-skills --list

Notes

• interactive installs require a real TTY
• direct passthrough commands intentionally show the upstream skills output
• TUI installs keep upstream install output in the background and show a single skillsearch progress flow instead

TUI Design Notes

The TUI is intentionally kept simple:

• compact search bar
• searchable multi-select lists
• light metadata instead of dense panels
• one install summary before execution
• quiet background installs for multi-source selections

See docs/tui-research.md for the short research note that shaped the prompt design.