index
starsforks
How to install index?
softspark/ai-toolkit/index
$npx -y skills add softspark/ai-toolkit --skill indexReindexes KB for semantic search via vector store (Qdrant). Triggers: reindex KB, rebuild index, vector reindex, refresh embeddings.
SKILL.md
| 1 | # Knowledge Base Indexing |
| 2 | |
| 3 | $ARGUMENTS |
| 4 | |
| 5 | Reindex the knowledge base for semantic search. |
| 6 | |
| 7 | > **Prerequisite**: This command requires a vector store (e.g., Qdrant) and an indexing pipeline configured for your project. If not configured, this command provides guidance on setup. |
| 8 | |
| 9 | ## Usage |
| 10 | |
| 11 | ``` |
| 12 | /index # Incremental index (detect changes) |
| 13 | /index --full # Full rebuild |
| 14 | ``` |
| 15 | |
| 16 | ## Execution |
| 17 | |
| 18 | ### Direct Execution |
| 19 | ```bash |
| 20 | # Incremental index (auto-detects changes) |
| 21 | make index |
| 22 | |
| 23 | # Full rebuild |
| 24 | make index-full |
| 25 | ``` |
| 26 | |
| 27 | ### Docker Execution |
| 28 | ```bash |
| 29 | docker exec {app-container} make index |
| 30 | docker exec {app-container} make index-full |
| 31 | ``` |
| 32 | |
| 33 | ## Change Detection |
| 34 | |
| 35 | The indexer uses content hashing to detect changes: |
| 36 | |
| 37 | | Scenario | Action | |
| 38 | |----------|--------| |
| 39 | | New document | Index | |
| 40 | | Changed content | Reindex | |
| 41 | | No changes | Skip | |
| 42 | | Deleted document | Remove from index | |
| 43 | |
| 44 | ## Frontmatter Validation |
| 45 | |
| 46 | Before indexing, ensure all KB documents have valid frontmatter: |
| 47 | |
| 48 | ```yaml |
| 49 | --- |
| 50 | title: "Document Title" |
| 51 | service: {service-name} |
| 52 | category: reference|howto|procedures|troubleshooting|decisions|best-practices |
| 53 | tags: [tag1, tag2] |
| 54 | last_updated: "YYYY-MM-DD" |
| 55 | --- |
| 56 | ``` |
| 57 | |
| 58 | ## Troubleshooting |
| 59 | |
| 60 | | Problem | Solution | |
| 61 | |---------|----------| |
| 62 | | Index not updating | Check file timestamps, run full rebuild | |
| 63 | | Missing documents | Verify frontmatter is valid | |
| 64 | | Slow indexing | Check embedding service performance | |
| 65 | | No vector store | Set up Qdrant or compatible vector DB | |
| 66 | |
| 67 | ## Rules |
| 68 | |
| 69 | - **MUST** require explicit user permission before running `make index` or `make index-full` — never self-trigger |
| 70 | - **NEVER** trigger a full rebuild to "clean up" unless the user asked for it |
| 71 | - **CRITICAL**: validate KB frontmatter before indexing — abort on invalid documents rather than indexing a broken state |
| 72 | - **MANDATORY**: respect change-detection hashes; do not force reindexing of unchanged documents |
| 73 | |
| 74 | ## Gotchas |
| 75 | |
| 76 | - Content-hash change detection keys on the file's content AND path. A **moved** document (same content, new path) looks new to the indexer — both the old path vector and the new one will exist until a full rebuild. Plan a full rebuild after mass reorganizations. |
| 77 | - Deleting a document on disk does not automatically remove its vectors from Qdrant; the indexer emits tombstones only if run with a directory scan. Without `--delete-missing`, orphan vectors stay for weeks. |
| 78 | - Embedding providers rate-limit by requests-per-minute AND by tokens-per-minute. A reindex of 1000+ docs hits the token cap first and stalls silently — watch for 429s in the indexer log before concluding "slow indexing". |
| 79 | - `make index-full` truncates the collection before re-embedding; if the embedding job crashes mid-way, the collection is left partially populated with no query-time indicator of the gap. |
| 80 | |
| 81 | ## When NOT to Use |
| 82 | |
| 83 | - For searching the KB — use `/research-mastery` or call `smart_query()` via the rag-mcp tool |
| 84 | - For fixing indexing bugs — use `/debug` on the indexer pipeline |
| 85 | - To evaluate RAG quality after reindexing — use `/evaluate` |
| 86 | - When no vector store is configured — document the gap, do not invent one |
People who liked this also viewed
6 picksType
- find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 2026
- grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026
- vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026
- improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026
- setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026
- triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026
