--- name: kb-update description: Knowledge base sync and health check for the knowledge-base skill. Scans all topic folders for unindexed documents, removes index entries for missing files, refreshes topic descriptions, cleans up stale split directories, and reports health issues (missing summaries, naming inconsistencies, orphaned files, duplicate content). triggers: kb update, kb up, update kb, kb sync allowed-tools: Bash(python*), Bash(pip*), Bash(ls*), Bash(mv*), Bash(cp*), Bash(mkdir*), Bash(find*), Bash(wc*), Bash(file*), Read, Write, Edit, Glob, Grep, Agent model: sonnet effort: medium --- # Knowledge Base Update Sync the `knowledge-base` skill's index with the contents of the knowledge base on disk, then run a health check. Companion skill to `knowledge-base`: where `knowledge-base` processes new documents one at a time and answers queries, this skill keeps the index honest and surfaces drift. ## Knowledge Base Location Edit the path below to match the knowledge base root used by the `knowledge-base` skill on this system: ``` / ``` All paths in this skill are relative to that root. A common default is `~/knowledge-base/`. ## Directory Structure The knowledge base supports two document storage patterns: **Pattern A: Per-document subfolder** (output of a content pipeline like `slides-content`) ``` / ├── topic-folder/ │ ├── 2026-01-28 Author. Title./ │ │ ├── Title._text.md │ │ ├── Title._summary.md │ │ └── Title._slides.pdf ``` **Pattern B: Flat files** (output of the `knowledge-base` Process Inbox mode) ``` / ├── topic-folder/ │ ├── 2026-03-18 Author. Title.pdf │ ├── 2026-03-18 Author. Title._text.md │ └── 2026-03-18 Author. Title._summary.md ``` Topic folders are dynamic: any immediate subdirectory of the knowledge base root other than the inbox folder, any blog folder, and any `*_build/` directory is a topic folder. When scanning, search both patterns: - Flat: `/*_summary.md` - Subfolder: `/*/*_summary.md` **Reference material (`materials/` subfolders):** any subfolder named `materials/` at any depth inside the knowledge base is reference-only. Skip its contents entirely during sync and health checks. No scanning, no index entries, no missing-summary warnings, no naming checks. Use this to park files that should live inside a topic folder for proximity but are not indexable knowledge base content (third-party reference docs, working notes, artifacts from external projects). ## Index Format `index.md` is a markdown table at the knowledge base root: ```markdown | Date | Author | Title | Topic | Summary | |------|--------|-------|-------|---------| | 2026-03-18 | Last | Document Title | topic-folder | One-line summary of the document | ``` ## Topics File Format `topics.md` describes each topic folder: ```markdown # Knowledge Base Topics ## topic-folder One- to two-sentence description of what this folder collects. ``` ## Update Steps ### Step 1: Sync the index Scan all topic folders for documents not in `index.md`. Do not descend into any subfolder named `materials/`; its contents are reference-only and must not appear in the index. For each unindexed document found: - If it has a `_summary.md`, read it and append an index entry - If it has a source file but no `_summary.md`, note it as missing (do not generate; report it) - Remove entries in `index.md` for files that no longer exist on disk Update `topics.md` with current folder descriptions based on the contents of each folder. Existing descriptions are not overwritten if the folder's purpose has not changed; new folders get a draft description for the user to refine. ### Step 1b: Clean up inbox build folder Scan the inbox build folder (e.g., `/_build/`) for split directories (`split_*/`). For each split directory, check whether the corresponding source file still exists in the inbox. If the source file has already been moved out of the inbox (i.e., it no longer exists there), the splits are stale and can be deleted. Present the list of stale split folders with their sizes, then delete them after confirmation. If the inbox build folder is empty after cleanup, remove it too. ### Step 2: Health check Skip any path under a `materials/` subfolder. Report any issues found: - **Missing summaries:** source files without a corresponding `_summary.md` - **Orphaned summaries:** `_summary.md` files without a corresponding source file - **Naming inconsistencies:** files not matching the expected convention (the default is `YYYY-MM-DD Last. Title.ext`; adjust to whatever convention the `knowledge-base` skill uses on this system) - **Duplicate content:** files with very similar titles or content across different folders - **Topic suggestions:** documents that might fit better in a different folder based on their summary content - **Gaps:** topics with few sources where more research would strengthen the knowledge base Offer to fix automatically where possible (e.g., move misplaced files, rename inconsistencies). Wait for user confirmation before making any moves or renames. ## Constraints - **Never delete original source files.** Rename and move only; never delete a source. - **Never overwrite existing summaries.** If a summary already exists, skip unless the user explicitly asks to regenerate. - **Index updates respect existing entries.** Add new entries, remove entries for missing files, but do not silently rewrite existing rows. - **Topic folders are user-created.** Suggest new folders but wait for approval before creating them. - **Read-only on `materials/`.** Never index, scan, or report on anything under a `materials/` subfolder. ## Customization This skill assumes the `knowledge-base` skill's directory and naming conventions. If your conventions differ, edit: - The knowledge base root path at the top of this file - The directory pattern descriptions if you use a different layout (e.g., topics nested under categories) - The naming convention used in the health check - The list of "skip" folder names (`aa-inbox/`, etc.) if your inbox or auxiliary folders are named differently