---
name: kb
description: Manage an Obsidian-based AI knowledge vault with /kb add/find/process-pending/compile/health/tidy/add-video.
---

# /kb - AI Knowledge Vault

Manage the `knowledge/` directory in this repository as a reusable AI knowledge vault.

## Triggers

- `/kb process-pending`
- `/kb add [content or URL]`
- `/kb find [query]`
- `/kb add-video [file-or-directory]`
- `/kb compile`
- `/kb health`
- `/kb tidy`

## Guardrails

- Do not scan every `knowledge/*.md` file by default; start from `knowledge/_index.md`
- Store all knowledge entries under `knowledge/`
- Keep the original source content in full under `## 原始内容`
- Reuse existing tags and concept names when possible
- Prefer local config files for API keys; use environment variables as fallback
- Treat `knowledge/concepts/` as the primary navigation layer and `knowledge/reports/` as reusable query output
- `/kb add` and `/kb process-pending` use the same ingestion action: first produce a pending Markdown source with frontmatter, then create the normalized entry, update the index, and archive the source

## Workflows

### 1) `/kb process-pending`

Process files in `knowledge/inbox/manual/pending/` and turn them into structured entries.

Expected behavior:
1. Read `knowledge/_index.md` first for existing tags and concepts
2. For each pending Markdown file, extract metadata, summarize 1-3 key points, optionally add `我的思考`
3. Write a normalized entry to `knowledge/YYYY-MM-DD-title.md`
4. Update `knowledge/_index.md`
5. Move the source file to `knowledge/inbox/manual/processed/` or `review/` when uncertain

This workflow is handled directly by the agent, not by a Python CLI command.

### 2) `/kb add`

Add a single piece of knowledge from text, notes, or a URL.

Expected behavior:
1. Detect source type
2. If the input is a URL, prefer Defuddle CLI to fetch clean Markdown content instead of WebFetch:

```bash
defuddle parse "<URL>" --md -o "knowledge/inbox/manual/pending/YYYY-MM-DD-short-title.md"
```

   If title or domain metadata is needed, use:

```bash
defuddle parse "<URL>" -p title
defuddle parse "<URL>" -p domain
```

   The pending file must include frontmatter:
   - `date`
   - `source`
   - `source_type`
   - `source_url`
   - `tags` (can start as an empty list and be finalized during ingestion)
   - `confidence: raw`

   Keep the full Defuddle Markdown output as the body without truncation.
3. If the input is pasted text or notes, also write it first to `knowledge/inbox/manual/pending/YYYY-MM-DD-short-title.md` with the same frontmatter and full original body
4. Process the new pending source using the same action as `/kb process-pending`:
   - Read `knowledge/_index.md` for existing tags, concepts, and recent entries
   - Summarize 1-3 key points with the current agent
   - Optionally add `我的思考`
   - Choose tags by reusing existing names when possible
   - Choose related concepts from the index concept navigation
   - Write a normalized entry to `knowledge/YYYY-MM-DD-title.md`
   - Preserve the pending file body under `## 原始内容`
   - Update `knowledge/_index.md`
   - Move the pending source to `knowledge/inbox/manual/processed/`
5. Return the created entry path, tags, related concepts, and suggested links to existing entries

Fallbacks:
- If `defuddle` is not installed, install it with `npm install -g defuddle-cli`
- If Defuddle cannot fetch meaningful content, try another reader; if that still fails, keep a URL-only pending source with `confidence: raw` and move it to `knowledge/inbox/manual/review/`
- If Defuddle output is too short, mostly navigation, or lacks substantive body content, do not ingest it directly; move it to `review/`

### 3) `/kb find`

Search the knowledge vault and optionally generate a reusable report.

Command:

```bash
python3 .claude/skills/kb/scripts/knowledge_ops.py find "context engineering"
```

Output should prioritize:
- matching concepts
- matching entries
- key takeaways
- suggested follow-up reading

### 4) `/kb add-video`

Transcribe local video or audio files, lightly clean the transcript, and create knowledge entries.

Prerequisites:
- `pip3 install dashscope`
- `ffmpeg` and `ffprobe` available on the machine
- Copy `.claude/skills/kb/config.example.json` to `.claude/skills/kb/config.local.json` and fill in `dashscope_api_key`
  or set `DASHSCOPE_API_KEY`

Default input directory:
- `knowledge/inbox/video/raw/`

Command:

```bash
python3 .claude/skills/kb/scripts/video_ingest.py [path]
```

Outputs:
- `knowledge/inbox/video/transcripts/*.raw.txt`
- `knowledge/inbox/video/transcripts/*.clean.txt`
- `knowledge/inbox/video/transcripts/*.meta.json`
- `knowledge/inbox/video/logs/ingest.log`
- new knowledge entry files under `knowledge/`

Quality rules:
- Only do light transcript cleanup
- Do not invent facts
- Leave `核心观点` blank for the current agent to fill in later

### 5) `/kb compile`

Compile timeline entries into concept pages, related links, index, and Bases view.

Command:

```bash
python3 .claude/skills/kb/scripts/knowledge_ops.py compile
```

### 6) `/kb health`

Generate a health report for isolated entries, concept gaps, stale raw files, and report coverage.

Command:

```bash
python3 .claude/skills/kb/scripts/knowledge_ops.py health
```

### 7) `/kb tidy`

Normalize tags and rebuild concepts, index, health report, and Bases view.

Command:

```bash
python3 .claude/skills/kb/scripts/knowledge_ops.py tidy
```

## Troubleshooting

- If `find`, `compile`, or `health` fail to locate the repo root, set `KB_ROOT=/absolute/path/to/repo`
- If `add-video` fails, verify `dashscope` installation, API key config, and `ffmpeg` availability