Claude Code Plugins

Community-maintained marketplace

Feedback

changelog-updater

@phamhung075/4genthub-hooks
1
0

Update CHANGELOG.md and TEST-CHANGELOG.md with new entries following Keep a Changelog format and token optimization principles. Use when adding changes to the changelog, documenting new features, fixes, or optimizations.

Install Skill

1Download skill
2Enable skills in Claude

Open claude.ai/settings/capabilities and find the "Skills" section

3Upload to Claude

Click "Upload skill" and select the downloaded ZIP file

Note: Please verify skill by going through its instructions before using it.

SKILL.md

name changelog-updater
description Update CHANGELOG.md and TEST-CHANGELOG.md with new entries following Keep a Changelog format and token optimization principles. Use when adding changes to the changelog, documenting new features, fixes, or optimizations.
allowed-tools Read, Edit, Grep

Changelog Updater

Updates CHANGELOG.md following the optimized format established in this project.

When to Use

  • After completing features, fixes, or optimizations
  • When user requests "update changelog" or "add to changelog"
  • When documenting architectural changes or token optimizations

Format Requirements

File Structure

## [Unreleased]

### Added
**Feature Name** (YYYY-MM-DD)
- Bullet points describing what was added
- Impact metrics if applicable

### Changed
**Change Name** (YYYY-MM-DD)
- Bullet points describing what changed
- Before/after metrics when relevant

### Fixed
**Fix Name** (YYYY-MM-DD)
- Bullet points describing what was fixed
- Files modified and root cause when relevant

Token Optimization Principles

Apply these techniques when writing changelog entries:

Technique Example Benefit
Tables over prose Use tables for comparisons/metrics 60-80% reduction
Pattern statements "Philosophy: 'Don't echo back what caller knows'" 80% reduction
Consolidated redundancy Combine similar entries into themed sections 50-70% reduction
One perfect example Show one clear example instead of multiple 65-70% reduction
Eliminate teaching State facts, don't explain basics 80% reduction

Entry Guidelines

Good entry structure:

**Feature Name - Key Metric** (2025-11-03)
- What was done (1-2 lines)
- Technical details if complex (2-3 lines max)
- Impact: tokens saved, performance gain, etc.
- Files modified: path/to/file.ext:lines

Avoid:

  • Excessive technical detail (put in ai_docs/ instead)
  • Redundant explanations
  • Multiple paragraphs per bullet
  • Teaching basic concepts

Instructions

Step 1: Read Current Changelog

# Read just the Unreleased section
grep -A 100 "## \[Unreleased\]" CHANGELOG.md | head -100

Step 2: Identify Correct Section

  • Added: New features, capabilities, documentation, tools
  • Changed: Modifications to existing functionality, optimizations, refactors
  • Fixed: Bug fixes, error corrections, path updates

Step 3: Format Entry

Use this template:

**Title - Key Metric** (YYYY-MM-DD)
- Primary change description
- Technical implementation (if needed)
- Impact: quantifiable benefit
- Files: modified locations

For token optimizations, use table format:

**Optimization Suite - Total Savings** (YYYY-MM-DD)
| Component | Savings | Type | Impact |
|-----------|---------|------|--------|
| Item 1 | X tokens | Per session | Description |
| Item 2 | Y tokens | One-time | Description |
| **TOTAL** | **Z tokens** | **Per session** | **% of budget** |

Step 4: Add Entry

  1. Find the correct section (### Added, ### Changed, or ### Fixed)
  2. Add entry at the TOP of that section (after the header)
  3. Maintain chronological order (newest first)
  4. Ensure proper blank lines between entries

Step 5: Verify Format

Check:

  • Date is today's date (YYYY-MM-DD)
  • Entry is concise (<10 lines unless complex optimization)
  • Metrics included when applicable
  • No duplicate section headers
  • Proper markdown formatting

Examples

Example 1: Feature Addition

### Added

**Agent Skills System** (2025-11-03)
- Created changelog-updater skill for consistent CHANGELOG.md updates
- Format: YAML frontmatter + markdown instructions + examples
- Features: Token optimization guidelines, format validation, Keep a Changelog compliance
- Location: .claude/skills/changelog-updater/SKILL.md

Example 2: Optimization

### Changed

**Agent Files Token Optimization - 55.7% Reduction** (2025-11-03)
- Rewrote all 31 `.claude/agents/*.md` files from verbose to minimal YAML
- Line reduction: 1,878 → 832 lines (1,046 removed, 55.7% savings)
- Architecture: Metadata only in files, full prompts loaded via MCP
- Impact: ~2,000-2,500 tokens saved per agent file load

Example 3: Bug Fix

### Fixed

**Claude Hooks Path References** (2025-11-03)
- Updated config_validator.py path construction (scripts/claude-hooks → .claude/hooks)
- Fixed _find_project_root() traversal logic for new structure
- Files: .claude/hooks/utils/config_validator.py:20,78-83
- Result: Hooks load correctly, file protection active, no startup errors

Example 4: Multi-Component Table

### Changed

**Token Optimization Suite - 21-28k Tokens Saved** (2025-11-03)
| Optimization | Savings | Type | Impact |
|--------------|---------|------|--------|
| MCP Tool Descriptions | 10,600 | Startup | 60-70% description reduction |
| Dead Code Prevention | 4,500-7,000 | Per session | Removed unused services |
| MinimalResponseSerializer | 6,000-8,000 | Per session | Eliminated echo responses |
| **TOTAL** | **21,720-26,580** | **Per session** | **10.9-13.3% of 200k budget** |

Best Practices

Be Concise

Good: "Optimized agent files: 1,878 → 832 lines (55.7% reduction)"

Too verbose: "We performed a comprehensive optimization of the agent file system by analyzing each of the 31 agent files and rewriting them to use a more concise format that reduced the total line count from 1,878 lines down to 832 lines which represents a 55.7% reduction in file size..."

Quantify Impact

Always include metrics when available:

  • Token savings (per session, one-time, % of budget)
  • Line reduction (before → after, % saved)
  • Performance gains (time, memory, response size)
  • File counts (files modified, lines changed)

Use Active Voice

Good: "Removed EnrichmentService (566 lines)"

Avoid: "EnrichmentService was removed (566 lines)"

Group Related Changes

If multiple related changes happened together, combine them:

Good (grouped):

**Hooks System Migration** (2025-11-03)
- Migrated from scripts/claude-hooks/ to .claude/hooks/
- Updated all path references in config_validator, pre_tool_use, test paths
- File system protection, documentation enforcement operational

Avoid (separate):

**Hooks Path Update** (2025-11-03)
- Migrated hooks to .claude/hooks/

**Config Validator Fix** (2025-11-03)
- Updated config_validator paths

**Test Paths Update** (2025-11-03)
- Fixed test path references

Validation Checklist

Before finalizing the changelog entry:

  • Format: Follows Keep a Changelog structure
  • Section: Entry in correct section (Added/Changed/Fixed)
  • Date: Uses YYYY-MM-DD format
  • Concise: Entry is scannable (<10 lines for most changes)
  • Metrics: Includes quantifiable impact when available
  • Files: References specific files/lines when relevant
  • Token Optimized: Uses tables, patterns, consolidated format
  • No Duplicates: Doesn't duplicate existing section headers
  • Markdown: Proper formatting (**, -, backticks for code)

Supporting Files

For detailed guidance, see:

  • EXAMPLES.md - Real-world examples from this project (189 lines, all patterns covered)
  • TEMPLATES.md - Copy-paste templates for quick entry creation (267 lines, fill placeholders)
  • VALIDATION.md - Validation commands, checklists, quality checks (212 lines, pre-commit verification)

Reference