agent-changelog

Original：🇺🇸 English

Translated

Compile an agent-optimized changelog by cross-referencing git history with plans and documentation. Use when asked to "update changelog", "compile history", "document project evolution", or proactively after major milestones, architectural changes, or when stale/deprecated information is detected that could confuse coding agents.

1installs

Sourcepetekp/claude-code-setup

Added on2026-02-07

NPX Install

npx skill4agent add petekp/claude-code-setup agent-changelog

SKILL.md Content

View Translation Comparison →

Agent Changelog

Compile a chronological record of key decisions, architectural changes, and project evolution optimized for coding agent context-building.

Output

Write to

AGENT_CHANGELOG.md

in the project root. This file helps agents:

Understand key decisions and their rationale
Identify deprecated patterns/approaches to avoid
Grasp the trajectory from past to present to likely future
Detect stale documentation that contradicts current reality

Workflow

1. Gather Sources

Collect information from these sources in parallel:

Git history:

bash

git log --oneline --since="6 months ago" | head -100
git log --all --oneline --grep="BREAKING" --grep="deprecate" --grep="remove" --grep="migrate" -i
git tag -l --sort=-creatordate | head -20

Documentation:

```
.claude/plans/
```
- implementation plans and decisions
```
CLAUDE.md
```
- project instructions
```
README.md
```
- project overview
```
docs/
```
or similar documentation directories
```
CHANGELOG.md
```
if exists (traditional changelog)

Code signals:

```
@deprecated
```
annotations
```
TODO
```
,
```
FIXME
```
,
```
HACK
```
comments with dates
Migration files, upgrade scripts

2. Identify Key Events

Extract events that matter for agent understanding:

Always include:

Architectural decisions (new patterns, removed patterns)
Breaking changes and migrations
Deprecated features/approaches
Major dependency changes
Directory structure changes
API changes (internal or external)

Include if significant:

New features that change how agents should work
Bug fixes that reveal incorrect assumptions
Performance changes that affect approach recommendations

Skip:

Minor bug fixes
Cosmetic changes
Routine dependency updates
Individual feature additions (unless architectural)

3. Cross-Reference for Contradictions

For each significant event, check if existing documentation contradicts it:

Event: "Migrated from Redux to Zustand" (commit abc123, 2024-03)

Check: Does any documentation still reference Redux patterns?
- README.md mentions Redux? → Flag as STALE
- CLAUDE.md suggests Redux approach? → Flag as STALE
- Old tutorials in docs/? → Flag as STALE

Track contradictions in a "Stale Information Detected" section.

4. Write the Changelog

Structure the output file:

markdown

# Agent Changelog

> This file helps coding agents understand project evolution, key decisions,
> and deprecated patterns. Updated: [DATE]

## Current State Summary

[2-3 sentences on where the project is NOW - the authoritative current architecture]

## Stale Information Detected

[List any documentation that contradicts current reality - agents should ignore these until fixed]

| Location | States | Reality | Since |
|----------|--------|---------|-------|
| docs/auth.md | "Uses JWT tokens" | Migrated to sessions | 2024-06 |

## Timeline

### [YEAR-MONTH] - [Brief Title]

**What changed:** [Factual description]

**Why:** [Decision rationale if known from plans/commits]

**Agent impact:** [How this affects how agents should work in the codebase]

**Deprecated:** [What approaches/patterns should agents avoid]

---

[Repeat for each significant event, reverse chronological]

## Deprecated Patterns

[Consolidated list of things agents should NOT do, with what to do instead]

| Don't | Do Instead | Deprecated Since |
|-------|------------|------------------|
| Use `OldService` | Use `NewService` | 2024-08 |

## Trajectory

[Brief note on where the project appears to be heading based on recent changes and plans]

5. Validate and Update

After writing:

Read existing
```
AGENT_CHANGELOG.md
```
if present and merge, don't duplicate
Verify dates against git history
Ensure "Stale Information Detected" section is actionable

When to Proactively Run

Suggest running this skill when:

A major refactor or migration just completed
Plans in
```
.claude/plans/
```
were recently executed
Multiple architectural decisions happened in quick succession
Detected documentation that seems to contradict code reality
Starting work on a codebase after a long gap
Onboarding to an unfamiliar codebase

Guidelines

Prioritize accuracy over completeness—wrong history is worse than incomplete
Include rationale when available (commit messages, plan docs)
Be specific about what agents should avoid, not just what changed
Keep entries concise—this is reference material, not storytelling
Date everything to help agents judge relevance