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

# Discovery Commands

> FastSkill CLI commands for skill search, vector indexing, and repository management.

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

<Info>
  **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)
</Info>

<Note>
  For detailed documentation on specific commands, see the dedicated command pages linked below.
</Note>

## 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`.

<Info>
  See [search Command](/cli-reference/search-command) for complete documentation with output formats.
</Info>

```bash theme={null}
# 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.

<Info>
  See [reindex Command](/cli-reference/reindex-command) for complete documentation with concurrency options.
</Info>

```bash theme={null}
# 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.

<Info>
  See [repos Command](/cli-reference/repository-command) for complete documentation with subcommands and authentication.
</Info>

```bash theme={null}
# 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**:

```toml theme={null}
[[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**:

```toml theme={null}
[[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**:

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

**Local**:

```toml theme={null}
[[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

<Warning>
  **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.
</Warning>

## Search and Reindex Workflow

### Initial Setup

```bash theme={null}
# 1. Install skills
fastskill install

# 2. Reindex for search
fastskill reindex

# 3. Test search
fastskill search "text processing"
```

### After Updates

```bash theme={null}
# 1. Update skills
fastskill update

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

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

### Adding New Skills

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Search returns no results">
    <Warning>
      **Index not built**: Make sure you've run `fastskill reindex` after installing skills.
    </Warning>

    <Warning>
      **Query too specific**: Try broader terms or different phrasing.
    </Warning>

    <Warning>
      **Skills not installed**: Verify skills are in `.claude/skills/` with `fastskill list`.
    </Warning>
  </Accordion>

  <Accordion title="Reindex fails">
    <Info>
      **OpenAI API key not set**: Set `OPENAI_API_KEY` environment variable.

      ```bash theme={null}
      export OPENAI_API_KEY="your-key-here"
      fastskill reindex
      ```
    </Info>

    <Info>
      **API rate limit errors**: Reduce concurrent requests with `--max-concurrent 3`.
    </Info>

    <Info>
      **Network errors**: Check internet connectivity and OpenAI API status.
    </Info>
  </Accordion>

  <Accordion title="Repository not found">
    <Tip>
      **Invalid repository name**: Check repository name with `fastskill repos list`.
    </Tip>

    <Tip>
      **Repository URL incorrect**: Verify URL is accessible with `fastskill repos test <name>`.
    </Tip>

    <Tip>
      **Authentication failed**: Verify authentication type and credentials with `fastskill repos info <name>`.
    </Tip>
  </Accordion>
</AccordionGroup>

## Best Practices

<Steps>
  <Step title="Reindex after changes">
    Always run `fastskill reindex` after installing, updating, or modifying skills to keep search index current.
  </Step>

  <Step title="Use natural language queries">
    Search queries work best with natural language that matches skill descriptions in SKILL.md files.
  </Step>

  <Step title="Organize repositories by priority">
    Set lower priority numbers for primary repositories to ensure preferred skills are discovered first.
  </Step>

  <Step title="Test repositories after configuration">
    Use `fastskill repos test <name>` to verify repositories are accessible before using them.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## See Also

* [Install Command](/cli-reference/install-command) - Install skills from repositories
* [repos Command](/cli-reference/repository-command) - Primary repository management and catalog browsing documentation
* [Search Command](/cli-reference/search-command) - Detailed search command documentation
* [Repository System](/registry/repository-architecture) - Repository types and configuration