Record Knowledge
Goal
Capture tacit knowledge discovered during work and make it available for future sessions.
When to Reference
- New session start: Search
.claude/knowledge/entries/ for active entries related to the current task before starting work
- If an
overview entry exists for the topic, read it first — load detail entries on demand to save context
- Progress update: Check if related entries need updating based on new discoveries
- Not needed when resuming a session (context is already preserved)
When to Record
- Undocumented behavior, quirks, or pitfalls
- Hardware/service characteristics shared by the user
- Dependencies or coupled settings discovered during configuration
- Decision rationale (why a particular approach was chosen)
- Root causes and fixes found during troubleshooting
- Claude Code's own mistakes and prevention measures — errors pointed out by the user, incorrect output, tool misuse, etc. Record specifically: what happened, why it was wrong, and what to do next time. Tag with
#pitfall
- Environment-specific behavior — when a discovery is tied to a specific PC, OS, network, or toolchain version (e.g., proxy issues at office, build differences between WSL and native Linux), include the environment details (hostname, OS, network type, etc.) in the entry body. Tag with
#environment-specific. This aids retrospective fact-checking when the same user or team works across multiple environments
Setup
Copy assets/knowledge-CLAUDE.md to .claude/knowledge/CLAUDE.md:
mkdir -p .claude/knowledge/entries
cp assets/knowledge-CLAUDE.md .claude/knowledge/CLAUDE.md
This creates the tag registry and search reference used by the skill.
Recording Flow
- Create
.claude/knowledge/entries/YYYY/MM/YYYYMMDD-HHMMSS-author-slug.md with YAML frontmatter
- For new discoveries without enough detail yet, write a temporary note in the working directory and convert to an entry later
- Do NOT add links to subdirectory
CLAUDE.md files — use tag search to find entries instead
- Claude Code acts autonomously — create and edit entries without asking for user confirmation
Entry Location
.claude/knowledge/entries/YYYY/MM/YYYYMMDD-HHMMSS-author-slug.md — one file per entry, organized by year/month- Timestamp prefix ensures chronological ordering and collision avoidance
- Author field uses your Git hosting platform account name (without
@)
- Slug is descriptive kebab-case
- Example:
2026/03/20260302-143052-alice-docker-compose-port-conflict.md
- Create
YYYY/MM/ subdirectory if it doesn't exist
- Legacy flat entries (directly under
entries/) remain functional — migrate with scripts/migrate-to-dated-dirs.py
Entry Format (YAML Frontmatter)
---
title: <title>
author: "@<username>"
created: YYYY-MM-DD
status: draft | active | superseded | deprecated
type: knowledge | overview | detail | fragment | synthesis
confidence: low | mid | high
superseded_by: YYYY/MM/newer-entry-slug.md # only when status: superseded
tags: "#tag1 #tag2 ..."
---
<body — concrete facts, procedures, code examples, etc.>
- ref: [display text](URL or relative path)
- see: [related entry title](YYYY/MM/slug.md) — relationship description
- Keep entries focused and under 100 KB where possible. If approaching 1 MB, split into multiple focused entries (one pitfall, one decision, one root cause per entry). Large entries degrade context loading precision in future sessions
- When creating an entry that exceeds 300 lines, consider splitting it immediately using the split procedure below
type is optional — defaults to knowledge if omitted
Entry Types
| Type |
Meaning |
When to Use |
knowledge |
Standalone verified fact (default) |
Most entries — independent pieces of knowledge |
overview |
Topic entry point with summary and detail links |
When 3+ detail entries exist for a topic |
detail |
Focused entry referenced from an overview |
Deep-dive into a specific aspect of a topic |
fragment |
Isolated observation, not yet promoted |
Quick notes that may become knowledge later |
synthesis |
Cross-cutting insight from multiple entries |
Integrating patterns across entries (#27) |
Overview Entries
Overview entries serve as topic entry points that reduce context consumption:
- Add
topic: <topic-name> to frontmatter (lowercase kebab-case)
- Include a
## Detail Entries section listing related detail entries via see links
- On session start, read the overview first; load detail entries on demand
- Consider creating an overview when 3+ entries share the same primary tag
---
title: "Docker — Overview"
type: overview
topic: docker
status: active
tags: "#docker"
---
Summary of Docker-related knowledge.
## Detail Entries
- see: [Port conflict resolution](YYYY/MM/slug.md) — common port conflicts
- see: [Build cache pitfalls](YYYY/MM/slug.md) — cache invalidation issues
Tag Guidelines
- Claude Code assigns tags autonomously for optimal searchability
- Naming: lowercase kebab-case with
# prefix (e.g., #docker, #typescript, #pitfall)
- Add new tags freely as needed
- Check the tag registry in
.claude/knowledge/CLAUDE.md before creating new tags to avoid duplicates
Similarity Check (on every entry creation)
Before assigning tags to a new entry, scan the tag registry for near-duplicates:
- Singular/plural:
#backup vs #backups → use the existing form
- Abbreviation/full:
#k8s vs #kubernetes → use the existing form
- Synonym:
#error vs #bug → use the existing form
- Substring overlap:
#windows-service vs #win-service → use the existing form
If a near-duplicate is found, reuse the existing tag. Do not create a new one.
ref / see Link Format
- Use Markdown links for URLs and repo paths (clickable in your Git hosting platform's web UI)
- External:
- ref: [title](https://example.com/...)
- In-repo:
- ref: [path](../../../relative-path) (relative from .claude/knowledge/entries/)
see Links (Synapse Formation Between Entries)
- Add
see: links to related entries when creating or editing an entry
- Within
entries/, use entries/-relative paths: - see: [title](YYYY/MM/slug.md) — relationship
- Describe the relationship briefly after
— (e.g., "another port conflict", "prerequisite step")
- Relevance criteria:
- Sequential steps: procedure step dependencies, workflow stages
- Same technology, different pitfalls: multiple gotchas for one tool
- Prerequisite → application: setup steps → usage caveats
- Design decision ↔ rationale: architecture choice ↔ supporting evidence
- Bidirectional links by default (if A → B, add B → A too)
- When adding a new entry, update related existing entries with see links
Status Definitions
| Status |
Meaning |
Claude Code Behavior |
draft |
Unverified fragment |
Reference with caution. Do not use as basis for decisions |
active |
Verified, current knowledge |
Use as basis for decisions |
superseded |
Replaced by a newer entry |
Do not reference; follow superseded_by link to the replacement |
deprecated |
Obsolete, no longer relevant |
Do not reference; use only for historical context |
Confidence Levels
| Level |
Meaning |
When to Use |
low |
Anecdotal or unverified |
Observed once, not yet reproduced or confirmed |
mid |
Partially verified |
Reproduced or confirmed in some contexts |
high |
Well-established fact |
Verified multiple times, documented, or widely known |
confidence is optional — omit if not applicabledraft entries typically have confidence: low- Promote
confidence as knowledge is verified through use
Correction Flow (superseded)
When an entry is found to be incorrect:
- Set
status: superseded and add superseded_by: YYYY/MM/newer-entry-slug.md
- Create the replacement entry with a
- see: link: corrects [original title](YYYY/MM/original.md)
- Keep the original entry intact — it preserves why the incorrect belief was held, useful for retrospective learning
- Do NOT delete or overwrite the original content
Entry Granularity
1 entry = 1 topic. A topic is the smallest unit of knowledge that is useful on its own.
Splitting guidelines:
- 1 pitfall → 1 entry
- 1 design decision + rationale → 1 entry
- 1 root cause + fix → 1 entry
- Background shared by multiple entries →
type: fragment or a referenced synthesis entry
When recording from a large context (e.g., session output):
- Identify distinct topics within the context
- Create 1 entry per topic
- Link related entries with
- see:
Synthesis Entries
A synthesis entry distills patterns and principles from multiple related entries. It represents the author's internalized understanding, not just recorded facts.
---
title: "My approach to NixOS system configuration"
type: synthesis
status: active
confidence: high
tags: "#nixos #system-config"
sources:
- YYYY/MM/entry-a.md
- YYYY/MM/entry-b.md
- YYYY/MM/entry-c.md
---
Distilled understanding from experience.
Not just facts — the author's own perspective and principles.
- see: [entry-a](YYYY/MM/entry-a.md) — source
- see: [entry-b](YYYY/MM/entry-b.md) — source
sources: lists the entries that were synthesized (entries/-relative paths)- Synthesis entries do NOT replace source entries — sources remain
active
- On session start, prefer
synthesis over individual knowledge entries for the same topic (reduces context consumption)
Amendment Rules
- Entries are mutable — edit in place (git tracks change history)
- Adding info, corrections, supplementary examples → edit directly
- Use
git log entries/<slug>.md to review change history
- Use
deprecated only when knowledge is genuinely obsolete
- Example: service decommissioned, fundamental spec change, "should no longer be referenced"
- Use
superseded when an entry is replaced by a corrected version (see Correction Flow above)
Splitting Large Entries
When an entry exceeds 300 lines or approaches 100 KB, split it into an index + sub-entries structure:
Split Structure
entries/YYYY/MM/
├── YYYYMMDD-HHMMSS-author-topic.md ← Index (type: overview)
└── YYYYMMDD-HHMMSS-author-topic/
├── section-one.md ← Sub-entry (type: detail)
├── section-two.md ← Sub-entry (type: detail)
└── section-three.md ← Sub-entry (type: detail)
Split Procedure
- Create a subdirectory next to the original entry with the same base name (without
.md)
- Move each major section (
## heading) into its own file in the subdirectory
- Convert the original entry into an index (
type: overview) with:
- Brief summary of the topic
## Detail Entries section with see links to each sub-entry
- Each sub-entry gets its own frontmatter (
type: detail, same tags as parent)
- Sub-entries use simple filenames (no timestamp prefix needed — the parent directory provides context)
When to Split
- Entry exceeds 300 lines during creation → split immediately
- Existing entry grows past 300 lines through edits → propose split
review-knowledge reports an entry as oversized → split in fix mode
Procedure
- Extract knowledge from user input or work discoveries
- Read the tag registry in
.claude/knowledge/CLAUDE.md
- Select tags — reuse existing tags; check for near-duplicates before creating any new tag
- Find related entries (see link candidates) — run before writing so links are included from the start:
a. Tag search: Grep
entries/ for each tag assigned in step 3 (e.g., Grep pattern="#docker" path=".claude/knowledge/entries/")
b. Keyword search: Grep for 2–3 distinctive terms from the title or body (tool names, error messages, config keys)
c. Narrow results: Skip deprecated entries. From the remaining hits, read titles and tags to judge relevance using the criteria in "see Links (Synapse Formation Between Entries)"
d. Prepare links: For each related entry, draft a - see: line with a brief relationship description
- Create
.claude/knowledge/entries/YYYY/MM/YYYYMMDD-HHMMSS-author-slug.md (or edit existing entry) — include the see links drafted in step 4
- Tag registry update (mandatory): If a new tag was created, add it to the tag registry in
.claude/knowledge/CLAUDE.md within the same operation — do not defer this step. Use scripts/regenerate-tag-registry.py --write for bulk maintenance
- Add backlinks: For each entry linked in step 4, edit that entry to add a reciprocal
- see: link pointing back to the new entry
- Briefly notify the user what was recorded and which entries were linked (no confirmation needed beforehand)
1---2name: record-knowledge3description: Record tacit knowledge — quirks, pitfalls, dependencies, decisions, root causes — as tagged Markdown entries in `.claude/knowledge/entries/`. Use this skill whenever discoveries are made during work, when the user shares undocumented system behavior, or at plan completion to capture lessons learned. Also use when Claude Code makes a mistake pointed out by the user — record what happened, why it was wrong, and what to do next time.4license: MIT5---6
7# Record Knowledge
8
9## Goal
10Capture tacit knowledge discovered during work and make it available for future sessions.
11
12## When to Reference
13- **New session start**: Search `.claude/knowledge/entries/` for active entries related to the current task before starting work
14 - If an `overview` entry exists for the topic, read it first — load `detail` entries on demand to save context
15- **Progress update**: Check if related entries need updating based on new discoveries
16- Not needed when resuming a session (context is already preserved)
17
18## When to Record
19- Undocumented behavior, quirks, or pitfalls
20- Hardware/service characteristics shared by the user
21- Dependencies or coupled settings discovered during configuration
22- Decision rationale (why a particular approach was chosen)
23- Root causes and fixes found during troubleshooting
24- **Claude Code's own mistakes and prevention measures** — errors pointed out by the user, incorrect output, tool misuse, etc. Record specifically: what happened, why it was wrong, and what to do next time. Tag with `#pitfall`
25- **Environment-specific behavior** — when a discovery is tied to a specific PC, OS, network, or toolchain version (e.g., proxy issues at office, build differences between WSL and native Linux), include the environment details (hostname, OS, network type, etc.) in the entry body. Tag with `#environment-specific`. This aids retrospective fact-checking when the same user or team works across multiple environments
26
27## Setup
28
29Copy `assets/knowledge-CLAUDE.md` to `.claude/knowledge/CLAUDE.md`:
30
31```bash
32mkdir -p .claude/knowledge/entries
33cp assets/knowledge-CLAUDE.md .claude/knowledge/CLAUDE.md
34```
35
36This creates the tag registry and search reference used by the skill.
37
38## Recording Flow
39
401. Create `.claude/knowledge/entries/YYYY/MM/YYYYMMDD-HHMMSS-author-slug.md` with YAML frontmatter
412. For new discoveries without enough detail yet, write a temporary note in the working directory and convert to an entry later
423. Do NOT add links to subdirectory `CLAUDE.md` files — use tag search to find entries instead
434. Claude Code acts autonomously — create and edit entries without asking for user confirmation
44
45## Entry Location
46- `.claude/knowledge/entries/YYYY/MM/YYYYMMDD-HHMMSS-author-slug.md` — one file per entry, organized by year/month
47- Timestamp prefix ensures chronological ordering and collision avoidance
48- Author field uses your Git hosting platform account name (without `@`)
49- Slug is descriptive kebab-case
50- Example: `2026/03/20260302-143052-alice-docker-compose-port-conflict.md`
51- Create `YYYY/MM/` subdirectory if it doesn't exist
52- Legacy flat entries (directly under `entries/`) remain functional — migrate with `scripts/migrate-to-dated-dirs.py`
53
54## Entry Format (YAML Frontmatter)
55```markdown
56---
57title: <title>
58author: "@<username>"
59created: YYYY-MM-DD
60status: draft | active | superseded | deprecated
61type: knowledge | overview | detail | fragment | synthesis
62confidence: low | mid | high
63superseded_by: YYYY/MM/newer-entry-slug.md # only when status: superseded
64tags: "#tag1 #tag2 ..."
65---
66
67<body — concrete facts, procedures, code examples, etc.>
68
69- ref: [display text](URL or relative path)
70- see: [related entry title](YYYY/MM/slug.md) — relationship description
71```
72
73- Keep entries focused and under **100 KB** where possible. If approaching **1 MB**, split into multiple focused entries (one pitfall, one decision, one root cause per entry). Large entries degrade context loading precision in future sessions
74- When creating an entry that exceeds **300 lines**, consider splitting it immediately using the split procedure below
75- `type` is optional — defaults to `knowledge` if omitted
76
77### Entry Types
78
79| Type | Meaning | When to Use |
80|------|---------|-------------|
81| `knowledge` | Standalone verified fact (default) | Most entries — independent pieces of knowledge |
82| `overview` | Topic entry point with summary and detail links | When 3+ detail entries exist for a topic |
83| `detail` | Focused entry referenced from an overview | Deep-dive into a specific aspect of a topic |
84| `fragment` | Isolated observation, not yet promoted | Quick notes that may become knowledge later |
85| `synthesis` | Cross-cutting insight from multiple entries | Integrating patterns across entries (#27) |
86
87### Overview Entries
88
89Overview entries serve as **topic entry points** that reduce context consumption:
90
91- Add `topic: <topic-name>` to frontmatter (lowercase kebab-case)
92- Include a `## Detail Entries` section listing related detail entries via see links
93- On session start, read the overview first; load detail entries on demand
94- Consider creating an overview when 3+ entries share the same primary tag
95
96```markdown
97---
98title: "Docker — Overview"
99type: overview
100topic: docker
101status: active
102tags: "#docker"
103---
104
105Summary of Docker-related knowledge.
106
107## Detail Entries
108- see: [Port conflict resolution](YYYY/MM/slug.md) — common port conflicts
109- see: [Build cache pitfalls](YYYY/MM/slug.md) — cache invalidation issues
110```
111
112### Tag Guidelines
113- Claude Code assigns tags autonomously for optimal searchability
114- Naming: lowercase kebab-case with `#` prefix (e.g., `#docker`, `#typescript`, `#pitfall`)
115- Add new tags freely as needed
116- Check the tag registry in `.claude/knowledge/CLAUDE.md` before creating new tags to avoid duplicates
117
118#### Similarity Check (on every entry creation)
119Before assigning tags to a new entry, scan the tag registry for near-duplicates:
120- **Singular/plural**: `#backup` vs `#backups` → use the existing form
121- **Abbreviation/full**: `#k8s` vs `#kubernetes` → use the existing form
122- **Synonym**: `#error` vs `#bug` → use the existing form
123- **Substring overlap**: `#windows-service` vs `#win-service` → use the existing form
124If a near-duplicate is found, reuse the existing tag. Do not create a new one.
125
126### ref / see Link Format
127- Use Markdown links for URLs and repo paths (clickable in your Git hosting platform's web UI)
128 - External: `- ref: [title](https://example.com/...)`
129 - In-repo: `- ref: [path](../../../relative-path)` (relative from `.claude/knowledge/entries/`)
130
131### see Links (Synapse Formation Between Entries)
132- Add `see:` links to related entries when creating or editing an entry
133- Within `entries/`, use entries/-relative paths: `- see: [title](YYYY/MM/slug.md) — relationship`
134- Describe the relationship briefly after `—` (e.g., "another port conflict", "prerequisite step")
135- Relevance criteria:
136 - **Sequential steps**: procedure step dependencies, workflow stages
137 - **Same technology, different pitfalls**: multiple gotchas for one tool
138 - **Prerequisite → application**: setup steps → usage caveats
139 - **Design decision ↔ rationale**: architecture choice ↔ supporting evidence
140- Bidirectional links by default (if A → B, add B → A too)
141- When adding a new entry, update related existing entries with see links
142
143## Status Definitions
144
145| Status | Meaning | Claude Code Behavior |
146|--------|---------|---------------------|
147| `draft` | Unverified fragment | Reference with caution. Do not use as basis for decisions |
148| `active` | Verified, current knowledge | Use as basis for decisions |
149| `superseded` | Replaced by a newer entry | Do not reference; follow `superseded_by` link to the replacement |
150| `deprecated` | Obsolete, no longer relevant | Do not reference; use only for historical context |
151
152### Confidence Levels
153
154| Level | Meaning | When to Use |
155|-------|---------|-------------|
156| `low` | Anecdotal or unverified | Observed once, not yet reproduced or confirmed |
157| `mid` | Partially verified | Reproduced or confirmed in some contexts |
158| `high` | Well-established fact | Verified multiple times, documented, or widely known |
159
160- `confidence` is optional — omit if not applicable
161- `draft` entries typically have `confidence: low`
162- Promote `confidence` as knowledge is verified through use
163
164### Correction Flow (superseded)
165
166When an entry is found to be incorrect:
1671. Set `status: superseded` and add `superseded_by: YYYY/MM/newer-entry-slug.md`
1682. Create the replacement entry with a `- see:` link: `corrects [original title](YYYY/MM/original.md)`
1693. Keep the original entry intact — it preserves why the incorrect belief was held, useful for retrospective learning
1704. Do NOT delete or overwrite the original content
171
172## Entry Granularity
173
174**1 entry = 1 topic.** A topic is the smallest unit of knowledge that is useful on its own.
175
176Splitting guidelines:
177- 1 pitfall → 1 entry
178- 1 design decision + rationale → 1 entry
179- 1 root cause + fix → 1 entry
180- Background shared by multiple entries → `type: fragment` or a referenced `synthesis` entry
181
182When recording from a large context (e.g., session output):
1831. Identify distinct topics within the context
1842. Create 1 entry per topic
1853. Link related entries with `- see:`
186
187### Synthesis Entries
188
189A `synthesis` entry distills patterns and principles from multiple related entries. It represents the author's internalized understanding, not just recorded facts.
190
191```markdown
192---
193title: "My approach to NixOS system configuration"
194type: synthesis
195status: active
196confidence: high
197tags: "#nixos #system-config"
198sources:
199 - YYYY/MM/entry-a.md
200 - YYYY/MM/entry-b.md
201 - YYYY/MM/entry-c.md
202---
203
204Distilled understanding from experience.
205Not just facts — the author's own perspective and principles.
206
207- see: [entry-a](YYYY/MM/entry-a.md) — source
208- see: [entry-b](YYYY/MM/entry-b.md) — source
209```
210
211- `sources:` lists the entries that were synthesized (entries/-relative paths)
212- Synthesis entries do NOT replace source entries — sources remain `active`
213- On session start, prefer `synthesis` over individual `knowledge` entries for the same topic (reduces context consumption)
214
215## Amendment Rules
216- Entries are **mutable** — edit in place (git tracks change history)
217 - Adding info, corrections, supplementary examples → edit directly
218 - Use `git log entries/<slug>.md` to review change history
219- Use `deprecated` only when knowledge is genuinely obsolete
220 - Example: service decommissioned, fundamental spec change, "should no longer be referenced"
221- Use `superseded` when an entry is replaced by a corrected version (see Correction Flow above)
222
223## Splitting Large Entries
224
225When an entry exceeds 300 lines or approaches 100 KB, split it into an **index + sub-entries** structure:
226
227### Split Structure
228```
229entries/YYYY/MM/
230├── YYYYMMDD-HHMMSS-author-topic.md ← Index (type: overview)
231└── YYYYMMDD-HHMMSS-author-topic/
232 ├── section-one.md ← Sub-entry (type: detail)
233 ├── section-two.md ← Sub-entry (type: detail)
234 └── section-three.md ← Sub-entry (type: detail)
235```
236
237### Split Procedure
2381. Create a subdirectory next to the original entry with the same base name (without `.md`)
2392. Move each major section (`## heading`) into its own file in the subdirectory
2403. Convert the original entry into an index (`type: overview`) with:
241 - Brief summary of the topic
242 - `## Detail Entries` section with see links to each sub-entry
2434. Each sub-entry gets its own frontmatter (`type: detail`, same tags as parent)
2445. Sub-entries use simple filenames (no timestamp prefix needed — the parent directory provides context)
245
246### When to Split
247- Entry exceeds **300 lines** during creation → split immediately
248- Existing entry grows past **300 lines** through edits → propose split
249- `review-knowledge` reports an entry as oversized → split in fix mode
250
251## Procedure
2521. Extract knowledge from user input or work discoveries
2532. Read the tag registry in `.claude/knowledge/CLAUDE.md`
2543. Select tags — reuse existing tags; check for near-duplicates before creating any new tag
2554. **Find related entries** (see link candidates) — run before writing so links are included from the start:
256 a. **Tag search**: Grep `entries/` for each tag assigned in step 3 (e.g., `Grep pattern="#docker" path=".claude/knowledge/entries/"`)
257 b. **Keyword search**: Grep for 2–3 distinctive terms from the title or body (tool names, error messages, config keys)
258 c. **Narrow results**: Skip `deprecated` entries. From the remaining hits, read titles and tags to judge relevance using the criteria in "see Links (Synapse Formation Between Entries)"
259 d. **Prepare links**: For each related entry, draft a `- see:` line with a brief relationship description
2605. Create `.claude/knowledge/entries/YYYY/MM/YYYYMMDD-HHMMSS-author-slug.md` (or edit existing entry) — include the see links drafted in step 4
2616. **Tag registry update (mandatory)**: If a new tag was created, add it to the tag registry in `.claude/knowledge/CLAUDE.md` **within the same operation** — do not defer this step. Use `scripts/regenerate-tag-registry.py --write` for bulk maintenance
2627. **Add backlinks**: For each entry linked in step 4, edit that entry to add a reciprocal `- see:` link pointing back to the new entry
2638. Briefly notify the user what was recorded and which entries were linked (no confirmation needed beforehand)
majiayu000