Napkin

Napkin

You maintain a per-repo markdown runbook, not a chronological log. The napkin must be continuously curated for fast reuse in future sessions.

This skill is always active. Every session. No trigger required.

Session Start: Read And Curate

First thing, every session — read .claude/napkin.md before doing anything else. Internalize what's there and apply it silently. Don't announce that you read it. Just apply what you know.

Every time you read it, curate it immediately:

• Re-prioritize items by importance (highest first).
• Merge duplicates and remove stale/low-signal notes.
• Keep only recurring, high-frequency guidance.
• Ensure each item contains an explicit "Do instead" action.
• Enforce category caps (top 10 per category).

If no napkin exists yet, create one at .claude/napkin.md:

# Napkin Runbook

## Curation Rules
- Re-prioritize on every read.
- Keep recurring, high-value notes only.
- Max 10 items per category.
- Each item includes date + "Do instead".

## Execution & Validation (Highest Priority)
1. **[YYYY-MM-DD] Short rule**
   Do instead: concrete repeatable action.

## Shell & Command Reliability
1. **[YYYY-MM-DD] Short rule**
   Do instead: concrete repeatable action.

## Domain Behavior Guardrails
1. **[YYYY-MM-DD] Short rule**
   Do instead: concrete repeatable action.

## User Directives
1. **[YYYY-MM-DD] Directive**
   Do instead: exactly follow this preference.

Adapt categories to the repo, but keep category structure and priority ordering. Do not use raw journal-style entries.

Continuous Runbook Updates

Update during work whenever you learn something reusable.

What qualifies for inclusion:

• Frequent gotchas or surprising behavior in this repo/toolchain.
• User directives that affect repeated behavior.
• Non-obvious tactics that repeatedly work.

What does not qualify:

• One-off timeline notes.
• Verbose postmortems without reusable action.
• Pure mistake logs without "Do instead" guidance.

Entry format requirements:

• Include date added ([YYYY-MM-DD]).
• Include short rule title.
• Include explicit Do instead: line.
• Keep wording concise and action-oriented.

Category And Priority Policy

• Organize notes by category.
• Keep each category sorted by importance descending.
• Re-evaluate category choice and priority whenever editing.
• Maximum 10 items per category; if over 10, remove lowest-priority entries.
• Prefer fewer high-signal items over broad coverage.

Practical Rule

Think of napkin as a live knowledge base for future execution speed and reliability, not a history file.

Example Entry

1. **[2026-02-21] `rg` fails on giant expanded path lists**
   Do instead: run `rg` on directory roots or iterate files via `while IFS= read -r`.

Napkin

A skill for Claude Code that gives the agent persistent memory of its mistakes.

The agent maintains a markdown file in your repo (.claude/napkin.md) where it tracks what went wrong, what you corrected, and what worked. It reads the file at session start and writes to it continuously as it works. By session 3-5 the behavior shift is significant — the agent stops making mistakes you've already corrected and starts pre-empting issues before you catch them.

Baby continual learning in a markdown file.

Install

Claude Code

git clone https://github.com/blader/napkin.git ~/.claude/skills/napkin

Codex

git clone https://github.com/blader/napkin.git ~/.codex/skills/napkin

That's it. The skill activates every session, unconditionally.

How it works

1. Session start: Agent reads .claude/napkin.md in the current repo. If it doesn't exist, it creates one. 2. During work: Agent logs mistakes (its own and yours), corrections, patterns, preferences — as they happen, not just at session end. 3. Over sessions: The napkin compounds. Session 1 is normal. Session 3 the agent is catching things before you do. Session 5 it's a different tool.

What gets logged

• Agent's own mistakes — wrong assumptions, bad approaches, failed commands
• Your corrections — anything you told it to do differently
• Tool/environment surprises — things about the repo that weren't obvious
• Your preferences — how you like things done
• What worked — successful approaches worth repeating

The napkin

Lives at .claude/napkin.md in each repo. One per repo. The agent designs the initial structure and adapts it to the project's domain.

You can .gitignore it or commit it — your call. Committing it means other contributors' agents benefit from the same learned patterns. Ignoring it keeps it personal.

License

MIT