setup-knowledge-base

name	setup-knowledge-base
description	Interactive onboarding to create a structured knowledge base. Defines categories, scaffolds the directory structure, creates the index, and optionally imports initial content. Run this first before using /kb-answer or /kb-import.

Knowledge Base Setup

Interactive setup that creates a structured, evidence-backed knowledge base in your project.

When to Use

• Starting a new knowledge base from scratch
• Adding a KB to an existing project

Step 1: Discover Purpose

Ask the user (one question at a time, use AskUserQuestion):

1. What is this KB for? (e.g., product documentation, security/compliance, company knowledge, sales enablement, internal policies)
2. Who will query it? (e.g., you personally, your team, AI agents answering questions)
3. What categories make sense? Suggest 3-5 based on the domain, let the user adjust.

Example category suggestions by domain:

• Product docs: technical, integrations, deployment, security, faq
• Company knowledge: general, policies, processes, teams, faq
• Sales enablement: product, competitive, customer-success, pricing, faq
• Security/compliance: security, compliance, technical, general, faq

Step 2: Confirm Plan

Before creating anything, present the plan to the user:

I'll create this structure in your project:

kb/
  .kb-config.yaml
  index.md
  scopes/
    _default.yaml
    README.md
  {category1}/
  {category2}/
  {category3}/
scripts/
  kb-index.py
  kb-verify.py
  kb-validate.py
  kb-search.py
CLAUDE.md (or append to existing)

Ready to proceed?

Wait for user confirmation.

Step 3: Scaffold the KB

Read the template files from this plugin and adapt them for the user's project:

1. Read templates/kb/.kb-config.yaml from this plugin. Create kb/.kb-config.yaml in the user's project, replacing the placeholder categories with the ones chosen in Step 1. Replace {{today}} with today's date.

2. Read templates/kb/index.md from this plugin. Create kb/index.md, adding seed keywords for each chosen category. For example, if the user chose "security" and "technical", add initial keyword entries:

   | encryption, certificates, access | security/ |
   | API, architecture, deployment | technical/ |
   

3. Read templates/kb/scopes/_default.yaml from this plugin. Copy to kb/scopes/_default.yaml.

4. Read templates/kb/scopes/README.md from this plugin. Copy to kb/scopes/README.md.

5. Create empty directories for each chosen category: kb/{category1}/, kb/{category2}/, etc.

6. Read scripts/kb-index.py from this plugin. Copy to scripts/kb-index.py in the user's project.

7. Read scripts/kb-verify.py from this plugin. Copy to scripts/kb-verify.py in the user's project.

8. Read scripts/kb-validate.py from this plugin. Copy to scripts/kb-validate.py in the user's project.

9. Read scripts/kb-search.py from this plugin. Copy to scripts/kb-search.py in the user's project.

Step 4: Create Project CLAUDE.md

Read templates/CLAUDE.md from this plugin. Create (or append to existing) CLAUDE.md in the user's project root. Replace {{category}} placeholders with the actual categories chosen in Step 1.

Step 5: Populate from Sources

The KB structure is ready, but empty. Ask the user:

"Do you have existing knowledge sources you'd like to import? (Notion pages, Slack channels, Confluence, local files)"

• If yes: run /kb-refresh to populate the KB from those sources. It handles source discovery, scraping, and entry creation.
• If no or skip: create one example entry in the first category to demonstrate the format. Read templates/kb/example/sample-entry.md from this plugin for the format, but write an entry relevant to the user's domain rather than copying the sample.

Step 6: Verify

Run the index script to confirm everything is wired up:

python3 scripts/kb-index.py

Regenerate the "All Files by Category" section of kb/index.md from the current entries:

python3 scripts/kb-index.py --write

Validate KB health (frontmatter, categories, related links):

python3 scripts/kb-validate.py

If kb-index.py lists the entries and kb-validate.py reports "All entries valid", setup is complete.

Step 7: Summary

Tell the user:

• What was created and where
• How to add new entries (create .md files with YAML frontmatter in the right kb/{category}/ folder; nested sub-folders like kb/security/access/ are supported)
• How to query the KB (/kb-answer)
• How to import documents or bulk-import a directory (/kb-import)
• How to add more sources or refresh existing ones (/kb-refresh)
• How to list all entries (python3 scripts/kb-index.py)
• How to search (python3 scripts/kb-search.py "keyword")