원클릭으로 Manus에서 모든 스킬 실행

save-to-kb

스타0

포크0

업데이트2026년 4월 9일 02:51

Personal knowledge base manager for LLM-Brain-Bases. Four modes: (1) AUTO-SAVE — automatically called at end of significant conversations to save reusable knowledge as Cards; (2) INIT — run "save-to-kb init" on first install to create directory structure and configure KB path; (3) CHECK — run "save-to-kb check" to scan the entire knowledge base for broken links, inconsistencies, and missing data, then fix with user confirmation; (4) REPLAY — run "save-to-kb replay" to retroactively process historical sessions that were never saved. Config path: ~/.claude/skills/save-to-kb/.config

설치

Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.

Manus에서 실행

출처

verycafe

verycafe/save-to-kb

GitHub 저장소 열기 Creator 저장소 보기

다운로드

Manus에서 실행

save-to-kb

Route: Which Procedure to Run

Read the invocation context first:

Invoked with argument init → run [INIT PROCEDURE]
Invoked with argument check → run [CHECK PROCEDURE]
Invoked with argument replay → run [REPLAY PROCEDURE]
Invoked with argument save → run [AUTO-INIT CHECK] then [SAVE PROCEDURE]
Invoked with argument file <path> → run [FILE PROCEDURE] with the given path
Invoked without arguments → run [MENU]

[MENU]

Present a two-level menu using AskUserQuestion (max 4 options per question).

Level 1 — main actions:

save — 从当前对话提取知识并保存到知识库
file — 分析指定文件并提取知识（PDF / MD / txt）
check — 健康检查，扫描断链和不一致
管理知识库… — 进入二级菜单（init / replay）

If user selects "管理知识库…", show Level 2:

init — 初始化知识库或更改路径
replay — 回溯历史 session，补录遗漏的知识

Route based on final selection:

save → [AUTO-INIT CHECK] then [SAVE PROCEDURE]
file → [FILE PROCEDURE]
check → [CHECK PROCEDURE]
init → [INIT PROCEDURE]
replay → [REPLAY PROCEDURE]

[AUTO-INIT CHECK]

Before running the save procedure, verify the KB is initialized:

Check if ~/.claude/skills/save-to-kb/.config exists and contains a path
If missing or empty → run [INIT PROCEDURE] first, then continue with save

[INIT PROCEDURE]

Two scenarios: first-time setup and change path. Both follow the same steps but with different prompts and behaviors.

Step I-1: Detect Scenario

Read ~/.claude/skills/save-to-kb/.config:

File missing or empty → First-time setup. Proceed to Step I-2.

File exists with a valid path → Already initialized. Report:

Knowledge base is configured at: {current-path}

Ask: "Change to a new path? (yes/no)"

If no → stop.

If yes → this is a path change. Ask:

Migrate existing knowledge base to the new location?
- yes: copy all files (Bases/, Cards/, Wiki/, Claude.md) to new path. Old files are kept.
- no:  create a new empty knowledge base at new path. Old files untouched.

Record the user's choice as {migrate: true/false}. Proceed to Step I-2.

Step I-2: Ask for Path

Ask the user:

"Enter the full path for the knowledge base (e.g. ~/Documents/LLM-Brain-Bases or /Users/you/Obsidian/Work/LLM-Brain-Bases):"

Expand ~ to the actual absolute home directory path. Show the resolved path and ask: "Confirm: create knowledge base at {resolved-path}? (yes/no)"

If no → ask again for a new path.

Step I-3: Create Directory Structure

Create the following directories (skip any that already exist):

{KB}/
{KB}/Bases/
{KB}/Cards/
{KB}/Wiki/

Step I-3b: Migrate Files (path change + migrate: true only)

Skip this step for first-time setup or if user chose not to migrate.

Copy all contents from {old-KB}/ to {new-KB}/:

{old-KB}/Bases/ → {new-KB}/Bases/
{old-KB}/Cards/ → {new-KB}/Cards/
{old-KB}/Wiki/ → {new-KB}/Wiki/
{old-KB}/Claude.md → {new-KB}/Claude.md

Rules:

Copy, do not move. Old files remain untouched.
Do not overwrite files that already exist at the new location.
Wikilinks inside the files are relative ([[Cards/slug]]), so they require no modification.
After copying, report: Migrated {N} files to {new-KB}.

Step I-4: Write Master Index

First-time setup: Write {KB}/Claude.md only if it does not exist (never overwrite an existing index). Path change: Write {KB}/Claude.md only if it does not exist at the new location.

# LLM-Brain-Bases — Master Knowledge Index

*Auto-maintained by Claude. Last updated: {YYYY-MM-DD}.*

## How to Use This Index

Before starting any non-trivial task:
1. Check the **Scenario Quick-Lookup** table below for the task type
2. If found, read the linked Cards directly
3. If not found, identify the relevant category in **Knowledge Map** and open the Wiki file

To save new knowledge: invoke `save-to-kb` at conversation end.
To health-check the KB: invoke `save-to-kb check`.

---

## Knowledge Map

| Wiki | Cards | Focus | Key Tags |
|------|-------|-------|----------|
| [[Wiki/ai-tools]] | 0 | Claude Code, LLM tools, prompting, skills | claude, hooks, skills, llm |
| [[Wiki/workflow]] | 0 | Development process, tooling, automation | git, ci, planning |
| [[Wiki/debugging]] | 0 | Systematic diagnosis patterns | debugging, logging, tracing |
| [[Wiki/architecture]] | 0 | System design, decisions, tradeoffs | design, patterns, architecture |
| [[Wiki/knowledge-management]] | 0 | Knowledge base, Obsidian, PKM | obsidian, pkm |
| [[Wiki/frontend]] | 0 | Vue3, Nuxt, React, SSR, UI | vue3, nuxt, react, ssr |
| [[Wiki/backend]] | 0 | APIs, databases, server logic | postgres, redis, api |
| [[Wiki/infra]] | 0 | Deployment, CI/CD, cloud | docker, vercel, github-actions |
| [[Wiki/business]] | 0 | Non-technical context, decisions | client, scope, product |

---

## Scenario Quick-Lookup

| Scenario | Start Here |
|----------|-----------|
| *(empty — populated after first save)* | — |

---

## Cross-Domain Cards

*(empty — populated after first save)*

---

## Recently Added

*(empty — populated after first save)*

---

## Stats

- Total cards: 0
- Total bases (sessions): 0
- Wiki categories: 0
- Last save: —

Step I-5: Write Config File

Write the confirmed KB path (single line) to ~/.claude/skills/save-to-kb/.config:

/full/expanded/path/to/KB

Step I-6: Update Global CLAUDE.md

Read ~/.claude/CLAUDE.md. Find the  marker.

First-time setup — block does not exist: Append the following block at the end of the file:

<!-- LLM_BRAIN_BASES_BLOCK:BEGIN -->
## LLM-Brain-Bases 个人知识库

知识库路径：`{KB}`
（路径配置文件：`~/.claude/skills/save-to-kb/.config`）

### 规则 1：任务前查库

在开始以下类型的非平凡任务前，先查询知识库：
- 调试不熟悉的错误或行为
- 集成特定的库、API 或服务
- 系统设计或架构决策
- 涉及之前接触过的代码库或技术栈

操作步骤：
1. 读取 `{KB}/Claude.md`（主索引）
2. 从"场景快查"或"知识地图"定位相关 Wiki 和 Cards
3. 读取相关 Cards 后再开始工作

以下情况可跳过：纯机械操作、纯写作任务、与已有知识库完全无关的领域。

### 规则 2：对话结束自动保存

对话产出以下任何一项时，在对话末尾主动调用 `save-to-kb`：

- 调试发现了非显而易见的根因
- 发现了某 API/库/工具的文档未记录的行为
- 做出了有明确推理的架构或设计决策
- 总结出让重复任务明显更高效的工作流模式
- 验证了某种不该重蹈的失败路径

**判断标准**：刚加入项目的工程师在做类似任务前读到这张卡片会有收益吗？有则保存。

以下情况不保存：纯机械任务输出、标准教科书知识、一次性交付物、结论未明确的探索。

保存操作静默执行，无需向用户宣告（除非被问及）。
<!-- LLM_BRAIN_BASES_BLOCK:END -->

Path change — block already exists: Find the line starting with 知识库路径： inside the block and update the path value to the new {KB} path. Leave all other content unchanged.

Step I-7: Confirm

Report to user:

✓ Knowledge base initialized at: {KB}
✓ Directory structure created: Bases/ Cards/ Wiki/
✓ Master index written: Claude.md
✓ Config saved: ~/.claude/skills/save-to-kb/.config
✓ CLAUDE.md rules updated

Run `save-to-kb check` at any time to audit the knowledge base.

[REPLAY PROCEDURE]

Retroactively process historical session files that were never saved to the knowledge base.

Step R-1: Load Config

Read KB path from ~/.claude/skills/save-to-kb/.config. If missing → report "Not initialized. Run save-to-kb init first." and stop.

Step R-2: Locate Session Files

Claude Code stores session logs as JSONL files. Find the directory for the current working directory:

# Project dir = cwd with / replaced by - (e.g. /Users/tvwoo → -Users-tvwoo)
ls ~/.claude/projects/{project-dir}/*.jsonl

Run this bash command to list all session files with their dates:

for f in ~/.claude/projects/{project-dir}/*.jsonl; do
  ts=$(grep -m1 '"timestamp"' "$f" | grep -o '"timestamp":"[^"]*"' | cut -d'"' -f4)
  echo "$ts $f"
done | sort

Step R-3: Identify Unprocessed Sessions

Read all files in $KB/Bases/ and extract the session-id: field from each frontmatter.

Build a set of already-processed session IDs. A session is already processed if its JSONL filename (without .jsonl) matches any session-id in Bases/.

Sessions with no matching ID are candidates, regardless of date.

Report to user:

Found {N} session files. {M} already have Base records.
{K} unprocessed sessions:
  [1] 2026-04-07  abc123.jsonl  (~42 messages)
  [2] 2026-04-06  def456.jsonl  (~18 messages)
  ...
Process all? Or enter numbers to select (e.g. "1 3"):

Step R-4: Extract Conversation Content

For each selected session file, parse the JSONL to reconstruct the conversation:

# Extract user and assistant messages in order
jq -r 'select(.type == "user" or .type == "assistant") 
  | "\(.type | ascii_upcase): \(.message.content // "" | if type == "array" then .[0].text else . end)"' \
  {session-file}.jsonl

Each message should be extracted with its role (user/assistant) and content text. Ignore metadata entries (permission-mode, file-history-snapshot, tool results, etc.).

Step R-5: Process Each Session

For each selected session, treat the extracted conversation as if it were the current session context and run the full [SAVE PROCEDURE] (Steps S-1 through S-6).

Key differences from normal save:

The Base date: should use the session's actual date (from timestamp), not today
The Base slug: should include the session date
Check for duplicates against all existing Cards (not just today's)

Step R-6: Report

After processing all selected sessions:

Replay complete.
  Sessions processed: {K}
  Cards created: {N}
  Cards updated: {M}
  Bases written: {K}

[CHECK PROCEDURE]

Audit the entire knowledge base for broken links, inconsistencies, and data quality issues. Present findings and fix with user confirmation.

Step C-1: Load Config

Read ~/.claude/skills/save-to-kb/.config to get KB path. If missing → report "Knowledge base not initialized. Run save-to-kb init first." and stop.

Step C-2: Scan Cards/

List all .md files in {KB}/Cards/. For each card, check:

Check	Issue Type
Required frontmatter fields present: `title`, `slug`, `category`, `tags`, `scenario`, `created`, `updated`, `confidence`	`MISSING_FIELD`
`slug` matches the filename (without `.md`)	`SLUG_MISMATCH`
`category` value corresponds to an existing `Wiki/{category}.md` file	`BROKEN_CATEGORY`
Each entry in `related:` has a matching `Cards/{slug}.md` file	`BROKEN_RELATED`
Each entry in `sources:` has a matching `Bases/` file	`BROKEN_SOURCE`
Required body sections present: `## What`, `## Why It Matters`, `## How`	`MISSING_SECTION`
`confidence` value is one of: high, medium, low	`INVALID_CONFIDENCE`

Step C-3: Scan Bases/

List all .md files in {KB}/Bases/. For each base, check:

Check	Issue Type
Required frontmatter fields: `date`, `session-title`, `slug`	`MISSING_FIELD`
Each entry in `cards-created` and `cards-updated` has matching `Cards/` file	`BROKEN_CARD_REF`

Step C-4: Scan Wiki/

List all .md files in {KB}/Wiki/. For each Wiki file, check:

Check	Issue Type
All `[[Cards/slug]]` wikilinks have matching files in `Cards/`	`BROKEN_WIKILINK`
All `[[Wiki/category]]` wikilinks have matching files in `Wiki/`	`BROKEN_WIKILINK`
`card-count` in frontmatter matches the actual number of `[[Cards/` entries in the file	`COUNT_MISMATCH`

Step C-5: Scan Claude.md

Read {KB}/Claude.md. Check:

Check	Issue Type
All `[[Cards/slug]]` references have matching files in `Cards/`	`BROKEN_WIKILINK`
All `[[Wiki/category]]` references have matching files in `Wiki/`	`BROKEN_WIKILINK`
Stats `Total cards` matches actual file count in `Cards/`	`STATS_MISMATCH`
Stats `Total bases` matches actual file count in `Bases/`	`STATS_MISMATCH`

Step C-6: Report Issues

Present a structured report:

Health Check Report — {YYYY-MM-DD}
====================================
Cards/ ({N} files scanned)
  ✓ card-a.md
  ⚠ [#1] card-b.md — BROKEN_RELATED: slug 'missing-card' not found in Cards/
  ⚠ [#2] card-c.md — MISSING_SECTION: '## Why It Matters' not found

Bases/ ({N} files scanned)
  ✓ 2026-04-09-session.md
  ⚠ [#3] 2026-04-08-old.md — BROKEN_CARD_REF: 'Cards/deleted-card' not found

Wiki/ ({N} files scanned)
  ✓ ai-tools.md
  ⚠ [#4] frontend.md — COUNT_MISMATCH: card-count=5 but 3 actual entries found

Claude.md
  ⚠ [#5] Stats: Total cards=10, actual=8

Found 5 issues.
Fix all? Enter "yes" to fix all, or "skip 2,4" to fix all except those numbered.

If no issues found:

✓ Health check passed — {N} cards, {N} bases, {N} wiki files. No issues found.

Step C-7: Apply Fixes

If user confirms, apply the following repair actions per issue type:

Issue Type	Repair Action
`BROKEN_RELATED`	Remove the broken slug from `related:` list
`BROKEN_SOURCE`	Remove the broken entry from `sources:` list
`BROKEN_CARD_REF`	Remove the broken entry from `cards-created`/`cards-updated`
`BROKEN_WIKILINK`	Remove the broken `[[link]]` entry from the file
`BROKEN_CATEGORY`	Ask user: create the missing Wiki file, or reassign card to existing category?
`SLUG_MISMATCH`	Update `slug:` in frontmatter to match the filename
`MISSING_FIELD`	Report field as missing, ask user what value to set, then write it
`MISSING_SECTION`	Add the missing section with placeholder text: `(to be filled)`
`INVALID_CONFIDENCE`	Set `confidence: medium` as default
`COUNT_MISMATCH`	Recount actual `[[Cards/` entries and update `card-count`
`STATS_MISMATCH`	Recount actual files and update Stats numbers in Claude.md

After fixes, report:

Fixed 4 of 5 issues. Skipped: #2 (manual action required).
Run `save-to-kb check` again to verify.

[SAVE PROCEDURE]

Save reusable knowledge from the current conversation into LLM-Brain-Bases.

Step S-0: Load Config

Read KB path from ~/.claude/skills/save-to-kb/.config.

Step S-1: Extract Knowledge Points

Review the full conversation. A card must be non-obvious and transferable — meaning someone encountering a similar situation in the future would genuinely benefit from reading it.

Knowledge falls into these saveable categories:

Technical

A bug's non-obvious root cause and fix
Undocumented or surprising API / library behavior
Integration constraints between two systems or tools
Non-obvious performance characteristics

Architecture & Design

A design decision with clear reasoning that generalizes beyond this project
A tradeoff conclusion worth remembering (why X was chosen over Y)

Product & Requirements

A non-obvious insight about user behavior or intent revealed during development
A requirement that turned out to mean something different than assumed — and why
A product decision pattern that resolved ambiguity in a generalizable way

AI & Vibe Coding

Non-obvious Claude / LLM behavior (prompt patterns, context limits, model quirks)
Effective Skill, Hook, or tool configuration patterns for Claude Code
Vibe coding workflow patterns that meaningfully improve AI-assisted development
Lessons from AI agent coordination (task splitting, context management, handoff)

Hard rejections — do NOT save:

Generic process templates or documentation structures
Decisions or bugs entirely specific to one project with zero generalizable signal
Mainstream best practices any competent engineer already knows
Anything that belongs in CLAUDE.md rather than a reusable card
Unresolved explorations with no confirmed conclusion

Judgment test: "Would someone hitting a similar situation in the future — whether a bug, a decision, a product question, or an AI interaction — be better equipped after reading this card?" If yes, save it.

Step S-2: Check for Duplicates

Before writing any card:

Read $KB/Claude.md — scan Knowledge Map and Scenario Quick-Lookup
Check the relevant Wiki file for existing entries
Search $KB/Cards/ for files with similar slugs or title keywords

If a close match exists: update the existing card (add content, update updated: date, add new Base to sources:). Never create two cards for the same concept.

Step S-3: Write Cards

For each knowledge point, write $KB/Cards/{slug}.md.

Slug rules: lowercase, hyphens only, no special chars, ≤60 chars.

---
title: "{Title}"
slug: {slug}
category: {category}
tags: [{tag1}, {tag2}]
scenario: [{scenario1}, {scenario2}]
created: {YYYY-MM-DD}
updated: {YYYY-MM-DD}
confidence: {high|medium|low}
related:
  - {slug-of-related-card}
sources:
  - "[[Bases/{YYYY-MM-DD}-{session-slug}]]"
---

## What
One sentence. What is this knowledge point. No hedging.

## Why It Matters
When does this matter. What breaks without it.

## How
Concrete procedure, pattern, command, or code.

## Gotchas
Edge cases, common mistakes. Omit section if none.

## Connections
Prose explaining how this relates to other concepts. Use [[wikilinks]] inline.

## References
- [[Bases/{YYYY-MM-DD}-{session-slug}]] — {one-line session description}

Confidence: high = confirmed; medium = partially tested; low = speculative.

Step S-4: Write the Base

First, get the current session ID by running:

ls -t ~/.claude/projects/$(echo $PWD | sed 's|/|-|g' | sed 's|^-||')/*.jsonl 2>/dev/null | head -1 | xargs basename | sed 's/.jsonl//'

If this fails or returns empty, use "unknown" as the session-id.

Write one Base file at $KB/Bases/{YYYY-MM-DD}-{session-slug}.md. Append-only — never edit after creation.

---
date: {YYYY-MM-DD}
session-id: {session-id-from-jsonl-filename}
session-title: "{Brief title}"
slug: {YYYY-MM-DD}-{session-slug}
project: "{Project name, or 'General'}"
tech: [{tech1}]
scenario: [{scenario1}]
cards-created:
  - "[[Cards/{slug}]]"
cards-updated:
  - "[[Cards/{slug}]]"
---

## Session Summary
2–4 sentences.

## Key Discoveries
- {Discovery} — why it matters

## Cards Written
- [[Cards/{slug}]] — description

Step S-5: Update Wiki Files

For each card's category, update $KB/Wiki/{category}.md:

Add card under the correct tech-stack and scenario sections
Add to Cross-Wiki Connections table if it bridges categories
Increment card-count in frontmatter
Append to Recent Additions (keep last 20)

If the Wiki file doesn't exist, create it using references/wiki-template.md.

Step S-6: Update Master Index

Edit $KB/Claude.md:

Update Cards count in Knowledge Map for affected categories
Add scenario entry-points to Scenario Quick-Lookup
Add cross-domain cards to Cross-Domain Cards
Prepend to Recently Added (keep last 10)
Update Stats (total cards, bases, last save date)

What NOT to Save

Task-specific outputs (delivered code, one-time reports)
Preferences already in CLAUDE.md
Pure reference facts (version numbers, general documentation)
Incomplete explorations with no resolved conclusions

[FILE PROCEDURE]

Extract reusable knowledge cards from a file (PDF, Markdown, txt, or any readable format).

Step F-1: Load Config

Read KB path from ~/.claude/skills/save-to-kb/.config. If missing → report "Not initialized. Run save-to-kb init first." and stop.

Step F-2: Get File Path

If invoked from menu selection: ask the user with AskUserQuestion:

"请输入文件路径（支持 PDF / Markdown / txt）："

If invoked with argument (save-to-kb file <path>): use the provided path directly.

Expand ~ to the absolute home directory. Verify the file exists before proceeding. If file not found → report the resolved path and stop.

Step F-2b: Copy File to Knowledge Base

Copy the source file into {KB}/Sources/ to preserve a local reference:

mkdir -p "{KB}/Sources"
cp "{source-path}" "{KB}/Sources/{filename}"

If the file already exists at the destination, skip copying (do not overwrite). Report: Source file copied to: {KB}/Sources/{filename}

Step F-3: Read File

Use the Read tool to read the file.

For PDF: read all pages. If the PDF has more than 20 pages, read in batches of 20 pages.
For text/markdown: read the full file.

Step F-4: Extract Knowledge Points

Analyze the file content. Apply the same filter as [SAVE PROCEDURE] Step S-1 — same categories (Technical, Architecture & Design, Product & Requirements, AI & Vibe Coding), same hard rejections, same judgment test.

Before extracting, report a summary to the user:

File: {filename}
Pages/size: {N} pages / {size}
Candidate knowledge areas identified:
  - {area 1}
  - {area 2}
  ...
Proceed to extract cards? (yes/no)

Step F-5: Check for Duplicates

Same as [SAVE PROCEDURE] Step S-2 — check Claude.md and existing Cards before writing.

Step F-6: Write Cards

Same format as [SAVE PROCEDURE] Step S-3.

In the sources: field, reference the Base written in Step F-7 (use the slug you plan to write).

Step F-7: Write the Base

Write one Base file at $KB/Bases/{YYYY-MM-DD}-{file-slug}.md.

Use session-id: file:{filename} to distinguish file-sourced bases from session-sourced bases. Reference the local copy (Sources/{filename}) as the source, not the original path.

---
date: {YYYY-MM-DD}
session-id: "file:{filename}"
session-title: "{Brief description of file content}"
slug: {YYYY-MM-DD}-{file-slug}
project: "General"
tech: [{tech1}]
scenario: [{scenario1}]
cards-created:
  - "[[Cards/{slug}]]"
cards-updated: []
---

## Source

File: `[[Sources/{filename}]]`
Original path: `{original-source-path}`
{2–4 sentences describing what the file covers and why it was imported.}

## Key Discoveries
- {Discovery} — why it matters

## Cards Written
- [[Cards/{slug}]] — description

Step F-8: Update Wiki and Master Index

Same as [SAVE PROCEDURE] Steps S-5 and S-6.

Step F-9: Report

File analysis complete.
  Source: {filename}
  Cards created: {N}
  Cards updated: {M}
  Base written: {slug}

name

save-to-kb

description

save-to-kb

Route: Which Procedure to Run

Read the invocation context first:

Invoked with argument init → run [INIT PROCEDURE]
Invoked with argument check → run [CHECK PROCEDURE]
Invoked with argument replay → run [REPLAY PROCEDURE]
Invoked with argument save → run [AUTO-INIT CHECK] then [SAVE PROCEDURE]
Invoked with argument file <path> → run [FILE PROCEDURE] with the given path
Invoked without arguments → run [MENU]

[MENU]

Present a two-level menu using AskUserQuestion (max 4 options per question).

Level 1 — main actions:

save — 从当前对话提取知识并保存到知识库
file — 分析指定文件并提取知识（PDF / MD / txt）
check — 健康检查，扫描断链和不一致
管理知识库… — 进入二级菜单（init / replay）

If user selects "管理知识库…", show Level 2:

init — 初始化知识库或更改路径
replay — 回溯历史 session，补录遗漏的知识

Route based on final selection:

save → [AUTO-INIT CHECK] then [SAVE PROCEDURE]
file → [FILE PROCEDURE]
check → [CHECK PROCEDURE]
init → [INIT PROCEDURE]
replay → [REPLAY PROCEDURE]

[AUTO-INIT CHECK]

Before running the save procedure, verify the KB is initialized:

Check if ~/.claude/skills/save-to-kb/.config exists and contains a path
If missing or empty → run [INIT PROCEDURE] first, then continue with save

[INIT PROCEDURE]

Two scenarios: first-time setup and change path. Both follow the same steps but with different prompts and behaviors.

Step I-1: Detect Scenario

Read ~/.claude/skills/save-to-kb/.config:

File missing or empty → First-time setup. Proceed to Step I-2.

File exists with a valid path → Already initialized. Report:

Knowledge base is configured at: {current-path}

Ask: "Change to a new path? (yes/no)"

If no → stop.

If yes → this is a path change. Ask:

Migrate existing knowledge base to the new location?
- yes: copy all files (Bases/, Cards/, Wiki/, Claude.md) to new path. Old files are kept.
- no:  create a new empty knowledge base at new path. Old files untouched.

Record the user's choice as {migrate: true/false}. Proceed to Step I-2.

Step I-2: Ask for Path

Ask the user:

"Enter the full path for the knowledge base (e.g. ~/Documents/LLM-Brain-Bases or /Users/you/Obsidian/Work/LLM-Brain-Bases):"

Expand ~ to the actual absolute home directory path. Show the resolved path and ask: "Confirm: create knowledge base at {resolved-path}? (yes/no)"

If no → ask again for a new path.

Step I-3: Create Directory Structure

Create the following directories (skip any that already exist):

{KB}/
{KB}/Bases/
{KB}/Cards/
{KB}/Wiki/

Step I-3b: Migrate Files (path change + migrate: true only)

Skip this step for first-time setup or if user chose not to migrate.

Copy all contents from {old-KB}/ to {new-KB}/:

{old-KB}/Bases/ → {new-KB}/Bases/
{old-KB}/Cards/ → {new-KB}/Cards/
{old-KB}/Wiki/ → {new-KB}/Wiki/
{old-KB}/Claude.md → {new-KB}/Claude.md

Rules:

Copy, do not move. Old files remain untouched.
Do not overwrite files that already exist at the new location.
Wikilinks inside the files are relative ([[Cards/slug]]), so they require no modification.
After copying, report: Migrated {N} files to {new-KB}.

Step I-4: Write Master Index

First-time setup: Write {KB}/Claude.md only if it does not exist (never overwrite an existing index). Path change: Write {KB}/Claude.md only if it does not exist at the new location.

# LLM-Brain-Bases — Master Knowledge Index

*Auto-maintained by Claude. Last updated: {YYYY-MM-DD}.*

## How to Use This Index

Before starting any non-trivial task:
1. Check the **Scenario Quick-Lookup** table below for the task type
2. If found, read the linked Cards directly
3. If not found, identify the relevant category in **Knowledge Map** and open the Wiki file

To save new knowledge: invoke `save-to-kb` at conversation end.
To health-check the KB: invoke `save-to-kb check`.

---

## Knowledge Map

| Wiki | Cards | Focus | Key Tags |
|------|-------|-------|----------|
| [[Wiki/ai-tools]] | 0 | Claude Code, LLM tools, prompting, skills | claude, hooks, skills, llm |
| [[Wiki/workflow]] | 0 | Development process, tooling, automation | git, ci, planning |
| [[Wiki/debugging]] | 0 | Systematic diagnosis patterns | debugging, logging, tracing |
| [[Wiki/architecture]] | 0 | System design, decisions, tradeoffs | design, patterns, architecture |
| [[Wiki/knowledge-management]] | 0 | Knowledge base, Obsidian, PKM | obsidian, pkm |
| [[Wiki/frontend]] | 0 | Vue3, Nuxt, React, SSR, UI | vue3, nuxt, react, ssr |
| [[Wiki/backend]] | 0 | APIs, databases, server logic | postgres, redis, api |
| [[Wiki/infra]] | 0 | Deployment, CI/CD, cloud | docker, vercel, github-actions |
| [[Wiki/business]] | 0 | Non-technical context, decisions | client, scope, product |

---

## Scenario Quick-Lookup

| Scenario | Start Here |
|----------|-----------|
| *(empty — populated after first save)* | — |

---

## Cross-Domain Cards

*(empty — populated after first save)*

---

## Recently Added

*(empty — populated after first save)*

---

## Stats

- Total cards: 0
- Total bases (sessions): 0
- Wiki categories: 0
- Last save: —

Step I-5: Write Config File

Write the confirmed KB path (single line) to ~/.claude/skills/save-to-kb/.config:

/full/expanded/path/to/KB

Step I-6: Update Global CLAUDE.md

Read ~/.claude/CLAUDE.md. Find the  marker.

First-time setup — block does not exist: Append the following block at the end of the file:

<!-- LLM_BRAIN_BASES_BLOCK:BEGIN -->
## LLM-Brain-Bases 个人知识库

知识库路径：`{KB}`
（路径配置文件：`~/.claude/skills/save-to-kb/.config`）

### 规则 1：任务前查库

在开始以下类型的非平凡任务前，先查询知识库：
- 调试不熟悉的错误或行为
- 集成特定的库、API 或服务
- 系统设计或架构决策
- 涉及之前接触过的代码库或技术栈

操作步骤：
1. 读取 `{KB}/Claude.md`（主索引）
2. 从"场景快查"或"知识地图"定位相关 Wiki 和 Cards
3. 读取相关 Cards 后再开始工作

以下情况可跳过：纯机械操作、纯写作任务、与已有知识库完全无关的领域。

### 规则 2：对话结束自动保存

对话产出以下任何一项时，在对话末尾主动调用 `save-to-kb`：

- 调试发现了非显而易见的根因
- 发现了某 API/库/工具的文档未记录的行为
- 做出了有明确推理的架构或设计决策
- 总结出让重复任务明显更高效的工作流模式
- 验证了某种不该重蹈的失败路径

**判断标准**：刚加入项目的工程师在做类似任务前读到这张卡片会有收益吗？有则保存。

以下情况不保存：纯机械任务输出、标准教科书知识、一次性交付物、结论未明确的探索。

保存操作静默执行，无需向用户宣告（除非被问及）。
<!-- LLM_BRAIN_BASES_BLOCK:END -->

Path change — block already exists: Find the line starting with 知识库路径： inside the block and update the path value to the new {KB} path. Leave all other content unchanged.

Step I-7: Confirm

Report to user:

✓ Knowledge base initialized at: {KB}
✓ Directory structure created: Bases/ Cards/ Wiki/
✓ Master index written: Claude.md
✓ Config saved: ~/.claude/skills/save-to-kb/.config
✓ CLAUDE.md rules updated

Run `save-to-kb check` at any time to audit the knowledge base.

[REPLAY PROCEDURE]

Retroactively process historical session files that were never saved to the knowledge base.

Step R-1: Load Config

Read KB path from ~/.claude/skills/save-to-kb/.config. If missing → report "Not initialized. Run save-to-kb init first." and stop.

Step R-2: Locate Session Files

Claude Code stores session logs as JSONL files. Find the directory for the current working directory:

# Project dir = cwd with / replaced by - (e.g. /Users/tvwoo → -Users-tvwoo)
ls ~/.claude/projects/{project-dir}/*.jsonl

Run this bash command to list all session files with their dates:

for f in ~/.claude/projects/{project-dir}/*.jsonl; do
  ts=$(grep -m1 '"timestamp"' "$f" | grep -o '"timestamp":"[^"]*"' | cut -d'"' -f4)
  echo "$ts $f"
done | sort

Step R-3: Identify Unprocessed Sessions

Read all files in $KB/Bases/ and extract the session-id: field from each frontmatter.

Build a set of already-processed session IDs. A session is already processed if its JSONL filename (without .jsonl) matches any session-id in Bases/.

Sessions with no matching ID are candidates, regardless of date.

Report to user:

Found {N} session files. {M} already have Base records.
{K} unprocessed sessions:
  [1] 2026-04-07  abc123.jsonl  (~42 messages)
  [2] 2026-04-06  def456.jsonl  (~18 messages)
  ...
Process all? Or enter numbers to select (e.g. "1 3"):

Step R-4: Extract Conversation Content

For each selected session file, parse the JSONL to reconstruct the conversation:

# Extract user and assistant messages in order
jq -r 'select(.type == "user" or .type == "assistant") 
  | "\(.type | ascii_upcase): \(.message.content // "" | if type == "array" then .[0].text else . end)"' \
  {session-file}.jsonl

Each message should be extracted with its role (user/assistant) and content text. Ignore metadata entries (permission-mode, file-history-snapshot, tool results, etc.).

Step R-5: Process Each Session

For each selected session, treat the extracted conversation as if it were the current session context and run the full [SAVE PROCEDURE] (Steps S-1 through S-6).

Key differences from normal save:

The Base date: should use the session's actual date (from timestamp), not today
The Base slug: should include the session date
Check for duplicates against all existing Cards (not just today's)

Step R-6: Report

After processing all selected sessions:

Replay complete.
  Sessions processed: {K}
  Cards created: {N}
  Cards updated: {M}
  Bases written: {K}

[CHECK PROCEDURE]

Audit the entire knowledge base for broken links, inconsistencies, and data quality issues. Present findings and fix with user confirmation.

Step C-1: Load Config

Read ~/.claude/skills/save-to-kb/.config to get KB path. If missing → report "Knowledge base not initialized. Run save-to-kb init first." and stop.

Step C-2: Scan Cards/

List all .md files in {KB}/Cards/. For each card, check:

Check	Issue Type
Required frontmatter fields present: `title`, `slug`, `category`, `tags`, `scenario`, `created`, `updated`, `confidence`	`MISSING_FIELD`
`slug` matches the filename (without `.md`)	`SLUG_MISMATCH`
`category` value corresponds to an existing `Wiki/{category}.md` file	`BROKEN_CATEGORY`
Each entry in `related:` has a matching `Cards/{slug}.md` file	`BROKEN_RELATED`
Each entry in `sources:` has a matching `Bases/` file	`BROKEN_SOURCE`
Required body sections present: `## What`, `## Why It Matters`, `## How`	`MISSING_SECTION`
`confidence` value is one of: high, medium, low	`INVALID_CONFIDENCE`

Step C-3: Scan Bases/

List all .md files in {KB}/Bases/. For each base, check:

Check	Issue Type
Required frontmatter fields: `date`, `session-title`, `slug`	`MISSING_FIELD`
Each entry in `cards-created` and `cards-updated` has matching `Cards/` file	`BROKEN_CARD_REF`

Step C-4: Scan Wiki/

List all .md files in {KB}/Wiki/. For each Wiki file, check:

Check	Issue Type
All `[[Cards/slug]]` wikilinks have matching files in `Cards/`	`BROKEN_WIKILINK`
All `[[Wiki/category]]` wikilinks have matching files in `Wiki/`	`BROKEN_WIKILINK`
`card-count` in frontmatter matches the actual number of `[[Cards/` entries in the file	`COUNT_MISMATCH`

Step C-5: Scan Claude.md

Read {KB}/Claude.md. Check:

Check	Issue Type
All `[[Cards/slug]]` references have matching files in `Cards/`	`BROKEN_WIKILINK`
All `[[Wiki/category]]` references have matching files in `Wiki/`	`BROKEN_WIKILINK`
Stats `Total cards` matches actual file count in `Cards/`	`STATS_MISMATCH`
Stats `Total bases` matches actual file count in `Bases/`	`STATS_MISMATCH`

Step C-6: Report Issues

Present a structured report:

Health Check Report — {YYYY-MM-DD}
====================================
Cards/ ({N} files scanned)
  ✓ card-a.md
  ⚠ [#1] card-b.md — BROKEN_RELATED: slug 'missing-card' not found in Cards/
  ⚠ [#2] card-c.md — MISSING_SECTION: '## Why It Matters' not found

Bases/ ({N} files scanned)
  ✓ 2026-04-09-session.md
  ⚠ [#3] 2026-04-08-old.md — BROKEN_CARD_REF: 'Cards/deleted-card' not found

Wiki/ ({N} files scanned)
  ✓ ai-tools.md
  ⚠ [#4] frontend.md — COUNT_MISMATCH: card-count=5 but 3 actual entries found

Claude.md
  ⚠ [#5] Stats: Total cards=10, actual=8

Found 5 issues.
Fix all? Enter "yes" to fix all, or "skip 2,4" to fix all except those numbered.

If no issues found:

✓ Health check passed — {N} cards, {N} bases, {N} wiki files. No issues found.

Step C-7: Apply Fixes

If user confirms, apply the following repair actions per issue type:

Issue Type	Repair Action
`BROKEN_RELATED`	Remove the broken slug from `related:` list
`BROKEN_SOURCE`	Remove the broken entry from `sources:` list
`BROKEN_CARD_REF`	Remove the broken entry from `cards-created`/`cards-updated`
`BROKEN_WIKILINK`	Remove the broken `[[link]]` entry from the file
`BROKEN_CATEGORY`	Ask user: create the missing Wiki file, or reassign card to existing category?
`SLUG_MISMATCH`	Update `slug:` in frontmatter to match the filename
`MISSING_FIELD`	Report field as missing, ask user what value to set, then write it
`MISSING_SECTION`	Add the missing section with placeholder text: `(to be filled)`
`INVALID_CONFIDENCE`	Set `confidence: medium` as default
`COUNT_MISMATCH`	Recount actual `[[Cards/` entries and update `card-count`
`STATS_MISMATCH`	Recount actual files and update Stats numbers in Claude.md

After fixes, report:

Fixed 4 of 5 issues. Skipped: #2 (manual action required).
Run `save-to-kb check` again to verify.

[SAVE PROCEDURE]

Save reusable knowledge from the current conversation into LLM-Brain-Bases.

Step S-0: Load Config

Read KB path from ~/.claude/skills/save-to-kb/.config.

Step S-1: Extract Knowledge Points

Review the full conversation. A card must be non-obvious and transferable — meaning someone encountering a similar situation in the future would genuinely benefit from reading it.

Knowledge falls into these saveable categories:

Technical

A bug's non-obvious root cause and fix
Undocumented or surprising API / library behavior
Integration constraints between two systems or tools
Non-obvious performance characteristics

Architecture & Design

A design decision with clear reasoning that generalizes beyond this project
A tradeoff conclusion worth remembering (why X was chosen over Y)

Product & Requirements

A non-obvious insight about user behavior or intent revealed during development
A requirement that turned out to mean something different than assumed — and why
A product decision pattern that resolved ambiguity in a generalizable way

AI & Vibe Coding

Non-obvious Claude / LLM behavior (prompt patterns, context limits, model quirks)
Effective Skill, Hook, or tool configuration patterns for Claude Code
Vibe coding workflow patterns that meaningfully improve AI-assisted development
Lessons from AI agent coordination (task splitting, context management, handoff)

Hard rejections — do NOT save:

Generic process templates or documentation structures
Decisions or bugs entirely specific to one project with zero generalizable signal
Mainstream best practices any competent engineer already knows
Anything that belongs in CLAUDE.md rather than a reusable card
Unresolved explorations with no confirmed conclusion

Step S-2: Check for Duplicates

Before writing any card:

Read $KB/Claude.md — scan Knowledge Map and Scenario Quick-Lookup
Check the relevant Wiki file for existing entries
Search $KB/Cards/ for files with similar slugs or title keywords

If a close match exists: update the existing card (add content, update updated: date, add new Base to sources:). Never create two cards for the same concept.

Step S-3: Write Cards

For each knowledge point, write $KB/Cards/{slug}.md.

Slug rules: lowercase, hyphens only, no special chars, ≤60 chars.

---
title: "{Title}"
slug: {slug}
category: {category}
tags: [{tag1}, {tag2}]
scenario: [{scenario1}, {scenario2}]
created: {YYYY-MM-DD}
updated: {YYYY-MM-DD}
confidence: {high|medium|low}
related:
  - {slug-of-related-card}
sources:
  - "[[Bases/{YYYY-MM-DD}-{session-slug}]]"
---

## What
One sentence. What is this knowledge point. No hedging.

## Why It Matters
When does this matter. What breaks without it.

## How
Concrete procedure, pattern, command, or code.

## Gotchas
Edge cases, common mistakes. Omit section if none.

## Connections
Prose explaining how this relates to other concepts. Use [[wikilinks]] inline.

## References
- [[Bases/{YYYY-MM-DD}-{session-slug}]] — {one-line session description}

Confidence: high = confirmed; medium = partially tested; low = speculative.

Step S-4: Write the Base

First, get the current session ID by running:

ls -t ~/.claude/projects/$(echo $PWD | sed 's|/|-|g' | sed 's|^-||')/*.jsonl 2>/dev/null | head -1 | xargs basename | sed 's/.jsonl//'

If this fails or returns empty, use "unknown" as the session-id.

Write one Base file at $KB/Bases/{YYYY-MM-DD}-{session-slug}.md. Append-only — never edit after creation.

---
date: {YYYY-MM-DD}
session-id: {session-id-from-jsonl-filename}
session-title: "{Brief title}"
slug: {YYYY-MM-DD}-{session-slug}
project: "{Project name, or 'General'}"
tech: [{tech1}]
scenario: [{scenario1}]
cards-created:
  - "[[Cards/{slug}]]"
cards-updated:
  - "[[Cards/{slug}]]"
---

## Session Summary
2–4 sentences.

## Key Discoveries
- {Discovery} — why it matters

## Cards Written
- [[Cards/{slug}]] — description

Step S-5: Update Wiki Files

For each card's category, update $KB/Wiki/{category}.md:

Add card under the correct tech-stack and scenario sections
Add to Cross-Wiki Connections table if it bridges categories
Increment card-count in frontmatter
Append to Recent Additions (keep last 20)

If the Wiki file doesn't exist, create it using references/wiki-template.md.

Step S-6: Update Master Index

Edit $KB/Claude.md:

Update Cards count in Knowledge Map for affected categories
Add scenario entry-points to Scenario Quick-Lookup
Add cross-domain cards to Cross-Domain Cards
Prepend to Recently Added (keep last 10)
Update Stats (total cards, bases, last save date)

What NOT to Save

Task-specific outputs (delivered code, one-time reports)
Preferences already in CLAUDE.md
Pure reference facts (version numbers, general documentation)
Incomplete explorations with no resolved conclusions

[FILE PROCEDURE]

Extract reusable knowledge cards from a file (PDF, Markdown, txt, or any readable format).

Step F-1: Load Config

Read KB path from ~/.claude/skills/save-to-kb/.config. If missing → report "Not initialized. Run save-to-kb init first." and stop.

Step F-2: Get File Path

If invoked from menu selection: ask the user with AskUserQuestion:

"请输入文件路径（支持 PDF / Markdown / txt）："

If invoked with argument (save-to-kb file <path>): use the provided path directly.

Expand ~ to the absolute home directory. Verify the file exists before proceeding. If file not found → report the resolved path and stop.

Step F-2b: Copy File to Knowledge Base

Copy the source file into {KB}/Sources/ to preserve a local reference:

mkdir -p "{KB}/Sources"
cp "{source-path}" "{KB}/Sources/{filename}"

If the file already exists at the destination, skip copying (do not overwrite). Report: Source file copied to: {KB}/Sources/{filename}

Step F-3: Read File

Use the Read tool to read the file.

For PDF: read all pages. If the PDF has more than 20 pages, read in batches of 20 pages.
For text/markdown: read the full file.

Step F-4: Extract Knowledge Points

Before extracting, report a summary to the user:

File: {filename}
Pages/size: {N} pages / {size}
Candidate knowledge areas identified:
  - {area 1}
  - {area 2}
  ...
Proceed to extract cards? (yes/no)

Step F-5: Check for Duplicates

Same as [SAVE PROCEDURE] Step S-2 — check Claude.md and existing Cards before writing.

Step F-6: Write Cards

Same format as [SAVE PROCEDURE] Step S-3.

In the sources: field, reference the Base written in Step F-7 (use the slug you plan to write).

Step F-7: Write the Base

Write one Base file at $KB/Bases/{YYYY-MM-DD}-{file-slug}.md.

Use session-id: file:{filename} to distinguish file-sourced bases from session-sourced bases. Reference the local copy (Sources/{filename}) as the source, not the original path.

---
date: {YYYY-MM-DD}
session-id: "file:{filename}"
session-title: "{Brief description of file content}"
slug: {YYYY-MM-DD}-{file-slug}
project: "General"
tech: [{tech1}]
scenario: [{scenario1}]
cards-created:
  - "[[Cards/{slug}]]"
cards-updated: []
---

## Source

File: `[[Sources/{filename}]]`
Original path: `{original-source-path}`
{2–4 sentences describing what the file covers and why it was imported.}

## Key Discoveries
- {Discovery} — why it matters

## Cards Written
- [[Cards/{slug}]] — description

Step F-8: Update Wiki and Master Index

Same as [SAVE PROCEDURE] Steps S-5 and S-6.

Step F-9: Report

File analysis complete.
  Source: {filename}
  Cards created: {N}
  Cards updated: {M}
  Base written: {slug}