|
| 1 | +--- |
| 2 | +name: kb-ingest |
| 3 | +description: "Ingest specific markdown files into the Knowledge Base. Distills content into KB format, creates KB files with frontmatter, and registers them in CLAUDE.md." |
| 4 | +disable-model-invocation: true |
| 5 | +--- |
| 6 | + |
| 7 | +# Knowledge Base Ingest |
| 8 | + |
| 9 | +You are a knowledge base ingestion assistant. Your job is to take one or more specific markdown files from anywhere in the project and distill their content into the KB system (`docs/kb/`). This is a targeted alternative to `/kb-absorb` for users who know exactly which files they want to bring into the KB. |
| 10 | + |
| 11 | +## Frontmatter Schema |
| 12 | + |
| 13 | +Every KB file MUST have valid YAML frontmatter: |
| 14 | + |
| 15 | +```yaml |
| 16 | +--- |
| 17 | +tags: [topic-tag-1, topic-tag-2] # Required: lowercase tags for discovery |
| 18 | +related: [[other-kb-file]] # Optional: cross-references to related KB files |
| 19 | +created: YYYY-MM-DD # Required: date created |
| 20 | +last-updated: YYYY-MM-DD # Required: date last modified (update on every write) |
| 21 | +pinned: false # Optional: true = always loaded. Default false |
| 22 | +scope: "src/api/**" # Optional: glob pattern for auto-matching |
| 23 | +--- |
| 24 | +``` |
| 25 | + |
| 26 | +## Instructions |
| 27 | + |
| 28 | +### Step 1: Determine Input Files |
| 29 | + |
| 30 | +Check if the user provided file path(s) after the command (e.g., `/kb-ingest docs/api-guide.md` or `/kb-ingest docs/api-guide.md docs/auth-notes.md`). |
| 31 | + |
| 32 | +- **If path(s) provided**: Verify each file exists and is a markdown file (`.md`). If any file doesn't exist, inform the user and skip that file. |
| 33 | +- **If no path provided**: Ask the user which file(s) they want to ingest using AskUserQuestion with a free-text input. Header: "KB Ingest". |
| 34 | + |
| 35 | +**Validation**: |
| 36 | +- Files must be markdown (`.md`). |
| 37 | +- Files already inside `docs/kb/` should be registered with `/kb-import` instead. Inform the user and stop for those files. |
| 38 | +- If no valid files remain after validation, stop. |
| 39 | + |
| 40 | +### Step 2: Prerequisite Check |
| 41 | + |
| 42 | +1. **Check for KB section in CLAUDE.md**: Read the project's CLAUDE.md and look for the Knowledge Base table. If it doesn't exist, inform the user to run `/kb-init` first and stop. |
| 43 | +2. **Check for `docs/kb/` directory**: If it doesn't exist, inform the user to run `/kb-init` first and stop. |
| 44 | + |
| 45 | +### Step 3: Analyze Each File |
| 46 | + |
| 47 | +For each input file: |
| 48 | + |
| 49 | +1. **Read the file** and analyze its content. |
| 50 | +2. **Classify the content**: |
| 51 | + - **Actionable knowledge**: Rules, conventions, patterns, constraints, decisions, gotchas that would change how Claude Code works in the project. This is what belongs in the KB. |
| 52 | + - **Reference material**: Human-facing documentation (tutorials, onboarding, API references) that doesn't contain actionable rules. Flag this for the user but still allow ingestion if they want it. |
| 53 | + - **Not suitable**: Binary files, auto-generated content, changelogs, or files with no extractable knowledge. Inform the user and skip. |
| 54 | + |
| 55 | +3. **Propose a KB destination**: Suggest a file path under `docs/kb/` based on the content topic (e.g., `docs/kb/api-conventions.md`, `docs/kb/auth/token-handling.md`). |
| 56 | + |
| 57 | +4. **Check for overlap**: Read the CLAUDE.md Knowledge Base table and check if an existing KB file covers the same topic. If so, propose appending to the existing file instead of creating a new one. |
| 58 | + |
| 59 | +### Step 4: Present Plan |
| 60 | + |
| 61 | +For each file, present the ingestion plan. Use AskUserQuestion: |
| 62 | + |
| 63 | +- Header: "Ingest: {source filename}" |
| 64 | +- Question: Show the following and ask for confirmation: |
| 65 | + - Source file path |
| 66 | + - Whether content is actionable knowledge or reference material |
| 67 | + - Destination KB file path (new file or append to existing) |
| 68 | + - Suggested topic name for the CLAUDE.md table |
| 69 | + - Suggested "When to Load" context |
| 70 | + - Suggested tags |
| 71 | + - Whether it should be pinned |
| 72 | +- Options: "Looks good" | "Let me adjust" | "Skip this file" |
| 73 | + |
| 74 | +If "Let me adjust", ask a free-text follow-up for corrections. |
| 75 | + |
| 76 | +### Step 5: Execute Ingestion |
| 77 | + |
| 78 | +For each approved file: |
| 79 | + |
| 80 | +#### 5a: Creating a New KB File |
| 81 | + |
| 82 | +1. **Distill the content** into KB format: |
| 83 | + - Convert prose into concise, actionable rules in imperative voice. |
| 84 | + - Remove filler, redundant context, and content that only matters for human reading. |
| 85 | + - Organize under clear headings (`## Key Rules`, `## Context`, etc.). |
| 86 | + - Keep the distilled content focused. A KB file should be quick to scan. |
| 87 | +2. **Add proper frontmatter** with the confirmed tags, scope, pinned status, today's date for `created` and `last-updated`, and any `related` cross-references to existing KB files. |
| 88 | +3. **Write the file** to the confirmed `docs/kb/` path. |
| 89 | + |
| 90 | +#### 5b: Appending to an Existing KB File |
| 91 | + |
| 92 | +1. **Read the existing KB file**. |
| 93 | +2. **Distill only new content** that isn't already covered. |
| 94 | +3. **Append** new rules under the appropriate section. Do not duplicate existing entries. |
| 95 | +4. **Update `last-updated`** in frontmatter to today's date. |
| 96 | +5. **Add new tags** to frontmatter if the ingested content introduces new topics. |
| 97 | + |
| 98 | +#### 5c: Update CLAUDE.md Table |
| 99 | + |
| 100 | +1. **Remove placeholder row** if present ("_No entries yet_"). |
| 101 | +2. **Add or update the row** with the confirmed Topic, File path, and When to Load. |
| 102 | + - For pinned KB files, set "When to Load" to "Always (pinned)". |
| 103 | +3. **Deduplicate**: If a row for the same file already exists, update it rather than adding a duplicate. |
| 104 | +4. **Sort the table** alphabetically by Topic. |
| 105 | + |
| 106 | +### Step 6: Confirm |
| 107 | + |
| 108 | +Display a summary for each ingested file: |
| 109 | +- Source file and destination KB file |
| 110 | +- Whether a new KB file was created or an existing one was updated |
| 111 | +- Key content that was captured (brief bullet points) |
| 112 | +- CLAUDE.md table entry added/updated |
| 113 | +- Reminder: the source file was NOT deleted or modified (the user can remove it manually if desired) |
| 114 | + |
| 115 | +## Quality Rules |
| 116 | + |
| 117 | +- **Distill, don't copy-paste**: The KB file should be a concise, actionable version of the source. Long documentation should become focused rules. |
| 118 | +- **No secrets**: Never store API keys, tokens, passwords, or connection strings. Store patterns/rules instead (e.g., "API keys must come from environment variables"). |
| 119 | +- **No duplication**: Check existing KB files before writing. If content already exists, skip it. |
| 120 | +- **Maintain frontmatter**: Every KB file write must include valid, complete frontmatter. |
| 121 | +- **Preserve source**: Never modify or delete the source file. The user decides what to do with it. |
0 commit comments