find — Interactively find and install skills

Launch a multi-step interactive TUI to search, configure, and install skills. Supports multi-select for batch installation, with source grouping to clone each repo only once.

xskill find [OPTIONS]

Options:

  • -f, --from <SOURCE> — Filter skills by source name or URL
  • -s, --skill <QUERY> — Pre-fill the filter query
  • -g, --global — Install to global ~/.agents/ directory (default: project-level .agents/)

How it works

  1. Skill selection — Multi-select substring search (exact mode) from cached skills. Display format: name [source] (registry entries show name [registry] [source]). Non-selected names use default color, selected names use blue. Source tags are always dark gray; [registry] tags turn green when selected. Search box at bottom, list arranged upward. Keyboard hints: TAB: multi-select | enter confirm | esc cancel. Press TAB to toggle multiple skills, Enter to confirm. If nothing is toggled, the cursor item is used.
  2. Platform selection — Multi-select target platforms. First item is Default (disabled, means no platform symlinks). agents_compat platforms are excluded from the list and shown as SELECTED: <platform1>, <platform2>, ... in the header. Remaining items are non-compat configured platforms. Press TAB to select/deselect, Enter to confirm. Selected rows use blue text with dark background highlight.
  3. Install — Skills are grouped by source URL; each repo is cloned once. For each skill, the correct path is extracted from CachedSkill.path (supports nested paths like skills/engineering/grill/SKILL.md or root-level my-skill/SKILL.md). The skill is installed to the canonical directory (.agents/skills/<name> or ~/.agents/skills/<name> with -g), then relative symlinks are created for each selected platform. Reports Installed:, Symlinked:, and any Failed: platforms. Each skill’s output is separated by a blank line. Registry skills are cloned directly from their URL, independent of local sources configuration.

Press Esc or Ctrl-C at any step to cancel.

Known issue: skim library list row numbers are 0-based (skim 5.2.0 behavior), not 1-based.

Examples

# Open the interactive finder
xskill find

# Pre-filter for skills matching "git"
xskill find --skill git

# Find only from a specific source
xskill find --from antfu

# Find from a URL (auto-cached for 10 minutes)
xskill find --from https://github.com/example/skills

Note: Requires a populated cache. Run xskill cache update first if you haven’t already. When using a URL with --from, the skill list is fetched and cached automatically.