KB Builder — Self-Building, Self-Healing Knowledge Base

Why This Exists

In April 2026, Andrej Karpathy posted about using LLMs to build personal knowledge bases — ingesting raw documents, having an LLM "compile" a wiki of markdown files, then querying and enhancing it over time. The post went massively viral. His closing line:

"I think there is room here for an incredible new product instead of a hacky collection of scripts."

He later shared an "idea file" — a spec you hand to an agent to build your own version. The core insight: knowledge bases operated by LLM agents are the next major productivity unlock.

This skill is that product. Instead of hacky scripts and flat markdown files, it uses Senso as the knowledge platform (vector search, folder hierarchy, document versioning, brand-aligned generation, review/publish pipeline) and your AI agent as the autonomous operator.

Karpathy's DIY approach	This skill
Manual indexing into raw/ directory	Agent researches and ingests automatically
Flat .md files, LLM-maintained indexes	Senso KB — vector search, versioned docs, no scale ceiling
LLM reads its own summaries (~100 doc limit)	Semantic search with relevance scoring at any scale
Generic LLM markdown output	Brand-aligned generation with voice, tone, and content templates
Ad-hoc health checks	Structured self-heal loop — find gaps, fill them, verify
No publishing pipeline	Draft → review → publish workflow

The Core Principle: Continuous Improvement

Everything in this workflow is a living system — nothing is "set and done."

The KB, brand kit, content types, prompts, and generated content are all interconnected. Improvements in one cascade to the others:

• More KB documents → richer brand understanding → better brand kit
• Better brand kit → higher quality content generation → better drafts
• More prompts → wider topic coverage → gaps found during audit → more KB documents
• Each self-heal pass strengthens every layer

Never skip. Never delete. Always improve. Every run should leave the entire system stronger than it found it.

What It Does

One command triggers the full knowledge base lifecycle:

1. Foundation — Set up or refine brand voice, tone, and content type templates
2. Research — Web search the company thoroughly
3. Ingest — Create folders, ingest documents organized by topic
4. Generate — Create prompt questions, generate brand-aligned content, publish drafts
5. Self-Heal — Audit everything (KB, brand kit, content types, content quality), fill gaps, verify
6. Repeat — Each run layers new depth and strengthens every layer

How to Run This Skill

This skill works with any AI agent that can execute shell commands and search the web. Pick the option that fits your setup:

Option A: Claude Code (recommended — fastest to start)

Run directly in the Claude Code terminal. Claude Code has built-in web search, file ops, and bash — everything this skill needs. Just install the prerequisites, open Claude Code, and ask it to build your KB.

npm install -g @senso-ai/cli
export SENSO_API_KEY="your-key"
senso skills install --all
npx @senso-ai/shipables install @senso-ai/senso-kb-builder

Then in Claude Code: "Build a knowledge base for [your company]"

Option B: Claude Managed Agents (autonomous cloud execution)

For hands-off, long-running builds, use Claude Managed Agents — Anthropic's cloud-hosted agent infrastructure. The agent runs in a container with web search and bash built in. You define the Senso CLI commands as custom tools, send a task, and stream the results. The agent plans and executes the full lifecycle autonomously without your terminal being open.

Best for: production workflows, scheduled KB builds, multi-agent orchestration (e.g., one agent researches while another audits).

See the Managed Agents quickstart to set up your first session, and the tools docs for configuring custom tools that map to Senso CLI commands.

Option C: Other compatible agents

This skill works with any agent that can run senso CLI commands and search the web:

• Cursor — Install skills, use the Cursor agent
• Codex CLI — OpenAI's terminal agent
• GitHub Copilot — In agent mode with terminal access
• Gemini CLI — Google's terminal agent
• Cline — VS Code agent extension

The Senso CLI and skills are agent-agnostic — senso skills install --all detects your agent and installs accordingly.

Prerequisites

• Node.js 18+
• Senso CLI installed: npm install -g @senso-ai/cli
• SENSO_API_KEY environment variable set (get yours at https://v2.senso.ai)
• Senso skills installed: senso skills install --all

Trigger

Activate this skill when the user asks to:

• "Build a KB for [company]"
• "Populate my knowledge base"
• "Set up Senso for [company]"
• "Run the KB builder"
• "Improve my knowledge base"
• "Run a heal pass"

Step 0: Confirm Target Org

Before ANY writes, verify the target:

senso whoami --output json --quiet

Show the user the org name and ask them to confirm. If they say no, tell them to update SENSO_API_KEY and retry.

Do not proceed until the user confirms the org.

Step 1: Ask Which Company

If the user hasn't specified a company, ask:

Which company do you want to build a KB for?

Use their answer as the target for all subsequent steps.

---

Phase 1: Foundation — Brand Kit + Content Types

1a. Brand Kit — Always Evaluate, Always Improve

Read the current brand kit:

senso brand-kit get --output json --quiet

If empty: Research the company's website to understand their brand voice, tone, and positioning, then create the initial brand kit.

If already configured: Review it against what you know about the company. Research the company's latest website and messaging. If you find new insights — refined positioning, updated tone, new writing patterns, additional rules — update the brand kit with a patch:

senso brand-kit patch --data '{
  "guidelines": {
    "voice_and_tone": "Updated voice description based on latest research"
  }
}' --output json --quiet

To set a brand kit from scratch:

senso brand-kit set --data '{
  "guidelines": {
    "brand_name": "Company Name",
    "brand_domain": "company.com",
    "brand_description": "What the company does in 1-2 sentences",
    "voice_and_tone": "Description of how the brand communicates",
    "author_persona": "Who content is written as (e.g., The Company Team)",
    "global_writing_rules": [
      "Rule 1",
      "Rule 2"
    ]
  }
}' --output json --quiet

The brand kit is a living document. Every run should evaluate whether the current brand kit accurately reflects the company's latest positioning. The more KB content you have, the better you understand the brand — feed that understanding back into the brand kit.

1b. Content Types — Expand and Refine

Check existing content types:

senso content-types list --output json --quiet

If none exist, create at least 3 foundational templates:

FAQ Page:

senso content-types create --data '{
  "name": "FAQ Page",
  "config": {
    "template": "Create a comprehensive FAQ page with 8-12 questions and answers. Each Q&A should be concise (2-3 sentences per answer). Group related questions under subheadings. Use the brand voice throughout. End with a clear call-to-action.",
    "writing_rules": ["Keep answers under 100 words", "Use natural question phrasing", "Link to detailed resources where relevant"]
  }
}' --output json --quiet

Blog Post:

senso content-types create --data '{
  "name": "Blog Post",
  "config": {
    "template": "Write a 1000-1500 word educational blog post. Start with a hook that identifies the reader pain point. Include 3-5 subheadings. Use data, examples, or case studies to support key points. End with a summary and call-to-action. Optimize for search with a clear primary keyword.",
    "writing_rules": ["Use subheadings every 200-300 words", "Include at least one statistic or proof point", "Write at a professional but accessible reading level"]
  }
}' --output json --quiet

Comparison Page:

senso content-types create --data '{
  "name": "Comparison Page",
  "config": {
    "template": "Create a fair but persuasive comparison page. Start with the problem both solutions address. Use a comparison table for features. Highlight 3-4 key differentiators. Include a section on who each solution is best for. End with a recommendation and call-to-action.",
    "writing_rules": ["Be factually accurate about competitors", "Lead with value not features", "Include a comparison table"]
  }
}' --output json --quiet

If content types already exist, review them:

• Are the templates producing good results? If not, update them with senso content-types patch.
• Are there content formats the company needs that aren't covered? Create new types (e.g., Case Study, Landing Page, Product Brief).
• As the KB grows, content types should evolve to leverage the richer knowledge available.

---

Phase 2: Research + Ingest

2a. Research

Use web search to research the company thoroughly. Cover:

• Company overview, mission, what they do
• Products/services and key features
• Target audience and use cases
• Competitive positioning and differentiators
• Team, leadership, culture (if available)
• Case studies, testimonials, proof points
• Pricing model (if public)
• Industry/vertical focus

On subsequent runs, focus research on what's new or changed — recent news, updated products, new case studies, competitive shifts.

2b. Create Folder Structure

Check existing folders first:

senso kb my-files --output json --quiet

Reuse existing folders where they match. Only create new folders for categories not already covered:

senso kb create-folder --name "Company Overview" --output json --quiet
senso kb create-folder --name "Products & Features" --output json --quiet
senso kb create-folder --name "Use Cases & Industries" --output json --quiet
senso kb create-folder --name "Competitive Intel" --output json --quiet
senso kb create-folder --name "Case Studies" --output json --quiet
senso kb create-folder --name "FAQs" --output json --quiet
senso kb create-folder --name "Content Strategy" --output json --quiet

Save the returned folder IDs — you'll need them for ingestion.

2c. Ingest Documents

For each research finding, create a separate document:

senso kb create-raw --data '{
  "title": "Document Title",
  "text": "Markdown content here...",
  "kb_folder_node_id": "folder-id-here"
}' --output json --quiet

Rules:

• Never delete or overwrite existing documents — only add new ones
• One document per subtopic — NOT one giant document
• Use clear, descriptive titles
• Format content as markdown
• Include source URLs where available
• Place each document in the appropriate folder
• Search the KB first to understand what already exists — avoid duplicating topics, but DO add new depth to existing topics
• Each run should ADD depth and breadth to the existing KB

---

Phase 3: Content Generation

3a. Check Credits

senso credits balance --output json --quiet

Warn the user if credits are low before proceeding.

Important: Always attempt generation. Every org starts with its own credit balance. Never skip generation based on failures from a different org or a previous session. If generation fails, report the error — do not silently skip it.

3b. Create Prompt Questions

Review existing prompts first:

senso prompts list --output json --quiet

Add new prompts that cover topics not yet addressed, especially topics surfaced during Phase 2 research. Create questions that potential customers would ask, across all funnel stages:

senso prompts create --data '{
  "question_text": "What is [topic] and why does it matter?",
  "type": "awareness"
}' --output json --quiet

Funnel stages:

• awareness — "What is X?", "Why does X matter?"
• consideration — "How does X compare to Y?", "What features should I look for?"
• decision — "What results have customers achieved?", "What does pricing look like?"
• evaluation — "How do I evaluate X for my team?", "What's the implementation process?"

On first run, create at least 8-12 prompts. On subsequent runs, add prompts for newly discovered topics and gaps.

3c. Generate Content

Use the content type IDs from Phase 1 and prompt IDs from 3b:

senso generate sample --prompt-id <prompt_id> --content-type-id <content_type_id> --output json --quiet

Warning: Each generation takes 30-90 seconds. Inform the user before starting.

Generate at least 2-3 pieces of content using different prompt + content type combinations. On subsequent runs, generate content for any new prompts added.

3d. Save as Drafts

Save generated content into the review pipeline:

senso engine draft --data '{
  "geo_question_id": "<prompt_uuid>",
  "raw_markdown": "<generated_markdown>",
  "seo_title": "<seo_title>"
}' --output json --quiet

Drafts must always be created on every run. Two paths:

1. If senso generate sample succeeds — save the generated content as a draft
2. If generation fails or times out — write the content yourself using the KB and brand kit as context, then save it as a draft via senso engine draft

Either way, at least 2-3 drafts should exist after every run. The drafts pipeline is a core part of the Senso workflow — never skip it.

---

Phase 4: Self-Heal — Audit Everything, Improve Everything

The self-heal phase audits the ENTIRE system — not just KB content gaps, but brand kit accuracy, content type effectiveness, prompt coverage, and content quality.

4a. Audit KB Content

Search the KB for each major topic:

senso search "<topic>" --output json --quiet

For each search, evaluate:

• Is the answer comprehensive or thin/incomplete?
• Are there obvious subtopics missing?
• Are relevance scores consistently above 0.5?

4b. Audit Brand Kit

Re-read the brand kit (senso brand-kit get). Compare it against what the KB now contains:

• Does the voice_and_tone still accurately describe how the company communicates?
• Are the global_writing_rules comprehensive enough based on patterns you see in the content?
• Has the company's positioning evolved based on newer research?

If the brand kit needs refinement, update it with senso brand-kit patch.

4c. Audit Content Types

Review existing content types (senso content-types list):

• Are the templates producing the right output structure?
• Are there content formats the company needs that don't have a template yet?
• Should writing_rules be updated based on what you've learned about the brand?

Add or update content types as needed.

4d. Audit Prompt Coverage

Review existing prompts (senso prompts list):

• Are there customer questions not yet covered?
• Has the research surfaced new topics that need prompts?
• Are all funnel stages represented?

Add new prompts for any gaps.

4e. Fill Content Gaps

For any KB gaps found in 4a:

1. Research the missing topic via web search
2. Ingest new documents to fill the gap
3. Re-search to verify the gap is filled

4f. Report + Log

Compile a KB Health Report and save it as a build log in the KB.

First, check if a "Build Logs" folder exists. If not, create it:

senso kb create-folder --name "Build Logs" --output json --quiet

Then save the log as a timestamped document in the Build Logs folder:

senso kb create-raw --data '{
  "title": "Build Log — 2026-04-09T12:00:00",
  "text": "<full log content as markdown>",
  "kb_folder_node_id": "<build-logs-folder-id>"
}' --output json --quiet

The log document MUST include:

# KB Build Log — [timestamp]

## Run Info
- **Company:** [company name]
- **Org:** [org name from senso whoami]
- **Run type:** Full build / Heal pass

## Actions Taken

### Phase 1: Foundation
- Brand kit: [Created / Updated / No changes]
  - Changes: [list what was added or refined]
- Content types: [Created X / Updated X / No changes]
  - New types: [list]

### Phase 2: Research + Ingest
- Documents ingested: [count]
  - [Title 1] → [folder] (content_id: xxx)
  - [Title 2] → [folder] (content_id: xxx)
- Folders created: [count] [list]

### Phase 3: Content Generation
- Prompts created: [count] [list]
- Content generated: [count]
- Drafts saved: [count]

### Phase 4: Self-Heal
- Topics audited: [count]
- Gaps found: [count] [list]
- Gaps filled: [count] [list]
- Brand kit refined: [yes/no — what changed]
- Content types updated: [yes/no — what changed]

## Health Report

| Dimension | Status |
|-----------|--------|
| Brand kit | Configured / Updated this run / Needs attention |
| Content types | Count (new this run / total) |
| Documents ingested | Count (new this run / total) |
| Folders organized | Count |
| Prompts | Count (new this run / total) |
| Content generated | Count |
| Drafts published | Count |
| Gaps found | Count |
| Gaps filled | Count |
| Brand kit refinements | What changed and why |
| Search quality (avg score) | Score |

## Search Quality by Topic

| Topic | Score | Status |
|-------|-------|--------|
| [topic] | [score] | Strong / Weak / Gap |

The build logs serve as an audit trail. Over time, you can see how the KB evolved — each run should show fewer gaps and higher search scores. This is the KB maturing.

4g. Ask to Continue

After the report, ask the user:

Run another heal pass? [Y/n]

If yes, repeat Phase 4. Each pass should:

• Find fewer content gaps
• Produce a more refined brand kit
• Generate better content (because the KB and brand kit are richer)
• Surface diminishing returns — when the report shows minimal changes, the KB is maturing

---

All CLI Commands Reference

Operation	Command
Check org	senso whoami --output json --quiet
Get brand kit	senso brand-kit get --output json --quiet
Set brand kit	senso brand-kit set --data '{...}' --output json --quiet
Patch brand kit	senso brand-kit patch --data '{...}' --output json --quiet
List content types	senso content-types list --output json --quiet
Create content type	senso content-types create --data '{...}' --output json --quiet
Update content type	senso content-types patch <id> --data '{...}' --output json --quiet
List KB files	senso kb my-files --output json --quiet
List folder contents	senso kb children <folder_id> --output json --quiet
Create folder	senso kb create-folder --name "X" --output json --quiet
Create raw content	senso kb create-raw --data '{...}' --output json --quiet
Search KB	senso search "<query>" --output json --quiet
Check credits	senso credits balance --output json --quiet
List prompts	senso prompts list --output json --quiet
Create prompt	senso prompts create --data '{...}' --output json --quiet
Generate content	senso generate sample --prompt-id <id> --content-type-id <id> --output json --quiet
Save draft	senso engine draft --data '{...}' --output json --quiet
Get document	senso content get <content_id> --output json --quiet

All commands MUST include --output json --quiet flags.