Skip to main content

​
Overview

FastSkill’s embedding-based search uses OpenAI’s embedding models to understand the semantic meaning of queries, enabling intelligent skill discovery beyond simple keyword matching.
Embedding search requires configuration and an OpenAI API key. It provides superior relevance for natural language queries.

​
How It Works

​
1. Text Vectorization

Both your search query and all indexed skills are converted into mathematical vectors using OpenAI’s embedding models. These vectors capture semantic meaning, not just keywords.

​
2. Similarity Calculation

The system calculates cosine similarity between your query vector and all skill vectors to find the most semantically relevant matches.

​
3. Relevance Ranking

Skills are ranked by their semantic similarity to your query, often finding skills that don’t contain exact keywords but are conceptually related.

​
Configuration

​
1. Create Configuration File

Create .fastskill.yaml in your project root: 
embedding:
  openai_base_url: "https://api.openai.com/v1"
  embedding_model: "text-embedding-3-small"

​
2. Set API Key

export OPENAI_API_KEY="your-openai-api-key"

​
3. Index Skills

fastskill --skills-dir /path/to/skills/ refresh
This command:
  • Scans all SKILL.md files in the specified directory
  • Extracts frontmatter and content
  • Generates embeddings for each skill
  • Stores them in a local SQLite database

​
Usage

# Find skills related to document processing
fastskill --skills-dir .claude/skills/ "process documents and extract information"

# Search for visualization tools
fastskill --skills-dir .claude/skills/ "create charts and graphs"

​
Output Formats

​
Table Format (Default)

fastskill search "powerpoint" --format table

​
JSON Format

fastskill search "powerpoint" --format json

​
XML Format

fastskill search "powerpoint" --format xml

​
Controlling Search Behavior

# Limit results
fastskill search "query" --limit 5

# Output formats
fastskill search "query" --format json
fastskill search "query" --format xml

​
Example Results

​
Semantic Search Results

For query: “I need to run a meeting and need to summarize the main points visually” Embedding Search Finds:
  • PowerPoint presentation skills
  • Meeting summarization tools
  • Chart and graph creation utilities
  • Visual data representation tools
Keyword Search Might Miss:
  • Skills that use synonyms or related terms
  • Tools that focus on the outcome rather than the exact process

​
Performance Considerations

​
Indexing

  • First Time: May take several minutes for large skill sets
  • Updates: Only changed skills are re-indexed
  • Storage: Embeddings are stored locally in SQLite database

​
Search Speed

  • Very Fast: Vector similarity search is optimized
  • Local: No external API calls during search
  • Scalable: Handles thousands of skills efficiently

​
Troubleshooting

​
Common Issues

​
”Embedding not configured”

Solution: Create .fastskill.yaml with embedding configuration.

​
”OPENAI_API_KEY environment variable not set”

Solution: Set your OpenAI API key as an environment variable.

​
”Vector index service not available”

Solution: Run fastskill reindex first to build the index.

​
API Rate Limits

Solution: The system handles rate limits gracefully. Consider using a paid OpenAI plan for large indexing operations.

​
Debugging

Enable verbose logging to troubleshoot issues: 
RUST_LOG=fastskill=debug fastskill reindex --skills-dir /path/to/skills/

​
Integration with AI Agents

​
Cursor Integration

FastSkill automatically generates markdown files for Cursor integration: 
fastskill reindex --skills-dir .claude/skills/
# Creates .claude/skills/.fastskill/skills.md
This file contains all indexed skills in a format Cursor can use for tool discovery.

​
Custom Agent Integration

import asyncio
from fastskill import FastSkillService, ServiceConfig

async def semantic_search():
    config = ServiceConfig()
    service = FastSkillService(config)
    await service.initialize()

    # Semantic search
    results = await service.search_similar(
        "process images and extract text",
        limit=5
    )

    for skill in results:
        print(f"Found: {skill.name} - Relevance: {skill.similarity}")

asyncio.run(semantic_search())

​
Best Practices

​
Query Formulation

  • Use natural language queries
  • Describe the desired outcome, not specific tools
  • Include context about your use case

​
Index Maintenance

  • Run fastskill reindex after adding new skills
  • Re-index periodically to catch updates
  • Use --force flag to rebuild entire index if needed

​
Configuration

  • Use text-embedding-3-small for most use cases (cost-effective)
  • Upgrade to text-embedding-3-large for higher accuracy if needed
  • Keep API keys secure and rotate regularly

​
Cost Considerations

​
OpenAI API Costs

  • text-embedding-3-small: ~$0.02 per 1M tokens
  • Indexing: Costs scale with total content size
  • Search: Free after indexing (local vector search)

​
Optimization Tips

  • Index only relevant skills
  • Use smaller embedding models for cost savings
  • Cache embeddings to avoid re-indexing

​
Advanced Features

​
Custom Embedding Models

FastSkill can be extended to use custom embedding models: 
// Implement custom embedding service
struct CustomEmbeddingService {
    // Your embedding logic here
}

#[async_trait]
impl EmbeddingService for CustomEmbeddingService {
    async fn embed_text(&self, text: &str) -> Result<Vec<f32>, ServiceError> {
        // Your embedding implementation
    }
}
Embedding-based search provides intelligent skill discovery through semantic understanding, finding relevant skills based on meaning rather than exact keyword matches.