Mastering the Skill Registry CLI: Search, Discover, and Install Like a Pro

The Skill Registry CLI (sr) is a command-line tool for searching, previewing, and installing AI agent skills. Use sr search <query> to find skills with semantic search and synonym expansion, sr show <id> to preview content, and sr install <id> to add skills to your project. The CLI supports interactive mode for exploration, custom installation paths, batch scripting, and private registries via the SKILL_REGISTRY_URL environment variable.

Most developers install the Skill Registry CLI, run a quick search, install a skill, and never look back. They use maybe 10% of what the tool can do.

This guide covers the other 90%.

The sr command (shorthand for skill-registry) does more than fetch skills from a registry. It understands synonyms. It forgives typos. It ranks results intelligently. And when you combine it with shell scripting, it becomes a cornerstone of your AI agent workflow.

Let’s dig in.

Interactive Mode vs Direct Mode: Two Ways to Work

The CLI operates in two distinct modes. Most users stumble into one by accident and stick with it. Each has its place.

Direct mode runs a single command and exits:

sr search slack

You get results, the process ends, you’re back in your shell. This is what you want for scripts, CI pipelines, or quick one-off queries.

Interactive mode launches when you run sr with no arguments:

sr

You’ll see a welcome banner and a prompt. Now you’re in a REPL where commands are shorter and context persists:

skill-registry> s slack
# Shows results...

skill-registry> show slack
# Preview the skill...

skill-registry> i slack
# Install it

Notice the difference? In interactive mode, search becomes s, install becomes i. The commands are abbreviated because you’re expected to stay in the shell for a while.

When to use which?

Interactive mode shines during exploration. You’re not sure exactly what you need. You want to search, browse, preview, maybe refine your query, then install. The REPL keeps you in context.

Direct mode wins for automation. A CI script that installs skills should use direct commands. So should any shell one-liner you share with your team. sr install slack is self-documenting. i slack inside a REPL is not.

Here’s a practical example. You’re setting up a new project and want to explore what’s available for Slack integration:

# Start interactive mode
sr

# Inside the REPL
skill-registry> s slack
# See 5 results, want more...

skill-registry> s slack -l 10
# Get 10 results

skill-registry> show slack
# Read the full skill content

skill-registry> i slack
# Done. Exit when ready.

Compare that to the direct equivalent:

sr search slack
sr search slack -l 10
sr show slack
sr install slack

Four separate commands, four separate process invocations. It works, but it’s clunky for exploration.

Search Like a Pro: Understanding What Happens Behind the Query

Typing sr search javascript seems simple. What actually happens is not.

Synonym Expansion

The registry maintains a synonym map. When you search for “js”, the system also searches for “javascript”, “node”, and “nodejs”. You don’t need to know the exact term the skill author used.

This works both ways:

sr search js        # Finds JavaScript skills
sr search node      # Also finds JavaScript skills
sr search py        # Finds Python skills
sr search python    # Same results

The synonym groups cover languages, frameworks, tools, and concepts:

• Languages: js/javascript/node, ts/typescript, py/python, rb/ruby, go/golang, rs/rust
• Frameworks: react/reactjs/nextjs, vue/vuejs/nuxt, angular/ng, express/expressjs
• Databases: postgres/postgresql/pg, mongo/mongodb, redis/cache
• Infrastructure: docker/container, k8s/kubernetes, aws/amazon/cloud
• AI: ai/ml/llm/gpt/claude, openai/chatgpt

Search for “k8s” and you’ll find skills tagged with “kubernetes”. Search for “gpt” and you’ll find skills mentioning “openai”, “llm”, or “claude”.

Field Weighting: Why Certain Results Rank Higher

Not all matches are equal. The search algorithm assigns different weights to different fields:

Field	Weight	Why
ID	3.5	Exact ID match is definitive. Searching “slack” should rank the “slack” skill first.
Name	3.0	The skill name is a strong signal of intent.
Tags	2.5	Tags are curated by authors to describe what the skill does.
Description	1.5	Good context, but may contain tangential mentions.
Content	0.5	Broad matches in the full markdown get low priority.

This means if two skills both mention “slack”, but one has “slack” as its ID and the other merely mentions it in the description, the first ranks dramatically higher.

Multi-Term Searches

Searching for multiple words triggers bonus scoring when all terms match:

sr search "slack notification"

Skills matching both “slack” and “notification” rank higher than those matching only one. The algorithm multiplies the score by 1.5 when all query terms are found.

This lets you narrow results with precision. Instead of wading through all Slack skills, add a second term to find exactly what you need.

Typo Tolerance with Trigram Matching

Make a typo? The CLI often still finds what you want.

sr search javascrpt    # Still finds JavaScript skills
sr search kubernets    # Still finds Kubernetes skills

For terms with 3+ characters, the search calculates trigram similarity. “javascrpt” shares enough three-character sequences with “javascript” to score a match. The threshold is 40% similarity, which catches most common typos without producing garbage results.

This is particularly useful in interactive mode where you’re typing quickly.

The Show Command: Preview Before Committing

The show command (aliases: view, cat) displays a skill’s full content without installing it:

sr show github

You’ll see the complete SKILL.md markdown, including setup instructions, usage examples, and any caveats.

Why does this matter?

Skills aren’t just code. They’re instructions for AI agents. A skill for GitHub might require a gh CLI login. A skill for 1Password might need credential setup. Previewing reveals these requirements before you commit.

In interactive mode, the aliases make this even faster:

skill-registry> cat github

One practical pattern: use show to compare similar skills before deciding which to install. Found three skills for image generation? Preview each one to see which matches your workflow.

Custom Installation Paths: Taking Control

By default, skills install to .claude/<skill-id>/SKILL.md in your current directory:

sr install slack
# Creates: ./.claude/slack/SKILL.md

The --path (or -p) option changes this:

sr install slack -p ./skills/slack/SKILL.md

Why would you do this?

Team-shared locations: Your team might standardize on a shared skills directory. Instead of each developer having their own .claude/ folder, you could install to a centralized location:

sr install slack -p /projects/shared-skills/slack/SKILL.md

Monorepo organization: In a monorepo, you might want skills scoped to specific packages:

sr install github -p ./packages/api/skills/github/SKILL.md
sr install slack -p ./packages/notifications/skills/slack/SKILL.md

Version-controlled skills: If you commit your skills to git (which you should consider), custom paths let you organize them sensibly:

sr install openai-image-gen -p ./agent-skills/image-generation/SKILL.md
sr install openai-whisper -p ./agent-skills/transcription/SKILL.md

The directory structure is created automatically. If /projects/shared-skills/slack/ doesn’t exist, sr creates it.

Batch Workflows: Combining Commands with Shell Scripting

The CLI’s direct mode integrates naturally with shell scripts. Here are patterns that come up repeatedly.

Installing Multiple Skills

A simple loop installs several skills:

#!/bin/bash
skills=("slack" "github" "obsidian" "discord")

for skill in "${skills[@]}"; do
  sr install "$skill"
done

Or as a one-liner:

for skill in slack github obsidian discord; do sr install "$skill"; done

Conditional Installation

Check if a skill is already installed before downloading:

#!/bin/bash
install_if_missing() {
  local skill=$1
  local path=".claude/$skill/SKILL.md"

  if [ ! -f "$path" ]; then
    echo "Installing $skill..."
    sr install "$skill"
  else
    echo "$skill already installed, skipping."
  fi
}

install_if_missing slack
install_if_missing github

Search and Install in One Flow

Parse search results and install interactively:

#!/bin/bash
query=$1
echo "Searching for: $query"
sr search "$query" -l 3

echo ""
read -p "Enter skill ID to install (or 'skip'): " choice

if [ "$choice" != "skip" ]; then
  sr install "$choice"
fi

Project Bootstrap Script

For teams, a bootstrap script ensures everyone has the same skills:

#!/bin/bash
# bootstrap-skills.sh

SKILLS=(
  "slack"
  "github"
  "obsidian"
  "tmux"
)

SKILLS_DIR=".claude"

echo "Setting up project skills..."

for skill in "${SKILLS[@]}"; do
  target="$SKILLS_DIR/$skill/SKILL.md"

  if [ -f "$target" ]; then
    echo "[OK] $skill"
  else
    echo "[INSTALL] $skill"
    sr install "$skill"
  fi
done

echo "Done. All skills ready."

Add this to your project’s README: “Run ./bootstrap-skills.sh after cloning.”

Self-Hosted Registries: Using SKILL_REGISTRY_URL

The public registry at skillregistry.io works for open source skills. But enterprises often need private registries for proprietary skills.

The SKILL_REGISTRY_URL environment variable redirects all CLI traffic:

export SKILL_REGISTRY_URL=https://skills.internal.company.com
sr search proprietary-skill

Now searches hit your internal registry instead of the public one.

Setting Up Permanently

Add to your shell profile (~/.bashrc, ~/.zshrc, etc.):

export SKILL_REGISTRY_URL=https://skills.internal.company.com

Or create an alias for the internal registry while keeping access to the public one:

alias sr-internal="SKILL_REGISTRY_URL=https://skills.internal.company.com sr"
alias sr-public="sr"

Now sr-internal search auth searches your company registry, while sr-public search auth uses skillregistry.io.

Per-Project Configuration

For project-specific registries, use a .env file or direnv:

# .envrc
export SKILL_REGISTRY_URL=https://skills.team.example.com

Team members who use direnv automatically get the right registry when they enter the project directory.

Mixed Usage

Some teams use both public and private registries. A common pattern:

# Install public skills normally
sr install slack
sr install github

# Switch to internal for proprietary skills
SKILL_REGISTRY_URL=https://internal.company.com sr install company-auth
SKILL_REGISTRY_URL=https://internal.company.com sr install company-deploy

Pro Tips: Power User Techniques

Here are techniques that separate casual users from power users.

1. Use the Limit Flag Strategically

The default limit is 5 results. That’s often too few for exploration, too many for precision.

For broad exploration:

sr search api -l 15

For targeted queries where you expect one clear winner:

sr search "github actions" -l 3

2. Chain Show and Install

Preview, then install in one command chain:

sr show slack && sr install slack

The && ensures installation only happens if the preview succeeds. Useful in scripts where you want to abort if a skill doesn’t exist.

3. Use Aliases for Common Patterns

Add to your shell profile:

alias srs="sr search"
alias sri="sr install"
alias srv="sr show"

# Quick install with preview
skill() {
  sr show "$1" && read -p "Install? [y/N] " confirm && [ "$confirm" = "y" ] && sr install "$1"
}

Now skill slack previews and prompts before installing.

4. Leverage Synonym Groups in Queries

Instead of guessing the exact term, use common abbreviations:

sr search db          # Finds database, sql, data skills
sr search auth        # Finds authentication, login, oauth skills
sr search cli         # Finds command, terminal, shell skills

The synonym expansion works in your favor here.

5. Organize Skills by Domain

Use custom paths to create a domain-based structure:

sr install slack -p ./skills/communication/slack/SKILL.md
sr install discord -p ./skills/communication/discord/SKILL.md
sr install github -p ./skills/vcs/github/SKILL.md
sr install obsidian -p ./skills/notes/obsidian/SKILL.md

This organization scales better than a flat .claude/ directory as you add more skills.

6. Script Your Standard Setup

Create a personal sr-setup script that installs your must-have skills:

#!/bin/bash
# ~/bin/sr-setup

skills=(
  github
  slack
  tmux
  obsidian
)

echo "Installing standard skill set..."
for s in "${skills[@]}"; do
  sr install "$s" 2>/dev/null || echo "Skipped $s (already installed or not found)"
done
echo "Setup complete."

Run sr-setup in any new project to get your baseline configuration instantly.

Wrapping Up

The Skill Registry CLI does more than download markdown files. It understands what you’re looking for (synonym expansion), forgives your mistakes (trigram matching), and prioritizes results intelligently (field weighting).

Interactive mode keeps you in flow during exploration. Direct mode integrates with scripts and automation. Custom paths give you control over organization. Environment variables let you run private registries.

Most users never discover these capabilities. Now you’re not most users.

Start with one technique from this guide. Maybe it’s using the -l flag to tune your search results. Maybe it’s setting up a team bootstrap script. Try it in your next project and see the difference.

The CLI is a tool. How well you use it determines how much time you save.