Discovery Commands

Overview

Discovery commands help you find, index, and manage skills in your FastSkill ecosystem. These commands provide semantic search, vector indexing, and repository management capabilities.

Command Architecture:

Repository Management: Use fastskill repos for all repository operations (add, remove, list, test, refresh) and catalog browsing (skills, show, versions)
Skill Discovery: Use fastskill search (remote catalogs by default; add --local for installed skills and embeddings)

For detailed documentation on specific commands, see the dedicated command pages linked below.

Command Reference

fastskill search

Query skills. Default scope is remote (catalog APIs). Use --local to search installed skills; local embedding search uses OpenAI when configured and respects --embedding.

See search Command for complete documentation with output formats.

# Remote catalog search (default)
fastskill search "text processing"

# Installed skills + embeddings / keyword (see --embedding)
fastskill search "analyze data" --local

# Remote, limit and JSON
fastskill search "convert files" --limit 5 --json

# Remote, single repository
fastskill search "process text" --repository my-repo

What it does (local scope):

Optionally embeds the query and searches the local vector index when --embedding is not false
Uses the skills directory from skill-project.toml / discovery unless --skills-dir is set

Options:

<QUERY>: Search string
--local: Search installed skills only
--remote: Explicit remote search (same as default when --repository is not used alone)
--repository <NAME>: Limit remote search to one configured repository
-l, --limit <N>: Max results (default: 10)
-f, --format <FORMAT>: table, json, grid, or xml (default: table)
--json: Shorthand for --format json
--embedding <true|false|auto>: Local only; ignored for remote search
--skills-dir <PATH>: Override skills directory (local search / service bootstrap)

Output:

table (default): Human-readable rows
json / xml / grid: Structured or machine-readable layouts

fastskill reindex

Rebuild the vector search index by scanning all installed skills. Updates embeddings and similarity database.

See reindex Command for complete documentation with concurrency options.

# Reindex all skills (uses configured skills directory)
fastskill reindex

# Force reindex (ignore file hash cache)
fastskill reindex --force

# Control concurrent embedding requests (default 5)
fastskill reindex --max-concurrent 5

# Optional explicit skills directory
fastskill reindex --skills-dir ./.claude/skills

What it does:

Scans the configured skills directory for installed skills
Generates embeddings for SKILL.md content when embedding search is enabled
Stores vectors in the local index database used by fastskill search --local
Tracks file hashes (SHA256) for change detection
Skips unchanged files unless --force is set

Options:

--skills-dir <PATH>: Override skills directory for this run
--force: Rebuild all embeddings (ignore hash cache)
--max-concurrent <N>: Concurrent embedding requests (default: 5)
--progress / --no-progress: Control progress UI

When to use:

After installing new skills
After updating existing skills
When search results are stale or incomplete
When skill content has changed

fastskill repos

Manage skill repositories for discovering and installing skills. Supports multiple repository types with authentication and priority-based resolution. This is the primary command for repository management and catalog browsing.

See repos Command for complete documentation with subcommands and authentication.

# List all configured repositories
fastskill repos list

# Add new repository
fastskill repos add team-tools --repo-type git-marketplace https://github.com/team/skills.git

# Remove repository
fastskill repos remove team-tools

# Show repository details
fastskill repos info team-tools

# Update repository configuration
fastskill repos update team-tools --priority 1

# Test repository connectivity
fastskill repos test team-tools

# Refresh repository cache
fastskill repos refresh

What it does:

Manages repository configuration in skill-project.toml [tool.fastskill.repositories]
Supports multiple repository types: git-marketplace, http-registry, zip-url, local
Handles authentication: PAT, SSH key, SSH, Basic Auth, API Key
Implements priority-based conflict resolution (lower priority = higher precedence)

Repository Types: Git Marketplace:

[[tool.fastskill.repositories]]
name = "team-skills"
type = "git-marketplace"
url = "https://github.com/team/skills.git"
priority = 0
branch = "main"
# Optional authentication
auth_type = "pat"
auth_value = "token-value"

HTTP Registry:

[[tool.fastskill.repositories]]
name = "public-registry"
type = "http-registry"
index_url = "https://registry.fastskill.dev/index"
priority = 0
# Optional authentication
auth_type = "api-key"
auth_value = "key-value"

ZIP URL:

[[tool.fastskill.repositories]]
name = "skill-archive"
type = "zip-url"
base_url = "https://example.com/skills"
priority = 0

Local:

[[tool.fastskill.repositories]]
name = "local-skills"
type = "local"
path = "./local-skills"
priority = 0

Authentication Types:

pat: Personal Access Token (for git repositories)
ssh-key: SSH key path
ssh: SSH connection
basic: Basic authentication (username/password)
api-key: API key (for HTTP registries)

Priority Resolution: When skills are available in multiple repositories, priority determines the order:

Lower priority numbers are checked first
Default priority: 0
Higher priority values are checked later

Legacy commands: sources (alias source) and registry are hidden from fastskill --help but still exist for compatibility. Prefer fastskill repos for repository and catalog operations.

Search and Reindex Workflow

Initial Setup

# 1. Install skills
fastskill install

# 2. Reindex for search
fastskill reindex

# 3. Test search
fastskill search "text processing"

After Updates

# 1. Update skills
fastskill update

# 2. Reindex to refresh embeddings
fastskill reindex --force

# 3. Verify search results
fastskill search "new feature"

Adding New Skills

# 1. Add skill
fastskill add https://github.com/user/new-skill.git

# 2. Reindex to include in search
fastskill reindex

# 3. Test discovery
fastskill search "skill name or description"

Performance Considerations

Reindexing

File Hash Detection:

Files are hashed with SHA256 to detect changes
Unchanged files are skipped during reindex
Use --force to bypass hash cache

Concurrency:

Embedding API requests are concurrent (default: 10)
Use --max-concurrent to control API rate limiting
Lower values reduce API rate limit errors
Higher values speed up reindexing

Searching

Semantic Search:

Uses cosine similarity for ranking
Embeddings are cached in SQLite database
Search is O(log n) with vector index

Query Tips:

Use natural language queries (similar to SKILL.md descriptions)
Include relevant domain terms
Try different query phrasings for better results

Troubleshooting

Search returns no results

Index not built: Make sure you’ve run fastskill reindex after installing skills.

Query too specific: Try broader terms or different phrasing.

Skills not installed: Verify skills are in .claude/skills/ with fastskill list.

Reindex fails

OpenAI API key not set: Set OPENAI_API_KEY environment variable.

export OPENAI_API_KEY="your-key-here"
fastskill reindex

API rate limit errors: Reduce concurrent requests with --max-concurrent 3.

Network errors: Check internet connectivity and OpenAI API status.

Repository not found

Invalid repository name: Check repository name with fastskill repos list.

Repository URL incorrect: Verify URL is accessible with fastskill repos test <name>.

Authentication failed: Verify authentication type and credentials with fastskill repos info <name>.

Best Practices

Reindex after changes

Always run fastskill reindex after installing, updating, or modifying skills to keep search index current.

Use natural language queries

Search queries work best with natural language that matches skill descriptions in SKILL.md files.

Organize repositories by priority

Set lower priority numbers for primary repositories to ensure preferred skills are discovered first.

Test repositories after configuration

Use fastskill repos test <name> to verify repositories are accessible before using them.

Control API concurrency for reindexing

Use --max-concurrent to balance speed and API rate limits. Start with default and adjust based on rate limit errors.

Getting Started

Configuration

Skill Management

Evals & Quality

Skill Optimization

CLI Reference

Registry

Advanced Topics

Integration

Discovery Commands

Overview

Command Reference

fastskill search

fastskill reindex

fastskill repos

Search and Reindex Workflow

Initial Setup

After Updates

Adding New Skills

Performance Considerations

Reindexing

Searching

Troubleshooting

Best Practices

See Also

​Overview

​Command Reference

​fastskill search

​fastskill reindex

​fastskill repos

​Search and Reindex Workflow

​Initial Setup

​After Updates

​Adding New Skills

​Performance Considerations

​Reindexing

​Searching

​Troubleshooting

​Best Practices

​See Also

Overview

Command Reference

fastskill search

fastskill reindex

fastskill repos

Search and Reindex Workflow

Initial Setup

After Updates

Adding New Skills

Performance Considerations

Reindexing

Searching

Troubleshooting

Best Practices

See Also