When to use
- User says "update claude.md" or "add this to context"
- User asks "what should we remember?" or to "save this lesson"
- User wants to persist something learned in the current session for future runs
- A session surfaced a hard-won lesson, a new path, or an infrastructure change
Core workflow
Scan the conversation
Look for the signals that mark something worth keeping: "fixed", "the issue was", "turns out", "deployed", "configured", "new endpoint", "doesn't work", "workaround".
Categorize: durable facts only
Resolve the canonical AGENTS.md or CLAUDE.md file, then route durable lessons, infrastructure changes, and workflows to the right sections. Transient session notes stay out.
Build the exact diff
Produce a unified diff against the canonical project instruction file showing the precise lines and sections to change. The diff is what gets approved, not a summary of it.
Present for approval
Show the diff, then a short per-category summary. Nothing is written until the user approves the exact edits.
What it captures
Hard-won lessons
Non-obvious causes from debugging, workarounds for tool limits, anti-patterns found through failure.
Infrastructure changes
New services, endpoints, paths, or credential pointers (where a secret lives, never the value).
New workflows
Commands that solve recurring problems and multi-step processes worth repeating.
Updated information
Changed ports, IPs, or URLs, new capabilities, and deprecated or removed features.
You approve a diff, not a summary
The approval gate shows the exact patch first, so you can see every line before it lands:
## Proposed project instruction updates
```diff
--- a/AGENTS.md
+++ b/AGENTS.md
@@ Hard-won lessons @@
### Hard-won lessons
+- Plain `timeout` kills the Node tree; use `timeout --foreground` in tmux.
```
Summary of the diff above:
- Hard-won lessons: timeout --foreground note
Apply this diff? Nothing is written until you approve.
What stays out of project instructions
A project instruction file is checked into git and loads as standing context, so it is for durable, infrequently-changing facts, not a running log. The skill keeps these out:
- Transient "what we did today" session summaries
- Anything that changes frequently
- Things the client learns over time through corrections
Those belong in the client's memory feature (in Claude Code, auto memory at ~/.claude/projects/<project>/memory/) or a gitignored local notes file (in Claude Code, CLAUDE.local.md). This mirrors the project-memory skill's guidance.
Installation
# Recommended: install the dev-toolkit plugin
/plugin marketplace add jamditis/claude-skills-journalism
/plugin install dev-toolkit@claude-skills-journalism
# Or copy just this skill from the plugin tree
git clone https://github.com/jamditis/claude-skills-journalism.git
mkdir -p ~/.claude/skills ~/.agents/skills
cp -r claude-skills-journalism/dev-toolkit/skills/claude-md-updater ~/.claude/skills/ # Claude Code
cp -r claude-skills-journalism/dev-toolkit/skills/claude-md-updater ~/.agents/skills/ # Codex
Or browse this skill in the GitHub repository.
Related skills
Keep context current without the bloat
Durable lessons in, transient noise out, every edit shown as a diff before it's written.
View on GitHub