# 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`:**

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

**From the source tree** (for development):

```bash
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:

1. Reads `SKILL.md` (always loaded — the format + rules).
2. Loads `references/example-session.md` on demand to calibrate the
   granularity if the changes are non-trivial.
3. 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

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