Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/blader-napkin/badge.svg)](/listings/blader-napkin)

HTML

<a href="/listings/blader-napkin"><img src="/api/listings/blader-napkin/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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.

  1. ---
  2. name: napkin
  3. description: |
  4. Maintain a per-repo napkin as a continuously curated runbook (not a session
  5. log). Activates EVERY session. Read and curate it before work, keep only
  6. recurring high-value guidance, organize by priority-sorted categories, and
  7. cap each category at top 10 items. The napkin lives at `.claude/napkin.md`.
  8. author: Codex
  9. version: 6.0.0
  10. date: 2026-02-21
  11. ---
  12. # Napkin
  13. You maintain a per-repo markdown runbook, not a chronological log. The napkin
  14. must be continuously curated for fast reuse in future sessions.
  15. **This skill is always active. Every session. No trigger required.**
  16. ## Session Start: Read And Curate
  17. First thing, every session — read `.claude/napkin.md` before doing anything
  18. else. Internalize what's there and apply it silently. Don't announce that you
  19. read it. Just apply what you know.
  20. Every time you read it, curate it immediately:
  21. - Re-prioritize items by importance (highest first).
  22. - Merge duplicates and remove stale/low-signal notes.
  23. - Keep only recurring, high-frequency guidance.
  24. - Ensure each item contains an explicit "Do instead" action.
  25. - Enforce category caps (top 10 per category).
  26. If no napkin exists yet, create one at `.claude/napkin.md`:
  27. ```markdown
  28. # Napkin Runbook
  29. ## Curation Rules
  30. - Re-prioritize on every read.
  31. - Keep recurring, high-value notes only.
  32. - Max 10 items per category.
  33. - Each item includes date + "Do instead".
  34. ## Execution & Validation (Highest Priority)
  35. 1. **[YYYY-MM-DD] Short rule**
  36. Do instead: concrete repeatable action.
  37. ## Shell & Command Reliability
  38. 1. **[YYYY-MM-DD] Short rule**
  39. Do instead: concrete repeatable action.
  40. ## Domain Behavior Guardrails
  41. 1. **[YYYY-MM-DD] Short rule**
  42. Do instead: concrete repeatable action.
  43. ## User Directives
  44. 1. **[YYYY-MM-DD] Directive**
  45. Do instead: exactly follow this preference.
  46. ```
  47. Adapt categories to the repo, but keep category structure and priority ordering.
  48. Do not use raw journal-style entries.
  49. ## Continuous Runbook Updates
  50. Update during work whenever you learn something reusable.
  51. What qualifies for inclusion:
  52. - Frequent gotchas or surprising behavior in this repo/toolchain.
  53. - User directives that affect repeated behavior.
  54. - Non-obvious tactics that repeatedly work.
  55. What does not qualify:
  56. - One-off timeline notes.
  57. - Verbose postmortems without reusable action.
  58. - Pure mistake logs without "Do instead" guidance.
  59. Entry format requirements:
  60. - Include date added (`[YYYY-MM-DD]`).
  61. - Include short rule title.
  62. - Include explicit `Do instead:` line.
  63. - Keep wording concise and action-oriented.
  64. ## Category And Priority Policy
  65. - Organize notes by category.
  66. - Keep each category sorted by importance descending.
  67. - Re-evaluate category choice and priority whenever editing.
  68. - Maximum 10 items per category; if over 10, remove lowest-priority entries.
  69. - Prefer fewer high-signal items over broad coverage.
  70. ## Practical Rule
  71. Think of napkin as a live knowledge base for future execution speed and
  72. reliability, not a history file.
  73. ## Example Entry
  74. ```markdown
  75. 1. **[2026-02-21] `rg` fails on giant expanded path lists**
  76. Do instead: run `rg` on directory roots or iterate files via `while IFS= read -r`.
  77. ```
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.

  1. # Napkin
  2. A skill for Claude Code that gives the agent persistent memory of its mistakes.
  3. 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.
  4. Baby continual learning in a markdown file.
  5. ## Install
  6. **Claude Code**
  7. ```bash
  8. git clone https://github.com/blader/napkin.git ~/.claude/skills/napkin
  9. ```
  10. **Codex**
  11. ```bash
  12. git clone https://github.com/blader/napkin.git ~/.codex/skills/napkin
  13. ```
  14. That's it. The skill activates every session, unconditionally.
  15. ## How it works
  16. 1. **Session start**: Agent reads `.claude/napkin.md` in the current repo. If it doesn't exist, it creates one.
  17. 2. **During work**: Agent logs mistakes (its own and yours), corrections, patterns, preferences — as they happen, not just at session end.
  18. 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.
  19. ## What gets logged
  20. - Agent's own mistakes — wrong assumptions, bad approaches, failed commands
  21. - Your corrections — anything you told it to do differently
  22. - Tool/environment surprises — things about the repo that weren't obvious
  23. - Your preferences — how you like things done
  24. - What worked — successful approaches worth repeating
  25. ## The napkin
  26. 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.
  27. 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.
  28. ## License
  29. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.