Agent-Skills.md

Agent Skills: journal

Use at session start, after context compaction, and before session end. Owns session journals in `.sandbox/journals/`: when to create one, what prior context to read, what to log, and how to leave a resumable handoff

UncategorizedID: l-lin/dotfiles/journal

Repository

l-lin/dotfiles
l-lin
172

Install this agent skill to your local

pnpm dlx add-skill https://github.com/l-lin/dotfiles/tree/HEAD/home-manager/modules/share/ai/.config/ai/skills/journal

Skill Files

Browse the full folder contents for journal.

Download Skill

Loading file tree…

home-manager/modules/share/ai/.config/ai/skills/journal/SKILL.md

Skill Metadata

Name
journal
Description
"Use at session start, after context compaction, and before session end. Owns session journals in `.sandbox/journals/`: when to create one, what prior context to read, what to log, and how to leave a resumable handoff"

Journal is session memory. It is not a runbook and not generalized reusable learning.

Default posture

Keep journaling useful, not ceremonial.

  • For trivial, isolated Q&A, do the minimum
  • For file changes, investigations, multi-step work, or anything likely to survive compaction or handoff, keep a real journal
  • If a session starts small and becomes complex, open the journal then and add one catch-up entry

Session start

  1. Ensure .sandbox/journals/ exists
  2. Read the newest journal first
  3. If the newest journal looks related, read only the extra journal(s) needed to orient
  • Use a light heuristic: same files, same repo area, same problem, or explicit continuation
  1. Decide whether this session needs its own journal file. Create one when any of these are true:
  • work will touch files or state
  • the task is multi-step or investigative
  • prior context matters
  1. Default file name: .sandbox/journals/YYYY-MM-DD-<kebab-description>.md
  • Keep the slug short and task-specific
  • If that exact name already exists for a different session, append -2, -3, and so on
  • If a higher-priority instruction defines a different naming scheme, use that scheme and keep the same journal policy
  1. If the session is complex or resumed, start with a tiny working summary:
  • current goal
  • most important prior fact or decision
  • immediate next action

During work

Append an entry only when it would help a future agent or your post-compaction self.

Good reasons to write:

  • a decision changed the plan, with why
  • evidence confirmed or killed a hypothesis
  • you edited non-trivial files, and why
  • you hit a dead end worth not repeating
  • you uncovered an open question, blocker, risk, or exact next step

Do not write:

  • routine browsing or obvious commands
  • long transcripts
  • generic principles that belong in the prompt or napkin
  • speculation without an outcome

Entry shape

Use the smallest format that preserves the signal.

## YYYY-MM-DD HH:MM — short summary
- Evidence: `command` -> decisive excerpt
- Decision: what changed, and why
- Files: `path` — why it matters
- Dead end: what failed, and what not to retry
- Next: exact next step

Include only the fields that matter. Combine related micro-steps into one entry.

Reversals and supersession

When you reverse an earlier decision, mark both sides

In the new entry:

> ⚠️ Supersedes: `YYYY-MM-DD HH:MM — prior summary` (reason)

In the old entry:

> ⚠️ Superseded by: `YYYY-MM-DD HH:MM — new summary`

If updating the old entry is impractical, at least mark the new one clearly.

Before session end

Before ending a non-trivial session, append a short handoff entry that says:

  • where the work stands
  • what is verified
  • what remains risky or unresolved
  • the exact next action

A good handoff should let the next agent continue without re-reading the whole conversation.