Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gofastskill.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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

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

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 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

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 repos 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