knowledge-base-update

name	knowledge-base-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:

<knowledge-base-root>/

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)

<knowledge-base-root>/
├── 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)

<knowledge-base-root>/
├── 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, any auxiliary folders (for example, a recents or symlink folder, a search-index or database folder, or a documentation folder that describes the knowledge base process itself rather than holding indexable content), and any *_build/ directory is a topic folder. When scanning, search both patterns:

• Flat: <topic-folder>/*_summary.md
• Subfolder: <topic-folder>/*/*_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:

| 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:

# 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., <inbox>/<inbox>_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). Optional: if your knowledge base intentionally lets legacy and current naming conventions coexist permanently, turn this check off so it does not propose the same renames on every run. The same applies to empty or sparse topic folders kept as deliberate placeholders; do not flag them as defects.
• 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