Docs Updater

Universal Documentation Updater

Analyzes git changes since the latest release tag and updates the documentation files that should change with them.

Overview

Use git history to identify release-relevant changes, then update README.md, CHANGELOG.md, and any relevant documentation folders. Keep the workflow focused on explicit user approval, precise edits, and repository-specific documentation structure.

When to Use

Use this skill when:

• Preparing release notes or an Unreleased changelog update
• Syncing README.md or documentation after feature work lands
• Reviewing what changed since the last release before a PR or release

Prerequisites

Before starting, verify that the following conditions are met:

# Verify we're in a git repository
git rev-parse --git-dir

# Check that git tags exist
git tag --list | head -5

# Verify documentation files exist
test -f README.md || echo "README.md not found"
test -f CHANGELOG.md || echo "CHANGELOG.md not found"

If no tags exist, inform the user that this skill requires at least one release tag to compare against.

Instructions

Phase 1: Detect Last Release Version

Goal: Identify the latest released version to compare against.

Actions:

1. Detect the comparison baseline and display it:

LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)

if [ -z "$LATEST_TAG" ]; then
    echo "No git tags found. This skill requires at least one release tag."
    echo "Please create a release tag first (e.g., git tag -a v1.0.0 -m 'Initial release')"
    exit 1
fi

CURRENT_BRANCH=$(git branch --show-current)
VERSION=$(echo "$LATEST_TAG" | sed -E 's/^[^0-9]*([0-9]+\.[0-9]+\.[0-9]+).*/\1/')

echo "Latest release tag: $LATEST_TAG"
echo "Version detected: $VERSION"
echo "Comparing: $LATEST_TAG -> $CURRENT_BRANCH"

Phase 2: Perform Git Diff Analysis

Goal: Analyze all changes between the last release and current branch.

Actions:

1. Get the commit range and statistics:

# Get commit count between tag and HEAD
COMMIT_COUNT=$(git rev-list --count ${LATEST_TAG}..HEAD 2>/dev/null || echo "0")
echo "Commits since $LATEST_TAG: $COMMIT_COUNT"

# Get file change statistics
git diff --stat ${LATEST_TAG}..HEAD

2. Extract commit messages for analysis:

# Get all commit messages in the range
COMMITS=$(git log ${LATEST_TAG}..HEAD --pretty=format:"%h|%s|%b" --reverse)

# Display commits for review
echo "$COMMITS"

3. Get detailed file changes:

# Get list of changed files
CHANGED_FILES=$(git diff --name-only ${LATEST_TAG}..HEAD)

# Show add/modify/delete status for quick categorization
git diff --name-status ${LATEST_TAG}..HEAD

4. Identify component areas based on file paths:

# Detect which components/areas changed
echo "$CHANGED_FILES" | grep -E "^plugins/" | cut -d'/' -f2 | sort -u

Phase 3: Discover Documentation Structure

Goal: Identify all relevant documentation locations in the project.

Actions:

1. Find standard documentation folders:

# Check for common documentation locations
DOC_FOLDERS=()

[ -d "docs" ] && DOC_FOLDERS+=("docs/")
[ -d "documentation" ] && DOC_FOLDERS+=("documentation/")
[ -d "doc" ] && DOC_FOLDERS+=("doc/")

# Find plugin-specific docs
for plugin_dir in plugins/*/; do
    if [ -d "${plugin_dir}docs" ]; then
        DOC_FOLDERS+=("${plugin_dir}docs/")
    fi
done

echo "Documentation folders found:"
printf '  - %s\n' "${DOC_FOLDERS[@]}"

2. Identify existing documentation files:

# Check for standard doc files
DOC_FILES=()

[ -f "README.md" ] && DOC_FILES+=("README.md")
[ -f "CHANGELOG.md" ] && DOC_FILES+=("CHANGELOG.md")
[ -f "CONTRIBUTING.md" ] && DOC_FILES+=("CONTRIBUTING.md")
[ -f "docs/GUIDE.md" ] && DOC_FILES+=("docs/GUIDE.md")

echo "Documentation files found:"
printf '  - %s\n' "${DOC_FILES[@]}"

Phase 4: Generate CHANGELOG Updates

Goal: Create categorized changelog entries following Keep a Changelog standard.

Actions:

1. Parse commits using conventional commit semantics and map them into Keep a Changelog sections such as Added, Changed, Fixed, Removed, and Security.

2. Read the existing CHANGELOG.md to understand structure, then generate new entries following Keep a Changelog format.

See references/examples.md for detailed bash commands and changelog templates.

Phase 5: Update README.md

Goal: Update the main README with relevant high-level changes.

Actions:

1. Read the current README.md to understand its structure 2. Identify sections needing updates (features list, skills/agents, setup instructions, version references) 3. Apply updates using Edit tool: preserve structure, maintain tone, update version numbers

Phase 6: Update Documentation Folders

Goal: Propagate changes to relevant documentation in docs/ folders.

Actions:

1. For each documentation folder found, check for files referencing changed code 2. Map changed files to their documentation 3. Generate updates: add new feature docs, update API references, fix outdated examples

See references/examples.md for detailed discovery patterns and update strategies.

Phase 7: Present Changes for Review

Goal: Show the user what will be updated before applying changes.

Actions:

1. Present a summary of proposed changes:

## Proposed Documentation Updates

### Version Information
- Previous release: $LATEST_TAG
- Current branch: $CURRENT_BRANCH
- Commits analyzed: $COMMIT_COUNT

### Files to Update
- [ ] CHANGELOG.md - Add new version section with categorized changes
- [ ] README.md - Update [specific sections]
- [ ] docs/[specific files] - Update documentation

### Summary of Changes
**Added**: N new features
**Changed**: N modifications
**Fixed**: N bug fixes
**Breaking**: N breaking changes

2. Ask the user for confirmation via AskUserQuestion:

• Confirm which files to update
• Ask if any changes should be modified
• Get approval to proceed

Phase 8: Apply Documentation Updates

Goal: Write the approved updates, then verify they landed correctly.

Actions:

1. Update CHANGELOG.md:

# Read current changelog
CURRENT_CHANGELOG=$(cat CHANGELOG.md)

# Prepend new section
cat > CHANGELOG.md << 'EOF'
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]
[New content goes here]

[Rest of existing changelog]
EOF

2. Update README.md using Edit tool:

• Make targeted edits to specific sections
• Preserve overall structure
• Update version numbers if applicable

3. Update documentation files:

# For each documentation file that needs updates
# Use Edit tool to make precise changes

4. Validate the applied changes:

# Confirm key files still exist after editing
test -f CHANGELOG.md && echo "CHANGELOG.md present"
test -f README.md && echo "README.md present"

# Review the scope of markdown changes
git diff --stat -- '*.md'

# Spot-check the actual content written
git diff -- '*.md' | sed -n '1,240p'

5. If the repository already defines documentation or markdown validation commands, run them before finishing.

Examples

Example 1: Update After Feature Development

User request: "Update docs for the new features I just added"

Output:

• Latest tag: v2.4.1 → Current branch: develop
• 5 commits analyzed
• CHANGELOG entry generated for new Spring Boot Actuator skill
• README.md skills list updated

Example 2: Prepare Release Documentation

User request: "Prepare documentation for v2.5.0 release"

Output:

• 47 commits analyzed since v2.4.1
• 15 features, 8 fixes, 3 breaking changes detected
• Complete CHANGELOG.md [2.5.0] section generated
• README.md and plugin docs updated

Example 3: Incremental Sync

User request: "Sync docs, I've made some changes"

Output:

• 2 commits analyzed
• Focused CHANGELOG update for github-issue-workflow skill changes
• No README or plugin doc updates needed

See references/examples.md for detailed session transcripts and troubleshooting.

Best Practices

1. Preview before writing, verify after writing: Show the plan first, then confirm the final diff after edits 2. Follow Keep a Changelog: Maintain consistent changelog formatting 3. Categorize properly: Use correct categories (Added, Changed, Fixed, etc.) 4. Be specific: Include plugin/component names in changelog entries 5. Preserve structure: Maintain existing documentation structure and style 6. Reference commits: Include commit hashes for traceability when helpful 7. Handle breaking changes: Clearly highlight breaking changes with migration notes 8. Update version refs: Keep version numbers consistent across documentation

Constraints and Warnings

1. Requires git tags: This skill only works if the repository has at least one release tag 2. Read-only analysis: The skill analyzes changes but asks before writing 3. Manual review required: Generated changelog entries should be reviewed for accuracy 4. Conventional commits: Works best with projects using conventional commit format 5. Does not create tags: This skill updates docs but does not create release tags 6. No auto-commit: Documentation changes are prepared but not committed automatically 7. Project-specific patterns: Some projects may have custom changelog formats to respect 8. File paths: All file paths use forward slashes (Unix style) for cross-platform compatibility

Universal Documentation Updater - Usage Examples

This document provides practical examples of using the Universal Documentation Auto-Updater skill in various scenarios.

Table of Contents

1. Basic Workflow 2. Release Preparation 3. Continuous Documentation Sync 4. Multi-Plugin Projects 5. Troubleshooting

Basic Workflow

Scenario: Adding a New Feature

After implementing a new feature and committing your changes:

User: "Update docs for the new DynamoDB skill I just added"

Expected Output:

Latest release tag: v2.4.1
Current branch: develop
Version detected: 2.4.1
Comparing: v2.4.1 -> develop

Commits since v2.4.1: 3

Changed files:
  A plugins/developer-kit-typescript/skills/dynamodb-toolbox-patterns/SKILL.md
  A plugins/developer-kit-typescript/skills/dynamodb-toolbox-patterns/references/schema.md
  M plugins/developer-kit-typescript/.claude-plugin/plugin.json

Generated CHANGELOG Entry:

## [Unreleased]

### Added
- **New DynamoDB-Toolbox v2 skill** (`developer-kit-typescript`):
  - `dynamodb-toolbox-patterns`: TypeScript patterns for DynamoDB-Toolbox v2
  - Includes schema/table/entity modeling and query/scan access patterns

Release Preparation

Scenario: Preparing for v2.5.0 Release

Before creating a release tag, ensure all documentation is up to date:

User: "Prepare documentation for v2.5.0 release"

Analysis Summary:

Latest release tag: v2.4.1
Commits since v2.4.1: 47

Commit breakdown:
- Features: 15
- Bug fixes: 8
- Breaking changes: 3
- Documentation: 12
- Refactoring: 9

Proposed Documentation Updates:

## Proposed Documentation Updates

### Version Information
- Previous release: v2.4.1
- Current branch: main
- Commits analyzed: 47

### Files to Update
- [x] CHANGELOG.md - Add [2.5.0] section with date
- [x] README.md - Update skills list, version badges
- [ ] plugins/developer-kit-java/docs/ - No changes needed
- [ ] plugins/developer-kit-aws/docs/ - Update SAM examples

### Summary of Changes
**Added**: 5 new skills, 10 new features
**Changed**: 3 component enhancements
**Fixed**: 8 bug fixes
**Breaking**: 3 breaking changes (migration notes required)

Continuous Documentation Sync

Scenario: Regular Documentation Maintenance

Keeping documentation synchronized after regular development iterations:

User: "Sync documentation with latest changes"

Quick Analysis (Small Changes):

Latest release tag: v2.5.0
Commits since v2.5.0: 5

Changes:
  M plugins/developer-kit-core/skills/github-issue-workflow/SKILL.md
  M plugins/developer-kit-core/commands/devkit.brainstorm.md

Generated Update:

## [Unreleased]

### Changed
- **GitHub Issue Workflow skill**: Enhanced security handling for untrusted issue content
- **Brainstorm command**: Added AskUserQuestion gates for user confirmation

Multi-Plugin Projects

Scenario: Developer Kit Multi-Plugin Structure

When working with a multi-plugin repository like the developer-kit:

User: "Update all docs across all plugins"

Discovered Documentation Structure:

Documentation folders found:
  - plugins/developer-kit-java/docs/
  - plugins/developer-kit-typescript/docs/
  - plugins/developer-kit-aws/docs/
  - plugins/developer-kit-python/docs/
  - plugins/developer-kit-php/docs/

Documentation files found:
  - README.md
  - CHANGELOG.md
  - CONTRIBUTING.md
  - CLAUDE.md

Per-Plugin Changes Detected:

## [Unreleased]

### Added

**developer-kit-java:**
- `spring-boot-actuator`: Production-ready monitoring patterns
- `spring-boot-cache`: Caching configuration patterns

**developer-kit-typescript:**
- `dynamodb-toolbox-patterns`: DynamoDB-Toolbox v2 integration
- `drizzle-orm-patterns`: Drizzle ORM comprehensive patterns

**developer-kit-aws:**
- `aws-sam-bootstrap`: SAM project initialization patterns

### Changed

**developer-kit-core:**
- Enhanced all devkit commands with mandatory user confirmation gates
- Added Universal Documentation Updater skill

### Fixed

**developer-kit-java:**
- Fixed unit-test-config-properties skill examples

**developer-kit-typescript:**
- Fixed react-patterns skill hooks documentation

Troubleshooting

No Tags Found

Error:

No git tags found. This skill requires at least one release tag.

Solution:

# Create an initial release tag
git tag -a v1.0.0 -m "Initial release"

# Or tag the latest commit as a release
git tag -a v0.1.0 -m "Pre-release"

Empty Diff Results

Symptom: No changes detected despite recent commits

Possible causes: 1. Current branch is at the same commit as the latest tag 2. No commits exist between tag and HEAD

Verification:

# Check commit count
git rev-list --count v2.4.1..HEAD

# Check current branch vs tag
git log v2.4.1..HEAD --oneline

Non-Conventional Commits

Issue: Commits don't follow conventional commit format

Example problematic commits:

abc1234: updated stuff
def5678: fix bug
ghi9012: add feature

Result: Categorization may be less accurate

Workaround: The skill will attempt to categorize by message content, but results may be less precise. Consider using conventional commits for better changelog generation.

Custom Changelog Format

Issue: Project uses a different changelog format than Keep a Changelog

Solution: 1. The skill generates entries following Keep a Changelog standard 2. Review the generated output and adapt to your project's format 3. Consider migrating to Keep a Changelog for consistency

Advanced Usage

Filtering by Component

To focus on specific plugin changes:

# Get changes for specific plugin only
git diff v2.4.1..HEAD -- plugins/developer-kit-java/

# Get changes for specific file types
git diff v2.4.1..HEAD -- "*.md"

Custom Version Detection

For projects with non-standard tag formats:

# Get tags matching specific pattern
git tag -l "v*" | sort -V | tail -1

# Get tags with custom format
git tag -l "release-*" | sort -V | tail -1

Verifying Generated Changelog

Before committing changes:

# Preview changelog changes
git diff CHANGELOG.md

# Verify markdown syntax
# (Use markdown linter if available)

Best Practices

1. Always verify before writing: Show the user what will change before applying updates 2. Follow Keep a Changelog: Maintain consistent changelog formatting 3. Categorize properly: Use correct categories (Added, Changed, Fixed, etc.) 4. Be specific: Include plugin/component names in changelog entries 5. Preserve structure: Maintain existing documentation structure and style 6. Reference commits: Include commit hashes for traceability when helpful 7. Handle breaking changes: Clearly highlight breaking changes with migration notes 8. Update version refs: Keep version numbers consistent across documentation

Constraints and Warnings

1. Requires git tags: This skill only works if the repository has at least one release tag 2. Read-only analysis: The skill analyzes changes but asks before writing 3. Manual review required: Generated changelog entries should be reviewed for accuracy 4. Conventional commits: Works best with projects using conventional commit format 5. Does not create tags: This skill updates docs but does not create release tags 6. No auto-commit: Documentation changes are prepared but not committed automatically 7. Project-specific patterns: Some projects may have custom changelog formats to respect 8. File paths: All file paths use forward slashes (Unix style) for cross-platform compatibility

Tips for Best Results

1. Use Conventional Commits: Follow conventional commit format for better categorization 2. Commit Frequently: Small, focused commits make for clearer changelog entries 3. Tag Releases: Always create tags for releases (not just branches) 4. Review Generated Content: Always review and edit generated changelog entries 5. Keep Descriptive Commit Messages: Include context in commit messages for better documentation

Sample Session

User: Update docs since last release

Claude: Let me analyze the changes since the last release...

[Latest release tag: v2.4.1]
[Commits analyzed: 12]

I found the following changes:
- 3 new skills added
- 2 bug fixes
- 1 documentation update

Here's the proposed changelog entry:

## [Unreleased]

### Added
- **New Universal Documentation Updater skill** (`developer-kit-core`):
  - Automatically updates project documentation based on git diff analysis
  - Supports CHANGELOG.md, README.md, and documentation folders

### Fixed
- **Plugin discovery**: Fixed marketplace.json missing developer-kit-tools entry

Should I apply these changes to CHANGELOG.md and README.md?

User: Yes, apply changes

Claude: Updating documentation files...

Changes applied:
✓ Updated CHANGELOG.md
✓ Updated README.md skills list

Git diff preview:
[Shows git diff of changes]