Agent-Skills.md

Agent Skills: Agent Changelog

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.

UncategorizedID: petekp/claude-skills/agent-changelog

Repository

petekp/claude-skills
petekpLicense: MIT
143

Install this agent skill to your local

pnpm dlx add-skill https://github.com/petekp/claude-code-setup/tree/HEAD/skills/agent-changelog

Skill Files

Browse the full folder contents for agent-changelog.

Download Skill

Loading file tree…

skills/agent-changelog/SKILL.md

Skill Metadata

Name
agent-changelog
Description
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.

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:

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:

# 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