Skip to main content

​
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.
For detailed documentation on specific commands, see the dedicated command pages linked below.

​
Command Reference

Search for installed skills using semantic similarity with OpenAI embeddings. Returns ranked results based on semantic relevance.
See search Command for complete documentation with output formats.
# Search for skills
fastskill search "text processing"

# Search with XML format output
fastskill search "analyze data" --format xml

# Search with JSON format
fastskill search "convert files" --format json

# Search with limit
fastskill search "process text" --limit 5
What it does:
  • Embeds query text using OpenAI’s text-embedding-3-small model
  • Searches vector index (SQLite database at .claude/.fastskill/index.db)
  • Returns ranked results using cosine similarity
  • File content is hashed (SHA256) to detect changes
Options:
  • <QUERY>: Search query (natural language)
  • --format <FORMAT>: Output format: json, xml, or text (default: text)
  • --limit <N>: Maximum number of results to return (default: 10)
  • --min-score <SCORE>: Minimum relevance threshold (0.0-1.0)
Output:
  • text: Human-readable table with skill details
  • json: Machine-readable array with relevance scores
  • xml: Structured XML for API integration

​
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
fastskill reindex

# Reindex specific skill
fastskill reindex web-scraper

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

# Control concurrent embedding requests
fastskill reindex --max-concurrent 5
What it does:
  • Scans .claude/skills/ for all installed skills
  • Generates embeddings for SKILL.md content using OpenAI API
  • Stores embeddings in SQLite database at .claude/.fastskill/index.db
  • Tracks file hashes (SHA256) for change detection
  • Skips unchanged files based on hash comparison
Options:
  • <SKILL_ID>: Reindex specific skill only (optional)
  • --force: Force reindex all files (ignore hash cache)
  • --max-concurrent <N>: Maximum concurrent embedding API requests (default: 10)
When to use:
  • After installing new skills
  • After updating existing skills
  • When search results are stale or incomplete
  • When skill content has changed

​
fastskill sources

Manage skill sources (repositories) for discovering and installing skills. Supports multiple repository types with authentication and priority-based resolution.
See sources Command for complete documentation with subcommands and authentication.
# List all configured sources
fastskill sources list

# Add new source
fastskill sources add team-tools --type git-marketplace --url https://github.com/team/skills.git

# Remove source
fastskill sources remove team-tools

# Show source details
fastskill sources show team-tools

# Update source configuration
fastskill sources update team-tools --priority 1

# Test source connectivity
fastskill sources test team-tools

# Refresh source cache
fastskill sources refresh

# Create marketplace.json from directory
fastskill sources create ./skills --output marketplace.json
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)
  • Creates marketplace.json for git-marketplace repositories
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

​
fastskill registry

Legacy alias for sources command. Provides same functionality with different subcommand names.
The registry command is a legacy alias. Use fastskill sources for new code. Both commands have identical functionality.
# Legacy: Add repository
fastskill registry add team-tools --repo-type git-marketplace https://github.com/team/skills.git

# Preferred: Add repository
fastskill sources add team-tools --type git-marketplace --url https://github.com/team/skills.git

​
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

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.
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.
Invalid repository name: Check repository name with fastskill sources list.
Repository URL incorrect: Verify URL is accessible with fastskill sources test <name>.
Authentication failed: Verify authentication type and credentials with fastskill sources show <name>.

​
Best Practices

1

Reindex after changes

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

Use natural language queries

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

Organize repositories by priority

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

Test repositories after configuration

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

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.

​
See Also