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.
54 lines
1.9 KiB
Markdown
54 lines
1.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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.
|