Maintain a per-repo napkin as a continuously curated runbook

by blader · MIT license · ★ 643 on GitHub · v6.0.0

Maintain a per-repo napkin as a continuously curated runbook (not a session log). Activates EVERY session.

---
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.**

Overview

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

Manual install (npx, ZIP)

Claude Codenpx skills add blader/napkin -g -a claude-code

Claude.ai / desktopZip the folder and upload it under Settings → Capabilities → Skills.

Codex, Cursor, other agentsPoint them at SKILL.md. The other files are plain text.

Connects with Agent Alley MCP · agentalley.io/mcp

Files included

SKILL.md3.1 KB

Read SKILL.md here

blader/main1 file

SKILL.md3.1 KB

SKILL.md

Show the full text107 lines

napkin/SKILL.md107 lines · 3.1 KB

PreviewCode

Outline

RawView on GitHub

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`.

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