Development skill

Project instruction updater

Updated

Turn the lessons of a working session into a scoped project instruction edit, shown as a diff you approve before anything is written.

Works in: Uses the open Agent Skills format. Codex: candidate, adapter review pending.

When to use

Core workflow

Step 1

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".

Step 2

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.

Step 3

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.

Step 4

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:

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