From kb-skill
Query and write to the personal Obsidian-backed knowledge base via the obsidian-kb MCP server (kb_lookup, kb_search, kb_read, kb_create, kb_update_frontmatter, kb_list_by_tag, kb_reindex_cache, kb_log_append, kb_index_rebuild). Use this skill when the user explicitly says "查知識庫", "記到知識庫", "kb lookup", "kb search", "kb create", "Obsidian vault", "knowledge base", or invokes the /kb slash command. The KB is a cross-AP store: per-project context is filtered by tags derived from cwd.
How this skill is triggered — by the user, by Claude, or both
Slash command
/kb-skill:kbThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill drives the `obsidian-kb` MCP server, which fronts an Obsidian vault used as a long-term, cross-AP knowledge store. All reads/writes go through MCP tools — never edit vault files directly.
This skill drives the obsidian-kb MCP server, which fronts an Obsidian vault used as a long-term, cross-AP knowledge store. All reads/writes go through MCP tools — never edit vault files directly.
Trigger ONLY on direct signals:
/kb slash commandkb_* tool (e.g. "用 kb_lookup 查...")Do NOT trigger on vague signals like generic "查一下" or "記下來" — those are for the host conversation to decide, not this skill.
| Tool | Purpose |
|---|---|
kb_lookup(query) | Try cache trigger match. Returns full note body on hit, {hit:false} on miss. Always call first. |
kb_search(query, tags?, category?, limit?) | Full-text search across vault. Filter by tags/category to scope to current AP. |
kb_read(relPath) | Read full note by vault-relative path. |
kb_create(title, body, hintTags?, cache?, triggers?, priority?, status?) | Create new note. Runs rule→LLM classifier, writes to correct folder, fills frontmatter. |
kb_update_frontmatter(relPath, patch) | Patch tags / cache / triggers / status. |
kb_list_by_tag(tag, limit?) | List all notes carrying a tag. |
kb_reindex_cache() | Rebuild the trigger index (after editing notes in Obsidian directly). |
kb_log_append(kind, title, detail?) | Append one line to _system/log.md. kind = ingest / query / lint / note. |
kb_index_rebuild() | Regenerate _system/index.md by scanning all notes. |
The vault is shared across multiple apps/projects. Scope reads to the current project by deriving an AP tag from the working directory:
basename(cwd) (e.g. obsidianMcp, eportfolio, tes).kb_search via tags: [<ap>] on the first attempt.Examples:
cwd = D:\work\local\sron\obsidianMcp\obsidianMcp → AP tag obsidianMcpcwd = D:\work\local\sron\tes → AP tag tesDon't fabricate AP tags — if the basename looks generic (src, app, home), skip the tag filter and search broadly.
1. kb_lookup(query)
├─ hit → use note.body verbatim. Cite [title](relPath). DONE.
└─ miss → continue
2. kb_search(query, tags=[<ap>], limit=5)
├─ has results → kb_read top 1–3 → synthesize answer → cite paths
└─ 0 results → kb_search(query, limit=5) ← widen
├─ has results → same as above
└─ 0 results → answer from general knowledge, mark as "not in KB"
3. After answering, decide write-back (see below).
Cache hit rule: if kb_lookup returns hit:true, do NOT paraphrase. Quote the note body and add the citation. The whole point of cache is deterministic, fast answers.
When a useful answer was just produced, decide whether to persist it. Routing by content kind:
Call kb_create immediately for:
These are "result-shaped" — short, stable, reusable.
Briefly ask "要存到知識庫嗎?" before kb_create for:
kb_search first)status: "draft" and let the user reviewkb_create argument guidancekb_create({
title: "短而具體,不含日期",
body: "Markdown body — 用 ## 章節分。Bug 類常見章節:症狀 / 根因 / 修法 / 驗證",
hintTags: [<ap>, ...domain tags], // 一定要帶 AP tag 做隔離
cache: <see below>,
triggers: [...], // 只在 cache:true 時填
priority: 1-10, // 預設 5;常用配置/指令給 8-9
status: "draft" | "review" | "stable" | "deprecated"
})
cache: trueALL of these must hold:
Examples that qualify: env var paths, "怎麼啟動 docker", API endpoint, 常用 git 指令. Examples that don't: 「我們上次討論的結論」, 多步驟解 bug.
When cache: true, ALWAYS provide triggers — 3–5 lowercase short phrases the user would actually type/say. Without triggers, kb_lookup won't find it.
Auto-persist bug fix:
kb_create({
title: "MCP HTTP server 多 session crash",
body: "## 症狀\n...\n## 修法\n...",
hintTags: ["obsidianMcp", "mcp", "debugging"],
status: "stable",
priority: 4
})
Cache-worthy command:
kb_create({
title: "啟動 obsidian-kb docker",
body: "`docker compose up -d --build` 在 vault root 執行",
hintTags: ["obsidianMcp", "docker"],
cache: true,
triggers: [
"啟動 obsidian-kb",
"啟動知識庫 docker",
"obsidian-kb 怎麼跑",
"重啟 kb container"
],
priority: 9,
status: "stable"
})
After any non-trivial kb_create / kb_update_frontmatter, append a log entry:
kb_log_append({
kind: "note", // or "ingest" if from raw/, "query" if from a user question, "lint" for cleanup
title: "短描述:做了什麼",
detail: "可選;多一兩句 context"
})
This preserves a chronological trail in _system/log.md.
kb_lookup returns {hit:false} — normal, just continue to kb_search.kb_create rejects due to classifier failure (no ANTHROPIC_API_KEY) — the rule-based path still works; if neither classifies, the note lands in 00-Inbox/.docker ps | grep obsidian-kb); do NOT fall back to writing markdown files directly.kb_create / kb_update_frontmatter.cache: true without giving triggers.Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub huangsron/kb-skill --plugin kb-skill