Claude Skill Definition

Claude Skill Definition

---

name: doc-serve description: | Semantic search over indexed documentation with BM25 keyword search and hybrid retrieval. This skill enriches the conversation context with relevant information from specific knowledge domains. Supports vector search, BM25 keyword matching, and intelligent hybrid fusion for optimal retrieval. version: 1.2.0 category: ai-tools triggers:

• doc-serve
• search the domain
• search domain
• query domain
• look up in domain
• find in docs
• search documentation
• bm25 search
• hybrid search author: Spillwave license: MIT

---

Doc-Serve Claude Skill

Overview

doc-serve enables advanced semantic search over indexed documentation with multiple retrieval modes. It provides context from local knowledge bases (Markdown, PDF, TXT) using state-of-the-art retrieval techniques including vector similarity, BM25 keyword matching, and hybrid fusion.

Capabilities

1. Automatic Setup: Can clone the repository and install the global CLI tools if missing.
2. Server Management: Can start and stop the doc-serve API server.
3. Smart Indexing: Can index local directories into the semantic + keyword database.
4. Multi-Mode Retrieval:
   • Vector Search: Semantic similarity using OpenAI embeddings
   • BM25 Search: Exact keyword matching for technical terms
   • Hybrid Search: Intelligent combination of both approaches
5. Context Retrieval: Performs high-accuracy similarity search with scoring transparency.

When to Use

• When asked to "search the domain X" or "look up X in the docs".
• When you need accurate information from local technical documentation.
• When working on a project with its own internal knowledge base.
• When searching for specific function names, error codes, or technical terms (use BM25 mode).
• When needing comprehensive search results (use hybrid mode - default).

Workflow

1. Verification

Before querying, ensure the CLI tools are available.

doc-svr-ctl --version

If missing, clone the repository and run task install:global.

2. Server & Indexing

Check if the server is running and has data:

doc-svr-ctl status

If the server is down, start it: doc-serve &. If the directory needs indexing: doc-svr-ctl index /path/to/docs.

3. Querying

Execute searches using different modes:

# Hybrid search (recommended default)
doc-svr-ctl query "authentication flow" --threshold 0.4 --json

# Pure keyword search (for technical terms)
doc-svr-ctl query "AuthenticationError" --mode bm25 --threshold 0.2

# Weighted hybrid search
doc-svr-ctl query "api documentation" --mode hybrid --alpha 0.7

# Show individual scores
doc-svr-ctl query "search query" --scores

Search Modes

Mode	Description	Best For	Example
hybrid (default)	Combines vector + BM25	General queries, comprehensive results	doc-svr-ctl query "api authentication"
vector	Pure semantic similarity	Conceptual understanding	doc-svr-ctl query "how authentication works"
bm25	Pure keyword matching	Technical terms, error codes	doc-svr-ctl query "ERROR_CODE_404"

Alpha Weighting (Hybrid Mode)

Control the balance between semantic and keyword search:

• alpha = 1.0: 100% vector search (pure semantic)
• alpha = 0.5: 50% vector + 50% BM25 (balanced) - recommended
• alpha = 0.0: 100% BM25 search (pure keyword)

Best Practices

• Mode Selection:

  • Use hybrid for most queries (best balance)
  • Use bm25 for function names, error codes, specific technical terms
  • Use vector for conceptual questions or when exact wording doesn't matter

• Threshold Adjustment: If no results are found, retry with a lower --threshold (e.g., 0.2 for BM25, 0.3 for hybrid).

• Alpha Tuning:

  • Technical documentation: Try alpha = 0.3 (more keyword focus)
  • Conceptual docs: Try alpha = 0.8 (more semantic focus)
  • General content: Keep alpha = 0.5 (balanced)

• Source Citation: Always mention the source file name in the final answer.

• Background Processes: Run the server in the background to keep the terminal interactive.

• Port Conflicts: If the server fails to start, check for existing processes on port 8000 using lsof -i :8000.

Example Usage

Technical Query (BM25 Mode)

User: "What does the documentation say about AuthenticationError?"

Skill Execution:

1. Run doc-svr-ctl status to verify indexing.
2. Run doc-svr-ctl query "AuthenticationError" --mode bm25 --threshold 0.2 --json.
3. Parse JSON results and synthesize response.

Claude Response: "According to auth_module.md, AuthenticationError is raised when login credentials are invalid. The error code is AUTH_001 and includes fields for username, attempt_time, and failure_reason."

Conceptual Query (Hybrid Mode)

User: "How does the authentication system work?"

Skill Execution:

1. Run doc-svr-ctl query "authentication system flow" --mode hybrid --alpha 0.6 --threshold 0.3 --json.
2. Combine results from semantic similarity and keyword matching.

Claude Response: "The authentication system uses a multi-step flow: 1) Credential validation via validate_credentials(), 2) Token generation using JWT, 3) Session management with Redis caching, 4) Automatic logout after 30 minutes of inactivity (from session_config.md)."

Balanced Search (Default Hybrid)

User: "Tell me about espresso brewing parameters"

Skill Execution:

1. Run doc-svr-ctl query "espresso brewing parameters" --json (uses hybrid mode by default).
2. Return top results combining semantic meaning with keyword matches.

Claude Response: "For optimal espresso extraction: use 18-20g finely ground coffee (like table salt texture), 195-205°F water temperature, 9 bars pressure, and extract for 25-30 seconds yielding 1-2oz of espresso. Grind size is critical - too fine causes bitter shots, too coarse causes weak extraction (from espresso_basics.md)."

Advanced Features

Scoring Transparency

Use --scores flag to see individual component scores:

doc-svr-ctl query "search term" --mode hybrid --scores

Returns results with vector_score, bm25_score, and combined score for debugging.

Programmatic Access

For automation or custom processing:

# Get raw JSON for scripting
doc-svr-ctl query "api endpoints" --json | jq '.results[0].text'

# Count total indexed content
curl http://localhost:8000/query/count

Performance Tuning

• BM25 Mode: Fastest (< 1ms), best for exact matches
• Vector Mode: Balanced performance, best for semantic understanding
• Hybrid Mode: Highest quality but slightly slower (~2-3ms overhead)

Error Handling

• No Results: Lower threshold or try different search mode
• Connection Error: Start server with doc-serve &
• Index Empty: Run doc-svr-ctl index /path/to/docs
• Invalid Mode: Use vector, bm25, or hybrid
• Alpha Out of Range: Must be between 0.0 and 1.0

Integration Notes

This skill integrates with Claude's conversation context to provide domain-specific knowledge. It automatically manages the underlying doc-serve infrastructure while exposing simple query interfaces to the AI assistant.