Reindex command, implicit note shorthand, add→addfile rename
- Add `kb reindex` command with confirmation prompt and --yes flag - Add implicit note shorthand: `kb "my note"` submits a note directly - Rename `add` to `addfile`, remove --note/--title/--type flags - Add client-side file extension validation before upload - Add `kb examples` command for common usage patterns - Update README, SKILL.md, and main specs - Archive completed changes and sync delta specs BREAKING: `kb add` renamed to `kb addfile`, `kb add --note` replaced by `kb "text"` Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# kb-search skill
|
||||
|
||||
Search the user's personal knowledge base containing PDFs, markdown documents, code snippets, and text notes.
|
||||
Search, manage, and add to the user's personal knowledge base containing PDFs, Word docs, HTML, markdown, code files, and text notes.
|
||||
|
||||
## When to use
|
||||
|
||||
@@ -8,10 +8,18 @@ Search the user's personal knowledge base containing PDFs, markdown documents, c
|
||||
- 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
|
||||
- User wants to save a note, add a file, or manage their knowledge base
|
||||
|
||||
## Available commands
|
||||
## Quick notes
|
||||
|
||||
### Search (primary)
|
||||
```bash
|
||||
kb "remember to update DNS records" # add a note
|
||||
kb "server room is building 3, floor 2" --tags ops # add a tagged note
|
||||
```
|
||||
|
||||
Bare text without a subcommand is treated as a note and submitted for ingestion.
|
||||
|
||||
## Search (primary use case)
|
||||
|
||||
```bash
|
||||
kb search "<query>" --top 10 --format json
|
||||
@@ -20,25 +28,72 @@ 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)
|
||||
- `-n, --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)
|
||||
- `--format json|human` — output format (always use json for parsing)
|
||||
- `--fts-only` — keyword search only (skip semantic)
|
||||
- `--vec-only` — semantic search only (skip keyword)
|
||||
- `--threshold FLOAT` — minimum score cutoff
|
||||
|
||||
### Other useful commands
|
||||
## Adding files
|
||||
|
||||
```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
|
||||
kb addfile report.pdf # single file
|
||||
kb addfile report.pdf --tags admin,reference # with tags
|
||||
kb addfile ~/docs/ --recursive # directory (recursive)
|
||||
kb addfile ~/docs/ --recursive --tags reference # directory with tags
|
||||
```
|
||||
|
||||
## Output format (search)
|
||||
Supported file types: `.pdf`, `.docx`, `.html`, `.md`, `.txt`, `.py`, `.sh`, `.go`. Unsupported extensions are rejected before upload.
|
||||
|
||||
**Flags:**
|
||||
- `--tags tag1,tag2` — tags (comma-separated)
|
||||
- `-r, --recursive` — recursively add directory contents
|
||||
|
||||
## Document management
|
||||
|
||||
```bash
|
||||
kb list --format json # list all documents
|
||||
kb list --type pdf --format json # filter by type
|
||||
kb list --tags admin --format json # filter by tags
|
||||
kb info <doc_id> --format json # document details with chunks
|
||||
kb export <doc_id> -o file.pdf # download original file
|
||||
kb remove <doc_id> # remove (prompts for confirmation)
|
||||
kb remove <doc_id> --yes # remove without confirmation
|
||||
```
|
||||
|
||||
## Tag management
|
||||
|
||||
```bash
|
||||
kb tags --format json # list all tags with counts
|
||||
kb tag <doc_id> --add important,ops # add tags to a document
|
||||
kb tag <doc_id> --remove draft # remove tags from a document
|
||||
```
|
||||
|
||||
## Jobs (ingestion queue)
|
||||
|
||||
```bash
|
||||
kb jobs --format json # list recent jobs
|
||||
kb jobs --status failed --format json # filter by status
|
||||
kb jobs <job_id> --format json # job details
|
||||
```
|
||||
|
||||
## Engine status and maintenance
|
||||
|
||||
```bash
|
||||
kb status --format json # engine status, GPU info, DB stats
|
||||
kb reindex --yes # re-embed all chunks (skip confirmation)
|
||||
```
|
||||
|
||||
## Global flags
|
||||
|
||||
All commands support:
|
||||
- `--format json|human` — output format (always use `json` for machine parsing)
|
||||
- `--engine <url>` — engine API URL (default: http://localhost:8000)
|
||||
- `--api-key <key>` — API key for authentication
|
||||
|
||||
## Search output format
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -66,7 +121,7 @@ kb status --format json # DB stats
|
||||
}
|
||||
```
|
||||
|
||||
## How to answer
|
||||
## How to answer search queries
|
||||
|
||||
1. Run `kb search "<query>" --top 10 --format json`
|
||||
2. Read the returned chunks
|
||||
@@ -93,7 +148,7 @@ Query 2: kb search "git merge explanation" --top 5 --format json
|
||||
Query 3: kb search "git rebase vs merge" --top 5 --format json
|
||||
```
|
||||
|
||||
## Filtering
|
||||
## Filtering tips
|
||||
|
||||
Use filters when the question implies a specific domain:
|
||||
|
||||
@@ -108,3 +163,4 @@ Use filters when the question implies a specific domain:
|
||||
- `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)
|
||||
- Duplicate files are detected at upload time (HTTP 409) — the client handles this gracefully
|
||||
|
||||
Reference in New Issue
Block a user