kb-ingest

Knowledge Bank Ingest

Ingest external knowledge sources into the knowledge bank through an interactive workflow. Unlike session-recap (which extracts from Claude Code sessions), this skill handles standalone sources — articles, gists, design docs, PDFs, URLs, or any knowledge-bearing document.

Knowledge Bank Location: Read from ~/.claude/plugins/config/second-brain/config.json. Configure via skills/common/setup_kb_path.sh --configure.

Philosophy: A single source can touch multiple KB pages. The discussion between you and the user shapes what gets preserved — this is not a summarizer, it's a collaborative knowledge integration tool.

---

Invocation

Manual

• Slash command: /second-brain:kb-ingest
• Skill tool: Skill({ skill: "second-brain:kb-ingest" })

Natural Language Triggers

• "Ingest this article into the knowledge bank"
• "Add this to the KB"
• "Process this document for the knowledge bank"
• "I want to save the key insights from this"

Arguments

Provide a source path, URL, or indicate inline content:

/second-brain:kb-ingest /path/to/article.md
/second-brain:kb-ingest https://example.com/interesting-post

---

Workflow

Step 1: READ

Read the source document:

• File path: Use Read tool directly
• URL: Use WebFetch to retrieve content
• Inline text: Accept content pasted by the user

For large sources (>100KB), apply the distillation guide — extract essentials, target 95% size reduction.

Identify:

• Key concepts, patterns, and principles
• Actionable techniques or methodologies
• Connections to existing KB knowledge

Step 2: DISCUSS

Present key takeaways to the user and engage in interactive discussion:

1. Summarize the source's main contributions (3-5 bullet points)
2. Propose what's worth preserving and as what type:
   • Concept doc — if the source reveals an architectural pattern or principle
   • Component doc — if it describes a specific system or tool
   • Best practice doc — if it documents a reusable methodology
   • Multiple docs — if the source covers several distinct topics
3. Ask the user:
   • What resonates most? What should be emphasized?
   • What's the project context? (determines KB placement under projects/{project}/)
   • Anything to add from their own experience?

The discussion itself generates insights beyond the raw source. Capture these.

Example:

Source: Article on event sourcing patterns
Summarize: "3 key takeaways: (1) events as source of truth, (2) projection 
  rebuilds from event stream, (3) snapshot optimization for large streams"
Propose: "This maps to a concept doc — fits under projects/cc/concepts/ 
  since it's an architectural pattern we could apply to session management"
Ask: "Does this connect to any patterns you've seen in your codebase? 
  Should we emphasize the snapshot optimization angle?"

Step 3: CREATE

Generate KB document(s) incorporating both the source content AND discussion insights.

Templates: Use existing templates from session-recap/references/:

• concept-template.md
• component-template.md
• best-practice-template.md

Cross-references: Run cross-reference discovery:

./skills/session-recap/scripts/search_cross_references.sh "keyword" [project]

Target 5-8 WikiLinks (lower than session-recap's 10-15 since standalone ingests have less cross-referencing context).

Frontmatter (MUST include):

---
title: Document Title
aliases: [Alt 1, Alt 2]
tags: [category, topic]
type: concept|component|best-practice
created: YYYY-MM-DD
modified: YYYY-MM-DD
project: {project}
source-type: article|document|url|gist
ingested-from: /path/to/source.md or https://url
---

Obsidian Syntax: When obsidian skills are available, MUST invoke /obsidian:obsidian-markdown before creating documents.

Updating existing docs: If the new knowledge connects to or supersedes existing KB pages, update them too — add cross-references, revise outdated claims, note where new data strengthens or challenges existing content. This follows the LLM Wiki principle that a single ingest can touch multiple pages.

Step 4: INTEGRATE

After creating/updating documents:

1. Regenerate index:

source skills/common/generate_index.sh
generate_index "$KB_PATH"

2. Append operation log:

source skills/common/obsidian_helpers.sh
append_kb_log "$KB_PATH" "ingest" "kb-ingest" "Ingested [source name]. Created: [docs]. Updated: [docs]"

3. Verify created documents:

./skills/session-recap/scripts/count_wikilinks.sh document.md 5
./skills/session-recap/scripts/validate_obsidian_syntax.sh document.md

---

Batch Ingest

For multiple sources: "Ingest all .md files in /path/to/folder/"

• READ all sources first
• DISCUSS as a batch — present combined takeaways, let user prioritize
• CREATE docs per source (or merged if topics overlap)
• INTEGRATE once at the end

---

Key Design Decisions

Decision	Rationale
Interactive DISCUSS step	User's context and emphasis shape what gets preserved — not a blind summarizer
5-8 WikiLinks (not 10-15)	Standalone ingests have less cross-referencing context than full session recaps
Reuse session-recap templates	No duplication — one set of templates for all KB documents
No daily log	Daily logs are session-recap's responsibility
No reflection gate	Reflections come from doing work, not reading about it
Can update existing pages	LLM Wiki principle — a single source can touch multiple wiki pages

---

Resources

• KB Schema — Unified conventions for all KB documents
• Ingest Guide — Source types, classification, and quality standards
• Distillation Guide — For large sources

---

Completion Criteria

Ingest is complete when:

1. Source has been read and discussed with user
2. KB document(s) created with valid frontmatter and 5-8 WikiLinks
3. Obsidian syntax validation passes
4. _meta/index.md regenerated
5. _meta/log.md entry appended