.dotfiles/claude/skills/notes/SKILL.md

name, description

name

description

notes

Manage the project's local .notes/ dir (design docs, work handoffs, parked questions). Use whenever writing a design doc, plan, proposal, research or review for local use; starting, handing off or closing out work that spans sessions (brief, plan, report); parking something for later, out of scope or a follow-up; picking up or settling a parked question; preparing a document for someone else; or when the user mentions .notes, handoffs, open questions or asks what is pending.

Notes

The policy is ~/.config/claude/rules/notes.md: layout, numbering, status lines, close-out, what doesn't belong. This skill holds the procedures. Every step that changes .notes/ ends with commit, which also regenerates index.html, notes.css, the markdown pages under _pages/ and the portable copies under _out/. Change the look only in this skill's notes.css, never in a project.

N=~/.config/claude/skills/notes/notes.py
python3 $N init                 # create .notes/ if missing (idempotent)
python3 $N next d|w|q           # next free id, counts deleted items too
python3 $N commit "<subject>"   # regenerate the generated pages, commit all of .notes/
python3 $N index                # regenerate index.html, notes.css, _pages/ and _out/ only
python3 $N serve                # every project's notes on http://127.0.0.1:8765/: hub filters projects, each project page searches its notes (the user runs this)

All commands take --root <project>; the default is the git toplevel of the current dir. Never pick an id by hand or from ls; deleted ids live only in git history.

New doc

1. init, then next d

2. write docs/dNNN-slug.html (or docs/dNNN-slug/index.html with its assets next to it, then every ../ below becomes ../../) on this skeleton, using only the components documented at the top of notes.css (callout, tag, cards, grid-2, table, figure.diagram with its svg classes); no <style>, no font links:

   <!doctype html>
   <html lang="en">
   <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>Short name</title>
   <link rel="stylesheet" href="../notes.css">
   </head>
   <body>
   <main class="page">
   <nav class="back"><a href="../index.html">← notes</a></nav>
   <header>
     <p class="eyebrow">dNNN · plan · 2026-10-14</p>
     <h1>Title</h1>
     <p class="status current">status: current</p>
     <p class="lede">What this doc decides, in one or two sentences.</p>
   </header>
   <section>
     <h2>…</h2>
   </section>
   </main>
   </body>
   </html>
   

3. if it replaces an older doc, set the older one's status line to <p class="status superseded">status: superseded by <a href="dNNN-slug.html">dNNN</a> (<date>)</p>; mind the relative path when either doc is a folder

4. look at it: a headless browser screenshot in light and dark, or serve

5. commit "dNNN: <slug>"

New work item

Only for work that will span sessions.

1. init, then next w, create work/wNNN-slug/
2. brief.md, starting with # wNNN <title>: goal, done when, scope, verification, decisions to ask, prerequisites to read
3. add plan.html (the proposal, on the doc skeleton with ../../notes.css and ../../index.html) and research files as the work goes; report.md at the end: what was built, what differs from the plan, leftovers
4. commit "wNNN: <what changed>"

Close-out

When the work's branch is merged or the work is dropped, in that same session:

1. lasting design → new doc or a status line on an existing one (see above)
2. each leftover → a question with origin: wNNN
3. rm -r work/wNNN-slug, then commit "wNNN: closed, <merged as <sha>|dropped>"

When index shows a work folder untouched for weeks with no open branch in the project, tell the user; don't close it yourself.

Park a question

1. init, then next q

2. write questions/qNNN-slug.md:

   ---
   created: 2026-10-14
   origin: w009
   status: open
   ---
   
   # <one-line question or follow-up>
   
   What is open and why it matters. What is known so far, with paths, commits and ids.
   Where to start looking.
   

3. commit "qNNN: <slug>"

Write it so a session with no memory of today can act on it.

Settle a question

1. check the repo first: it may already be done or moot
2. fold the outcome into a doc or a work item if it is worth keeping
3. rm questions/qNNN-slug.md, commit "qNNN: settled, <how: done in <sha> | moot because ... | moved to wNNN>"

Other

• other/in/: the user's files; read only when pointed at
• other/out/: documents for someone else, written for that reader; no ids, no status line
  • html follows the doc skeleton and components like any doc, with ../../notes.css and ../../index.html; the eyebrow names the reader and date instead of an id (for the team · 2026-10-14)
  • what gets sent is the generated _out/<file>: notes.css inlined, back link dropped, other files copied; the index links it as "to send"
  • look at the _out/ copy too before handing it over, then commit "other: <file>"

Never

• stage .notes/ from the project repo (git add ., git add -A); stage project paths explicitly
• reference .notes/ paths from committed project files
• keep archives or dated copies; delete, git keeps it
• push .notes/ or add a remote