Agent-Skills.md

Agent Skills: Add Changelog Entry

Adds changelog entries to readme.txt following keepachangelog format. Triggered when updating Unreleased section, documenting changes for release, or when user says "add changelog", "update changelog", "log this change".

UncategorizedID: bonny/wordpress-simple-history/changelog
31675

Install this agent skill to your local

pnpm dlx add-skill https://github.com/bonny/WordPress-Simple-History/tree/HEAD/.claude/skills/changelog

Skill Files

Browse the full folder contents for changelog.

Download Skill

Loading file tree…

.claude/skills/changelog/SKILL.md

Skill Metadata

Name
changelog
Description
Adds changelog entries to readme.txt following keepachangelog format. Triggered when updating Unreleased section, documenting changes for release, or when user says "add changelog", "update changelog", "log this change".

Add Changelog Entry

Add entries to the Simple History plugin's readme.txt changelog.

Workflow

  1. Ask user for the change description (if not provided)
  2. Determine category: Added, Changed, Fixed, Deprecated, Removed, Security
  3. Add entry under ## Changelog → ### Unreleased
  4. Confirm with user

Format

-   Fixed post creation via Gutenberg autosave not being logged. [#599](https://github.com/bonny/WordPress-Simple-History/issues/599)
  • Start with - (hyphen + 3 spaces)
  • Do NOT repeat the category verb — the heading already says Added/Changed/Fixed, so don't start entries with "Added...", "Fixed...", etc.
  • Link GitHub issue/PR if available
  • End with period

Writing Guidelines

Changelogs are for humans, not machines. Write for both technical and non-technical WordPress users.

Write for the user:

  • Explain what changed from the user's perspective, not what you did in the code
  • Provide context and scope: instead of "Optimized query" write "Improved performance on sites with large activity logs"
  • Replace jargon with clarity: avoid acronyms, internal class names, or hook names unless the audience is developers
  • Be specific: "Fixed timezone handling in email reports" not "Bug fixes"
  • Active voice: "Fixed X" not "X was fixed"

Be honest and complete:

  • Never hide breaking changes, deprecations, or security fixes
  • Be upfront about what changed and why — users trust changelogs that are transparent
  • Include all notable user-facing changes; selective entries undermine credibility
  • Mark experimental features with a trailing "(experimental)" tag, not as a prefix

Keep it concise:

  • One bullet per change, one or two sentences max
  • Don't duplicate commit messages — curate and translate them into user-facing language
  • Group related small changes into a single entry rather than listing each separately
  • Omit internal refactors, code cleanup, and dev tooling changes unless they affect users

Don't write:

  • "Bug fixes" or "Various improvements" (too vague, tells users nothing)
  • "Updated code" or "Minor changes" (meaningless)
  • Raw commit messages or git log dumps
  • Internal hook/filter names in user-facing entries (put in developer docs instead)

Categories

Use these standard categories from Keep a Changelog:

  • Added — New features and capabilities
  • Changed — Modifications to existing functionality
  • Deprecated — Features that will be removed in a future release
  • Removed — Features that have been eliminated
  • Fixed — Bug fixes
  • Security — Vulnerability patches (always include these, never hide them)

Unreleased Section

Always maintain an ### Unreleased section at the top of the changelog. This lets users see what's coming and makes it easy to promote entries into a versioned release.

When releasing, move Unreleased entries into a new versioned section with the release date.

Examples

✅ Post creation via Gutenberg autosave not being logged, causing email reports to show 0 posts created.
✅ Developer mode badge to improve debugging workflow.
✅ Performance on sites with large activity logs improved by optimizing database queries.
✅ `simple_history_log()` function — use `SimpleHistory\log()` instead. Will be removed in 6.0.
❌ Added developer mode badge (redundant — heading already says "Added")
❌ Fixed post creation (redundant — heading already says "Fixed")
❌ Bug fixes
❌ Updated code
❌ Refactored SimpleHistoryLogQuery class
❌ Various improvements and optimizations

References

Location

  • File: readme.txt (project root)
  • Section: ## Changelog → ### Unreleased
  • If Unreleased doesn't exist, create it after ## Changelog