From knowledge-base
Capture durable knowledge to the user's Obsidian knowledge base AFTER finishing work that involved surprise, multiple-attempt debugging, framework quirks, or a new reusable pattern — even when the user did not explicitly ask. Use this skill whenever you just (1) fixed a non-trivial bug, (2) resolved a silent failure or behavior that contradicted an assumption, (3) wrapped up a Jira / WFR implement or fix subtask, (4) spent >2 attempts on a fix, (5) discovered a framework / tool quirk not obvious from docs, or (6) established a new reusable pattern. Walks a rigid 5-item save checklist — if nothing triggers, announces "save skipped" and stops. Does NOT commit vault changes; user reviews manually. Skipping this skill when the checklist applies lets the same problem re-occur in future sessions — that is the failure mode this skill exists to prevent.
How this skill is triggered — by the user, by Claude, or both
Slash command
/knowledge-base:knowledge-saveThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are deciding whether a just-solved problem is worth preserving in the user's Knowledge Base, and if so, writing it.
You are deciding whether a just-solved problem is worth preserving in the user's Knowledge Base, and if so, writing it.
The whole point of this skill: the next time this problem appears (in this session or a future one), knowledge-lookup finds it and prevents re-solving.
Explicitly check EACH box against the task you just finished. Announce which boxes are triggered.
If NONE apply, announce:
Save skipped — no checklist item triggered. (Ran: surprise N, attempts N, quirk N, new pattern N, read source N.)
Then STOP. Do not write.
If ANY apply, continue to Step 2.
Don't mash both into one doc. If the work is both ("we hit a gotcha AND established a pattern"), write two docs.
Resources/gotchas/ or Resources/patterns/.Projects/<slug>/gotchas/ or Projects/<slug>/patterns/.Litmus test for cross-project: "Would this be useful in a completely different repo that uses the same tool?" If yes, cross-project.
Current project slug resolves the same way as in knowledge-lookup: CLAUDE.md frontmatter project_slug, then git repo basename, then give up and use cross only.
Grep the MOC for overlapping keywords:
grep -i "<key-keyword>" ~/Documents/workspace/obsidian-vault/claude-code/Resources/MOC-Knowledge-Base.md
Try 2-3 distinctive keywords. If a line comes back that looks like it covers the same problem, UPDATE that existing doc rather than creating a new one. Append today's incident to its ## Example incident section. Update the MOC one-liner if wording needs refinement.
If no overlap, continue to Step 5.
Pick the path based on type + scope:
| Type | Scope | Path |
|---|---|---|
| gotcha | cross | ~/Documents/workspace/obsidian-vault/claude-code/Resources/gotchas/<slug>.md |
| gotcha | project | ~/Documents/workspace/obsidian-vault/claude-code/Projects/<slug>/gotchas/<slug>.md |
| pattern | cross | ~/Documents/workspace/obsidian-vault/claude-code/Resources/patterns/<slug>.md |
| pattern | project | ~/Documents/workspace/obsidian-vault/claude-code/Projects/<slug>/patterns/<slug>.md |
If the project-specific gotchas/patterns folder doesn't exist yet, create it.
<slug> is kebab-case, descriptive, ≤ 6 words. Examples: drizzle-migration-when-timestamp, nginx-alb-cookie-stripping, new-account-tab.
Gotcha template (reuse the canonical structure from Resources/gotchas/drizzle-migration-when-timestamp.md):
---
title: <title>
date: YYYY-MM-DD
tags:
- type/gotcha
- stack/<stack>
- project/<project-or-cross>
---
# <title>
Back to: [[Resources/MOC-Knowledge-Base|MOC — Knowledge Base]]
## Symptom
<what you observed — commands run, output shown, user-visible effect>
## Root cause
<why it happens — the mechanism or library behavior that causes it>
## Fix
<steps to resolve — concrete commands or edits>
## Example incident
<concrete case: project, date (ISO), ticket ID, what happened, what fixed it, commit hash if known>
## Prevention
<how to avoid next time — a check, a lint, a doc update>
## Related
<wikilinks to related entries, MOCs, or code paths>
Pattern template:
---
title: <title>
date: YYYY-MM-DD
tags:
- type/pattern
- stack/<stack>
- project/<project-or-cross>
---
# <title>
Back to: [[Resources/MOC-Knowledge-Base|MOC — Knowledge Base]]
## When to use
<trigger conditions — what situation makes this pattern the right choice>
## Steps
1. …
2. …
3. …
## Example
<concrete application — paste the code/commands/config from when you just applied it>
## Pitfalls
<what to watch out for — the places this pattern misleads>
## Related
<wikilinks>
Prepend (NOT append) a one-line entry to the matching section of ~/Documents/workspace/obsidian-vault/claude-code/Resources/MOC-Knowledge-Base.md. Newest entries are on top within each section.
Format:
- [[<vault-path>|<title>]] — <scope> <keywords> <one-line hook>
<vault-path>: e.g. Resources/gotchas/my-new-gotcha (no .md)<title>: the H1 title of the full doc<scope>: cross or project slug<keywords>: 2-5 lowercase topic words — stack, area, error type<hook>: terse description, ≤ 15 wordsExample:
- [[Projects/c360/gotchas/nginx-alb-cookie-stripping|c360 nginx ALB cookie stripping]] — c360 nginx deploy alb ALB rewrites Set-Cookie domain on cross-origin requests
Announce to the user:
KB saved:
- Type: <gotcha | pattern>
- Scope: <cross | project>
- Doc: <full path>
- MOC updated: Resources/MOC-Knowledge-Base.md (prepended 1 line)
Vault changes are NOT committed — please review and commit manually.
Do NOT run git commit in the vault. The user wants to eyeball vault changes before they become permanent.
## Example incident entry under the existing one (don't overwrite). Announce KB updated (existing entry enriched) instead of KB saved.KB save failed — could not write to <path>. Please check vault path. and stop.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 harsh1210/claude-code-knowledge-base --plugin knowledge-base