Initial MVP

2026-03-23 20:38:42 +00:00
commit f245c24928
57 changed files with 6812 additions and 0 deletions
@@ -0,0 +1,110 @@
+# 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)