Project instruction updater
Analyze the current conversation to identify information worth persisting in the project's instruction file, then propose the edits for approval before writing anything.
Resolve the target before drafting:
- If
AGENTS.md exists, update it. In Claude Code, if there is no CLAUDE.md, also propose a one-line CLAUDE.md import of @AGENTS.md. Claude Code loads CLAUDE.md, not AGENTS.md.
- If only
CLAUDE.md exists, update it.
- If both exist and either imports the other, update the imported canonical file.
- If neither exists, create
AGENTS.md. In Claude Code, also propose the one-line CLAUDE.md import.
What to look for
1. Hard-won lessons
- Debugging sessions that revealed non-obvious causes
- Workarounds for platform or tool limitations
- Anti-patterns discovered through failure
- "The real problem was..." moments
2. New infrastructure
- New services deployed
- New endpoints or URLs
- New file paths or directories
- New credentials or tokens (reference only, never the values)
3. New workflows
- Commands that solve recurring problems
- Multi-step processes that work well
- Integration patterns between systems
4. Updated information
- Changed ports, IPs, or URLs
- New capabilities added to existing systems
- Deprecated or removed features
Analysis process
Scan the conversation for keywords:
- "fixed", "solved", "the issue was", "turns out"
- "deployed", "set up", "configured", "installed"
- "new endpoint", "new service", "new path"
- "doesn't work", "limitation", "workaround"
Categorize findings. Only durable facts belong in the project instruction file:
- Hard-won lessons go to the "Hard-won lessons" section
- Infrastructure changes update the relevant section
- New workflows go to the appropriate section
- Transient, session-specific notes do not go in the project instruction file (see "What not to persist")
Build the exact diff. Produce a unified diff against the resolved instruction file showing the precise lines and sections to add or change. This diff is what the user approves, not a summary of it.
Present the diff for approval and write nothing until the user approves.
Output format
Show the exact patch first, then a short summary grouped by category:
## Proposed project instruction updates
```diff
--- a/AGENTS.md
+++ b/AGENTS.md
@@ section being changed @@
existing context line
+new durable lesson, infra fact, or workflow
```
Summary of the diff above:
- Hard-won lessons: [one line, if any]
- Infrastructure updates: [one line, if any]
- New workflows: [one line, if any]
Apply this diff? Nothing is written until you approve.
What not to persist
The project instruction file is team-shared, checked into git, and loaded into agent sessions. Use it for durable, infrequently changing facts, not a running log. Per the project-memory skill, keep these items out:
- Transient "what we did today" session summaries
- Anything that changes frequently
- Things the client learns over time through corrections
Route those to the client's memory feature (in Claude Code, auto memory at
~/.claude/projects/<project>/memory/) or to a gitignored local notes file (in
Claude Code, CLAUDE.local.md). Putting them in shared project instructions
bloats context and loads stale session facts into future sessions.
Rules
- Never add sensitive values. Reference where a credential is stored; never include the actual token.
- Keep it concise. The project instruction file should stay scannable; target under 200 lines.
- Avoid duplication. Check whether the information already exists before adding it.
- Match the existing style. Follow the tone and format of the current file.
- Durable facts only. Persist hard-won lessons, infrastructure facts, and workflows. Session-specific notes belong in client memory or a gitignored local notes file, never the committed project instruction file.
1---2name: claude-md-updater3description: Scans the session for durable lessons and workflows, then proposes scoped project instruction updates. Use for save this lesson or add to context.4metadata:5 source: https://skillmd.com/skills/fridrichmethod/claude-md-updater6---78# Project instruction updater910Analyze the current conversation to identify information worth persisting in the project's instruction file, then propose the edits for approval before writing anything.1112Resolve the target before drafting:13141. If `AGENTS.md` exists, update it. In Claude Code, if there is no `CLAUDE.md`, also propose a one-line `CLAUDE.md` import of `@AGENTS.md`. Claude Code loads `CLAUDE.md`, not `AGENTS.md`.152. If only `CLAUDE.md` exists, update it.163. If both exist and either imports the other, update the imported canonical file.174. If neither exists, create `AGENTS.md`. In Claude Code, also propose the one-line `CLAUDE.md` import.1819## What to look for2021### 1. Hard-won lessons22- Debugging sessions that revealed non-obvious causes23- Workarounds for platform or tool limitations24- Anti-patterns discovered through failure25- "The real problem was..." moments2627### 2. New infrastructure28- New services deployed29- New endpoints or URLs30- New file paths or directories31- New credentials or tokens (reference only, never the values)3233### 3. New workflows34- Commands that solve recurring problems35- Multi-step processes that work well36- Integration patterns between systems3738### 4. Updated information39- Changed ports, IPs, or URLs40- New capabilities added to existing systems41- Deprecated or removed features4243## Analysis process44451. **Scan the conversation** for keywords:46 - "fixed", "solved", "the issue was", "turns out"47 - "deployed", "set up", "configured", "installed"48 - "new endpoint", "new service", "new path"49 - "doesn't work", "limitation", "workaround"50512. **Categorize findings.** Only durable facts belong in the project instruction file:52 - Hard-won lessons go to the "Hard-won lessons" section53 - Infrastructure changes update the relevant section54 - New workflows go to the appropriate section55 - Transient, session-specific notes do **not** go in the project instruction file (see "What not to persist")56573. **Build the exact diff.** Produce a unified diff against the resolved instruction file showing the precise lines and sections to add or change. This diff is what the user approves, not a summary of it.58594. **Present the diff for approval** and write nothing until the user approves.6061## Output format6263Show the exact patch first, then a short summary grouped by category:6465````66## Proposed project instruction updates6768```diff69--- a/AGENTS.md70+++ b/AGENTS.md71@@ section being changed @@72 existing context line73+new durable lesson, infra fact, or workflow74```7576Summary of the diff above:77- Hard-won lessons: [one line, if any]78- Infrastructure updates: [one line, if any]79- New workflows: [one line, if any]8081Apply this diff? Nothing is written until you approve.82````8384## What not to persist8586The project instruction file is team-shared, checked into git, and loaded into agent sessions. Use it for durable, infrequently changing facts, not a running log. Per the project-memory skill, keep these items out:8788- Transient "what we did today" session summaries89- Anything that changes frequently90- Things the client learns over time through corrections9192Route those to the client's memory feature (in Claude Code, auto memory at93`~/.claude/projects/<project>/memory/`) or to a gitignored local notes file (in94Claude Code, `CLAUDE.local.md`). Putting them in shared project instructions95bloats context and loads stale session facts into future sessions.9697## Rules98991. **Never add sensitive values.** Reference where a credential is stored; never include the actual token.1002. **Keep it concise.** The project instruction file should stay scannable; target under 200 lines.1013. **Avoid duplication.** Check whether the information already exists before adding it.1024. **Match the existing style.** Follow the tone and format of the current file.1035. **Durable facts only.** Persist hard-won lessons, infrastructure facts, and workflows. Session-specific notes belong in client memory or a gitignored local notes file, never the committed project instruction file.