Where should I store knowledge entries?

In .claude/knowledge/entries with a timestamped filename (one file per entry) using YAML frontmatter.

What should be in the entry frontmatter?

title, author, created, status, and tags, followed by the body and optional ref/see links.

How should links be formatted?

Use Markdown for external and in-repo references; do not link to CLAUDE.md subdirectories; use ref and see as described.

record-knowledge

Scanned

npx machina-cli add skill LevNas/ccmemo/record-knowledge --openclaw

Files (1)

SKILL.md

5.1 KB

Record Knowledge

Goal

Capture tacit knowledge discovered during work and make it available for future sessions.

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

Recording Flow

Create .claude/knowledge/entries/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/YYYYMMDD-HHMMSS-author-slug.md — one file per entry
Timestamp prefix ensures chronological ordering and collision avoidance
Author field uses your Git hosting platform account name (without @)
Slug is descriptive kebab-case
Example: 20260302-143052-alice-docker-compose-port-conflict.md
Existing entries without timestamp prefix remain as-is (no rename required)

Entry Format (YAML Frontmatter)

---
title: <title>
author: "@<username>"
created: YYYY-MM-DD
status: active | deprecated
tags: "#tag1 #tag2 ..."
---

<body — concrete facts, procedures, code examples, etc.>

- ref: [display text](URL or relative path)
- see: [related entry title](related-entry-slug.md) — relationship description

Entry body has no size constraint — include command examples, error messages, config values, decision context as needed

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 filename only: - see: [title](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"

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
Create .claude/knowledge/entries/YYYYMMDD-HHMMSS-author-slug.md (or edit existing entry)
If a new tag was created, add it to the tag registry
Add see links to related existing entries if applicable
Briefly notify the user what was recorded (no confirmation needed beforehand)

Source

git clone https://github.com/LevNas/ccmemo/blob/main/skills/record-knowledge/SKILL.mdView on GitHub

Overview

Record tacit knowledge discovered during work into .claude/knowledge/entries/ to make it searchable and reusable. It covers quirks, pitfalls, dependencies, and decision rationales, and can include troubleshooting fixes and noted mistakes.

How This Skill Works

Create a timestamped entry at .claude/knowledge/entries/YYYYMMDD-HHMMSS-author-slug.md with YAML frontmatter. Document concrete facts, procedures, errors, decisions, and references in the body. Claude Code can autonomously create and edit entries; convert temporary notes into full entries when details exist.

When to Use It

Undocumented behavior, quirks, or pitfalls encountered during work.
Hardware or service characteristics you rely on across sessions.
Dependencies or coupled settings discovered during configuration.
Decision rationale explaining why a particular approach was chosen.
Root causes and fixes found during troubleshooting (including user-reported mistakes).

Quick Start

Step 1: Create .claude/knowledge/entries/YYYYMMDD-HHMMSS-author-slug.md with YAML frontmatter.
Step 2: If details are missing, jot a temporary note in the working directory and convert later.
Step 3: Let Claude Code create/edit entries autonomously; no confirmation required.

Best Practices

Use a descriptive, timestamped filename such as YYYYMMDD-HHMMSS-author-slug.md.
Fill YAML frontmatter with title, author, created, status, and meaningful tags.
Document what happened, why it was wrong, and the next steps to prevent recurrence.
Avoid linking to CLAUDE.md subdirectories; rely on tag search.
Check the tag registry to reuse existing tags and avoid duplicates.

Example Use Cases

20260302-143052-alice-docker-port-conflict.md — docker-compose port binding caused misrouting; recorded steps and fix.
20260418-berta-hardware-threshold.md — sensor variance across batches and the underlying cause.
20260510-john-aws-lambda-timeout.md — misconfigured timeout and resolution.
20260601-sara-cli-misbehavior.md — CLI tool output anomaly and corrective action.
20260615-chen-dependency-lifecycle.md — dependency version coupling discovered during config.

Frequently Asked Questions

Add this skill to your agents