kb-import

KB Import Workflow

Import knowledge from existing documents into your knowledge base.

When to Use

• Adding knowledge from existing documentation
• Converting unstructured docs into structured KB entries
• Bulk-importing content into a new KB

Modes

• Single-document mode (default): one source document is split into one or more KB entries. Use Steps 1 to 6 below.
• Bulk mode: many source documents are ingested at once from a directory or a list of files. Use when the user points at a folder or provides a list longer than ~3 files. See Bulk Mode at the bottom.

Step 1: Understand the KB Structure

Read the KB config to understand available categories:

kb/.kb-config.yaml

Read the index to see what already exists:

kb/index.md

Step 2: Read the Source Document

Read the source file provided by the user. Supported formats:

• Markdown (.md)
• PDF (.pdf, use the Read tool with page ranges for large files)
• Plain text (.txt)

Step 3: Plan the Extraction

Analyze the document and propose a plan to the user:

1. How many KB entries should be created?
2. What categories do they belong to?
3. Suggested titles for each entry

Present this as a table:

| # | Title | Category | Source Section |
|---|-------|----------|---------------|
| 1 | ... | ... | ... |

Wait for user confirmation before proceeding.

Step 4: Create KB Entries

For each planned entry, create a markdown file with YAML frontmatter:

---
title: "Entry Title"
description: "Brief one-liner for index lookup"
category: {category}
tags: [{tag1}, {tag2}]
sources: ["{source_filename}"]
last_updated: "{today's date}"
related:
  - {category}/{related-file}.md
---

## Section Title

Content here. Write clear, quotable statements.
Each fact should be a self-contained sentence that can be cited as evidence.

Content Guidelines

• Preserve specifics: Keep exact numbers, dates, names, versions. Keep concrete customer/product examples by name (e.g., "Acme Corp", "Globex") — they make abstract concepts tangible and shouldn't be stripped "for neutrality".
• One topic per entry: Don't create catch-all files
• Quotable statements: Write so that individual sentences can be cited as evidence
• Capture the easily-missed content types when the source covers them: stakeholders (one entry per key person with role + ownership + contact pattern), projects (goal/owner/status), repositories (purpose/ownership). These are the most commonly skipped in first-pass imports.
• No opinions or speculation: Only include facts from the source document
• Use markdown structure: Headers, bullet points, tables for structured data