1f7a85b7d1
Skill that triggers at the end of every coding session where files changed. Enforces structured session notes with label, narrative, and four fields (What, Why, How, Touches) at one-entry-per-logical-change granularity. Includes reference examples from the Loom project and review-ready CLAUDE.md with key patterns documented.
1.9 KiB
Session Notes Skill
Claude Code skill that enforces structured session note documentation at the end of every coding session.
Architecture
session-notes-skill/
session-notes/
SKILL.md — Skill definition (triggers, format, rules)
references/
example-session.md — Reference examples at correct granularity
Key Patterns
Skill-as-convention enforcer. This skill doesn't generate code or transform files — it enforces a documentation convention. The SKILL.md teaches the agent what to write, when, and at what granularity. The reference file provides concrete examples to calibrate quality.
Granularity rule. The core constraint is one entry per logical change. This is the hardest thing to get right — agents naturally want to summarize. The skill explicitly calls out the anti-pattern (rolling multiple changes into one entry) and provides a "too coarse" vs "right granularity" comparison.
Progressive disclosure. SKILL.md body is always loaded when triggered
(~100 lines). The reference examples in references/ are loaded on
demand when the agent needs to calibrate its output quality.
Session notes live in the project, not the skill. The skill tells
the agent to write to sessions/<slug>.md in whatever project it's
working on. The skill itself doesn't store any session data.
Development
# Package as .skill file
cd session-notes && zip -r ../session-notes.skill SKILL.md references/
Session Notes
After each coding session, append a session entry to
sessions/session-notes-skill.md in this project folder.
See that file for the format convention and existing entries.
Granularity: one entry per logical change. A new function, a new route, a new template, a new config setting, or a bug fix each get their own entry. Don't combine multiple changes into one entry. If it would be a separate item in a code review, it's a separate entry here.