napkin
Maintain a per-repo napkin as a continuously curated runbook (not a session log). Activates EVERY session. Read and curate it before work, keep only recurring high-value guidance, organize by priority-sorted categories, and cap each category at top 10 items. The napkin lives at `.claude/napkin.md`.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/blader-napkin)HTML
<a href="/listings/blader-napkin"><img src="/api/listings/blader-napkin/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
**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.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 106 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- ---
- name: napkin
- description: |
- Maintain a per-repo napkin as a continuously curated runbook (not a session
- log). Activates EVERY session. Read and curate it before work, keep only
- recurring high-value guidance, organize by priority-sorted categories, and
- cap each category at top 10 items. The napkin lives at `.claude/napkin.md`.
- author: Codex
- version: 6.0.0
- date: 2026-02-21
- ---
- # 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`:
- ```markdown
- # 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
- ```markdown
- 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`.
- ```
README.md · README · 47 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # 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**
- ```bash
- git clone https://github.com/blader/napkin.git ~/.claude/skills/napkin
- ```
- **Codex**
- ```bash
- 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
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.