record-knowledge · diff
git:20260328.6388128 to git:20260328.a39e96c
30 added, 1 removed. Audit A to A.
---
name: record-knowledge
description: >-
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.
license: MIT
allowed-tools: Read, Grep, Glob, Edit, Write
---
# 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`:
```bash
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
1. Create `.claude/knowledge/entries/YYYY/MM/YYYYMMDD-HHMMSS-author-slug.md` with YAML frontmatter
2. For new discoveries without enough detail yet, write a temporary note in the working directory and convert to an entry later
3. Do NOT add links to subdirectory `CLAUDE.md` files — use tag search to find entries instead
4. 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)
```markdown
---
title: <title>
author: "@<username>"
created: YYYY-MM-DD
status: active | deprecated
type: knowledge | overview | detail | fragment | synthesis
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
```
- - Entry body has no size constraint — include command examples, error messages, config values, decision context as needed
+ - 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
```markdown
---
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 |
|--------|---------|---------------------|
| `active` | Current, valid knowledge | Use as basis for decisions |
| `deprecated` | Obsolete or proven incorrect | Do not reference; use only for historical context |
## 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"
+
+ ## 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
+ 1. Create a subdirectory next to the original entry with the same base name (without `.md`)
+ 2. Move each major section (`## heading`) into its own file in the subdirectory
+ 3. 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
+ 4. Each sub-entry gets its own frontmatter (`type: detail`, same tags as parent)
+ 5. 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
1. Extract knowledge from user input or work discoveries
2. Read the tag registry in `.claude/knowledge/CLAUDE.md`
3. Select tags — reuse existing tags; check for near-duplicates before creating any new tag
4. **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
5. Create `.claude/knowledge/entries/YYYY/MM/YYYYMMDD-HHMMSS-author-slug.md` (or edit existing entry) — include the see links drafted in step 4
6. **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
7. **Add backlinks**: For each entry linked in step 4, edit that entry to add a reciprocal `- see:` link pointing back to the new entry
8. Briefly notify the user what was recorded and which entries were linked (no confirmation needed beforehand)