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)

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

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)

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

Run kb search "<query>" --top 10 --format json
Read the returned chunks
Synthesise a natural language answer from the top results
ALWAYS cite sources: "According to [title] (p.X)..." or "From [title], section [header]..."
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"
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)

3.5 KiB Raw Blame History