111 lines
3.5 KiB
Markdown
111 lines
3.5 KiB
Markdown
# kb-search skill
|
|
|
|
Search the user's personal knowledge base containing PDFs, markdown documents, code snippets, and text notes.
|
|
|
|
## When to use
|
|
|
|
- User asks a question that might be answered by their stored documents, notes, or code
|
|
- User explicitly says "check my notes", "search kb", "look in my knowledge base", "what do my docs say about..."
|
|
- User references documents or notes they've previously stored
|
|
- User asks "how do I..." style questions that their knowledge base likely covers
|
|
|
|
## Available commands
|
|
|
|
### Search (primary)
|
|
|
|
```bash
|
|
kb search "<query>" --top 10 --format json
|
|
```
|
|
|
|
Returns JSON with ranked results combining full-text and semantic search.
|
|
|
|
**Flags:**
|
|
- `--top N` — number of results (default: 10)
|
|
- `--tags tag1,tag2` — filter by tags (AND logic)
|
|
- `--type pdf|markdown|code|note` — filter by document type
|
|
- `--format json|human` — output format (always use json)
|
|
- `--fts-only` — keyword search only (skip semantic)
|
|
- `--vec-only` — semantic search only (skip keyword)
|
|
- `--threshold FLOAT` — minimum score cutoff
|
|
|
|
### Other useful commands
|
|
|
|
```bash
|
|
kb list --format json # List all documents
|
|
kb list --type pdf --format json # List only PDFs
|
|
kb tags --format json # List tags with counts
|
|
kb info <doc_id> --format json # Document details
|
|
kb status --format json # DB stats
|
|
```
|
|
|
|
## Output format (search)
|
|
|
|
```json
|
|
{
|
|
"query": "how to install git",
|
|
"results": [
|
|
{
|
|
"chunk_id": 1423,
|
|
"score": 0.031,
|
|
"score_breakdown": {"fts": 0.016, "vector": 0.015},
|
|
"text": "To install the latest version of git from source...",
|
|
"source": {
|
|
"document_id": 42,
|
|
"title": "Git Admin Guide",
|
|
"path": "/home/user/docs/git-admin.pdf",
|
|
"type": "pdf",
|
|
"page": 12,
|
|
"chunk_index": 3,
|
|
"total_chunks": 28,
|
|
"tags": ["git", "admin"]
|
|
}
|
|
}
|
|
],
|
|
"total_matches": 47,
|
|
"returned": 10
|
|
}
|
|
```
|
|
|
|
## How to answer
|
|
|
|
1. Run `kb search "<query>" --top 10 --format json`
|
|
2. Read the returned chunks
|
|
3. Synthesise a natural language answer from the top results
|
|
4. **ALWAYS cite sources**: "According to [title] (p.X)..." or "From [title], section [header]..."
|
|
5. If results have low scores (all below 0.01) or `returned: 0`, tell the user: "I couldn't find anything in your knowledge base about this"
|
|
6. If initial results seem off-target, try refining the query and searching again
|
|
|
|
## Multi-query strategy
|
|
|
|
For complex questions, search multiple times with different queries:
|
|
|
|
- Decompose the question into sub-queries
|
|
- Run each query separately
|
|
- Combine and deduplicate results across queries
|
|
- Synthesise a unified answer citing all relevant sources
|
|
|
|
Example:
|
|
```
|
|
User: "What's the difference between git rebase and merge?"
|
|
|
|
Query 1: kb search "git rebase explanation" --top 5 --format json
|
|
Query 2: kb search "git merge explanation" --top 5 --format json
|
|
Query 3: kb search "git rebase vs merge" --top 5 --format json
|
|
```
|
|
|
|
## Filtering
|
|
|
|
Use filters when the question implies a specific domain:
|
|
|
|
- Code question → `--type code`
|
|
- From a specific topic → `--tags <topic>`
|
|
- Check available tags first: `kb tags --format json`
|
|
|
|
## Important notes
|
|
|
|
- Always use `--format json` for machine parsing
|
|
- The `score` field is relative, not absolute — compare scores within a result set
|
|
- `source.page` is only present for PDF documents
|
|
- `source.section_header` is only present for markdown documents with headers
|
|
- Results are already ranked by relevance (hybrid FTS + vector search)
|