Travis Herbranson 3fe54781a0 docs: add README

CLAUDE.md was current; repo just lacked a user-facing README.

README covers what the skill enforces (structured session notes at
end-of-session), the granularity rule (one entry per logical change),
install paths (.skill zip vs source symlink), how agents use it,
repo layout, and the packaging command.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-20 07:41:19 -04:00

2.8 KiB

Raw Blame History

session-notes-skill

A Claude Code skill that enforces structured session-note documentation at the end of every coding session.

The skill doesn't generate code or transform files. It teaches the agent what to write, when, and at what granularity — so each meaningful change in a session lands as a separate, parseable entry in the project's sessions/<slug>.md file.

Designed to pair with the Loom dashboard (the work-index-dashboard reader) and with project-local review workflows that scan session notes for context.

What it does

Triggers automatically at end-of-session when the agent has made file changes. Also triggers on explicit prompts: "write session notes", "log this session", "document what we did", "wrap up", "end of session".
Enforces granularity: one entry per logical change. New function, new route, new template, new config setting, bug fix — each get their own entry. The skill spec calls out the "combine everything into one paragraph" anti-pattern and provides side-by-side too-coarse vs. right-granularity examples.
Writes to the project, not the skill: the agent appends entries to sessions/<slug>.md in the project it's currently working in. This skill repo stores no session data.

Install

The skill ships as a zip: session-notes.skill.

From the packaged .skill:

cp session-notes.skill ~/.claude/skills/

From the source tree (for development):

ln -s "$(pwd)/session-notes" ~/.claude/skills/session-notes

Once installed, the skill self-loads on every session where the agent modifies files. No flags or /commands needed.

How agents use it

When the skill fires, the agent:

Reads SKILL.md (always loaded — the format + rules).
Loads references/example-session.md on demand to calibrate the granularity if the changes are non-trivial.
Appends entries to sessions/<project-slug>.md in the current project. Creates the file if it doesn't exist.

Granularity, restated

One entry per logical change. If it would be a separate item in a code review, it's a separate entry here.

This is the rule the skill is built around — see session-notes/references/example-session.md for what it looks like in practice.

Repo layout

session-notes-skill/
  session-notes/
    SKILL.md                     # Skill definition (triggers + format + granularity rule)
    references/
      example-session.md         # Calibration examples (good vs. too-coarse)
  session-notes.skill            # Packaged zip (regenerate after edits)
  sessions/
    session-notes-skill.md       # The skill dogfoods itself here
  CLAUDE.md                      # Agent notes
  README.md                      # This file

Packaging a release

cd session-notes && zip -r ../session-notes.skill SKILL.md references/

2.8 KiB Raw Blame History