Files
skillshare/website/docs/reference/commands/search.md
T
Willie 1d0ee69955 feat: support SSH hub sources for private and GHE hosts
Hub index fetch previously handled only unauthenticated HTTP(S) GET or
local file paths, leaving private and GitHub Enterprise repos out of
reach — raw HTTPS URLs redirect to login before token headers apply, and
SSH-style hub URLs were unrecognized.

Resolve SSH hub sources by shallow-cloning the repo with the user's SSH
keys and reading the index from it. The in-repo index path uses the
existing //path subdir convention (consistent with `install`), defaulting
to skillshare-hub.json at the repo root. Both scp-style and ssh:// URLs
are accepted. In the web dashboard, SSH clones are restricted to saved
hubs so a request-supplied URL can't drive an arbitrary clone.

Ref #185
2026-06-02 16:29:25 +08:00

9.1 KiB

sidebar_position
sidebar_position
5

search

Discover and install skills from GitHub repositories.

When to Use

  • Discover community skills from hub indexes
  • Find skills by name, tag, or description
  • Browse available skills before installing

Quick Start

skillshare search vercel       # Search by keyword
skillshare search              # Browse popular skills

This searches GitHub for repositories containing SKILL.md files that match your query.

Browse Mode

When no query is provided, search browses popular skills on GitHub:

skillshare search              # Browse popular skills
skillshare search --list       # List popular skills

This uses filename:SKILL.md as the GitHub query and sorts results by star count, showing the most popular skill repositories first.

How It Works

skillshare search [query]
        │
        ▼
GitHub Code Search API (filename:SKILL.md + query)
        │
        ▼
Fetch star counts for each repository
        │
        ▼
Sort by stars (most popular first)
        │
        ▼
Interactive selector → Install selected skill

Preview

search demo

Controls:

  • ↑ ↓ — Navigate results
  • Enter — Install selected skill
  • Ctrl+C — Cancel and exit
  • Type to filter results

After installing, you can search again or press Enter to quit.

Options

Flag Description
--project, -p Install to project-level config (.skillshare/)
--global, -g Install to global config (~/.config/skillshare)
--hub [URL] Search from a hub index (default: skillshare-hub; or custom URL/path)
--list, -l List results only, no install prompt
--json Output as JSON (for scripting)
--limit N, -n N Maximum results (default: 20, max: 100)
--help, -h Show help

:::tip Auto-detection If neither --project nor --global is specified, skillshare auto-detects: if .skillshare/config.yaml exists in the current directory, it defaults to project mode; otherwise global mode. :::

Examples

skillshare search              # Browse popular skills (no query)
skillshare search pdf           # Interactive search and install
skillshare search "code review" # Multi-word search

List Mode

skillshare search commit --list

Output:

  1.  fix                      facebook/react/.claude/skills/fix        ★ 242.7k
      Use when you have lint errors, formatting issues...
  2.  verify                   facebook/react/.claude/skills/verify     ★ 242.7k
      Use when you want to validate changes before committing...
  3.  commit-helper            cockroachdb/cockroach/.claude/skills/commit-helper ★ 31.8k
      Help create git commits and PRs with properly formatted messages...

JSON Output

skillshare search react --json --limit 5
[
  {
    "Name": "react-patterns",
    "Description": "React and Next.js performance optimization...",
    "Source": "facebook/react/.claude/skills/react-patterns",
    "Stars": 242700,
    "Owner": "facebook",
    "Repo": "react",
    "Path": ".claude/skills/react-patterns"
  }
]

Project Mode

skillshare search pdf -p           # Search and install to project
skillshare search react --project  # Same thing, long flag

Installed skills go to .skillshare/skills/ and the project config is updated automatically. If the project hasn't been initialized yet, skillshare will run init -p first.

Limit Results

skillshare search frontend -n 5   # Show only top 5 results

Authentication

GitHub Code Search API requires authentication. skillshare automatically detects your credentials:

  1. GitHub CLI (recommended) — If you're logged in with gh:

    gh auth login
    
  2. Environment variable — Set GITHUB_TOKEN or GH_TOKEN:

    export GITHUB_TOKEN=ghp_your_token_here
    

Creating a Token

If you don't use gh CLI:

  1. Go to GitHub Settings → Tokens
  2. Generate new token (classic)
  3. No scopes needed for public repos
  4. Set the token:
    export GITHUB_TOKEN=ghp_your_token_here
    

How Results are Ranked

  1. Search — GitHub Code Search finds SKILL.md files matching your query
  2. Filter — Removes forked repositories (duplicates)
  3. Fetch Stars — Gets star count for each unique repository
  4. Sort — Orders by stars (most popular first)
  5. Limit — Returns top N results

This ensures high-quality, popular skills appear first.

Community Hub

Browse and install community-curated skills from skillshare-hub:

skillshare search --hub                # Browse all skills in skillshare-hub
skillshare search react --hub          # Search "react" in skillshare-hub

When --hub is used without a URL, it defaults to the community skillshare-hub index.

Want to share your skill with the community? Open a PR to add your skill — CI runs skillshare audit on every submission.

Saved Hub Labels

Save hubs with hub add and search by label instead of typing full URLs:

# Save a hub once
skillshare hub add https://internal.corp/hub.json --label team

# Search by label
skillshare search react --hub team

# Set as default for bare --hub
skillshare hub default team
skillshare search --hub              # Uses "team" hub

Resolution order for --hub <value>:

  1. URL or path (starts with http, /, ., ~, file://, or an SSH URL such as git@…/ssh://…) → used directly
  2. Otherwise → label lookup from saved hubs
  3. Bare --hub (no value) → config default → community hub fallback

See hub for managing saved hubs.

Search from a private hub index instead of GitHub:

# Local file
skillshare search react --hub ./skillshare-hub.json

# HTTP URL
skillshare search react --hub https://internal.corp/skills/skillshare-hub.json

# SSH URL — clones the repo and reads the index (works with private/GHE hosts)
skillshare search react --hub git@github.com:org/skills.git
skillshare search react --hub git@ghe.corp.com:team/skills.git//hubs/team.json

# Browse all skills (empty query)
skillshare search --hub ./skillshare-hub.json --json

# Equals syntax also works
skillshare search react --hub=./skillshare-hub.json

:::note SSH hub sources An SSH --hub value is resolved by shallow-cloning the repo (using your SSH agent/keys) and reading the index file from it. The file path inside the repo comes from the //path suffix — git@host:org/repo.git//hubs/team.json — and defaults to skillshare-hub.json at the repo root when omitted. Both scp-style (git@host:org/repo.git) and scheme-style (ssh://git@host/org/repo.git) URLs are accepted.

In the web dashboard, SSH hub sources must be saved first; the server only clones saved hubs. :::

Build an index with hub index:

skillshare hub index                           # Generate skillshare-hub.json
skillshare search --hub ./skillshare-hub.json  # Search it

:::tip Default hub skillshare search --hub (without a URL) defaults to the community skillshare-hub index, so you don't need to type the full URL every time. Or set your own default with skillshare hub default <label>. :::

For more details, see the Hub Index Guide.

Tips

Find Official Skills

Search for well-known organizations:

skillshare search anthropic    # Anthropic's skills
skillshare search facebook     # Meta/Facebook skills
skillshare search vercel       # Vercel's skills

Find Specific Functionality

Search by what you want to do:

skillshare search "pull request"
skillshare search deployment
skillshare search testing
skillshare search database

In interactive mode, after installing a skill (or canceling), you can search again without restarting:

? Search again (or press Enter to quit): react

Troubleshooting

"GitHub Code Search API requires authentication"

Run gh auth login or set GITHUB_TOKEN. See Authentication.

"GitHub API rate limit exceeded"

  • Authenticated users: 30 requests/minute for Code Search
  • Wait a minute and try again
  • Use --limit to reduce API calls

New Repository Not Found

GitHub indexes new repositories with a delay (hours to days). If your repo isn't found:

  • Install directly: skillshare install owner/repo/path/to/skill
  • Wait for GitHub to index the repository

Results Don't Match Query

GitHub Code Search matches content inside SKILL.md files. A skill mentioning "vercel" in its description will appear in vercel searches, even if the skill isn't specifically about Vercel.

Use --list to review results before installing.