agentleFS
littlebearappslittlebearapps/pitchdocs/.claude/skills/changelog/SKILL.md

changelog

Skill8 starsChanged 8 months agoMITView on GitHub

Generates user-friendly changelogs from git history using conventional commits. Writes entries in benefit language ("You can now..." not "Refactored internal..."). Follows Keep a Changelog format. Use when creating or updating CHANGELOG.md.

165 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use playtest-report, soak-test and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • CoralGameSkill

    playtest-report

    Generates a structured playtest report template or analyzes existing playtest notes into a structured format. Use this to standardize playtest feedback collection and analysis.

    Also in 12 projects that use this

  • lilangMaxSkill

    soak-test

    Generate a soak test protocol for extended play sessions. Defines what to observe, measure, and log during long play sessions to surface slow leaks, fatigue effects, and edge cases that only appear after sustained play. Primarily used in Polish and Release phases.

    Also in 9 projects that use this

  • lilangMaxSkill

    team-live-ops

    Orchestrate the live-ops team for post-launch content planning: coordinates live-ops-designer, economy-designer, analytics-engineer, community-manager, writer, and narrative-director to design and plan a season, event, or live content update.

    Also in 9 projects that use this

  • CoralGameSkill

    team-polish

    Orchestrate the polish team: coordinates performance-analyst, technical-artist, sound-designer, and qa-tester to optimize, polish, and harden a feature or area for release quality.

    Also in 14 projects that use this

  • +5 more from lilangMax
  • +3 more from CoralGame

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. 0 are common, 9 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 154 edited versions we read keep these.

  • 9

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Follow keepachangelog.com with marketing-friendly language.

    line 12
  2. Distinctive:

    If there's no existing CHANGELOG.md, create one with all tagged releases

    line 118
  3. Very specific:

    If there's an existing one, only add the [Unreleased] section

    line 119
  4. Distinctive:

    Always include comparison links at the bottom

    line 120
  5. Distinctive:

    If the repo doesn't use conventional commits:

    line 124
  6. Distinctive:

    Check if the commit touches tests, docs, config, or source code

    line 126
  7. Distinctive:

    Read the diff to understand the nature of the change

    line 127
  8. Very specific:

    When a version contains breaking changes (BREAKING CHANGE: footer or feat!:/fix!: prefix), place them prominently:

    line 132
  9. Very specific:

    Add a Breaking Changes subsection at the top of the version entry, before ### Added

    line 134
  10. Distinctive:

    Write in chunks of 5–10 entries at a time — use Write for the initial file, then Edit for appending

    line 167
  11. Distinctive:

    Keep each write operation under 15 lines of template-like content

    line 168
  12. Very specific:

    Start with [Unreleased] (most project-specific), then append older versions

    line 169
  13. Distinctive:

    If the filter triggers, break the blocked content into smaller pieces and rephrase

    line 170
  14. Very specific:

    If the filter triggers repeatedly on unrelated content, the session may be poisoned — run /clear or start a new session

    line 171

“Common” is measured: kept by at least 6 in 10 of the 154 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Changelog Generator

Format: Keep a Changelog

Follow keepachangelog.com with marketing-friendly language.

# Changelog

All notable changes to this project are documented here.

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

## [Unreleased]

### Added
- You can now generate READMEs with marketing-friendly language (#42)

### Changed
- Changelog entries are now written in reader-centric language (#38)

### Fixed
- Badge URLs no longer break when the repo is transferred (#35)

## [1.2.0] - 2026-02-20

### Added
- New `/roadmap` command pulls data from GitHub Projects (#30)
- User-benefit language across all generated documents (#28)

### Changed
- Quickstart section now shows TypeScript examples by default (#27)

### Deprecated
- The `--format plain` flag will be removed in v2.0 — use `--format markdown` (#25)

### Security
- Dependencies updated to patch CVE-2026-1234 (#33)

[Unreleased]: https://github.com/org/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/org/repo/compare/v1.1.0...v1.2.0

Compare URL patterns by platform (load platform-profiles for full mapping):

  • GitHub: https://github.com/org/repo/compare/v1.1.0...v1.2.0
  • GitLab: https://gitlab.com/org/repo/-/compare/v1.1.0...v1.2.0
  • Bitbucket: https://bitbucket.org/org/repo/branches/compare/v1.2.0..v1.1.0 (note: reversed order)

Categories (Keep a Changelog Standard)

CategoryWhen to UseConventional Commit Types
AddedNew features for usersfeat:
ChangedChanges to existing functionalityfeat: (modifications), refactor: (user-visible)
DeprecatedFeatures that will be removedfeat: with deprecation
RemovedFeatures that were removedfeat: (breaking)
FixedBug fixesfix:
SecurityVulnerability patchesfix: with security label

Language Rules

Write for the USER, not the developer

Internal changes that don't affect users should be EXCLUDED from the changelog. Changelogs are for humans who USE the software.

Don't WriteWrite Instead
Refactored database layer(Skip — internal change)
Updated dependenciesDependencies updated to patch CVE-2026-1234
Fixed bug in parserDocuments with special characters now render correctly
Added new API endpointYou can now retrieve usage metrics via the /metrics endpoint
Improved performancePage loads are now 40% faster on large datasets
Changed config formatConfiguration files now use YAML instead of JSON — see migration guide

Sentence patterns

  • Added: "You can now [do thing] (#issue)" or "New [feature] for [use case] (#issue)"
  • Changed: "[Thing] now [behaves differently] (#issue)"
  • Fixed: "[Thing] no longer [breaks in this way] (#issue)"
  • Security: "Dependencies updated to patch [CVE] (#issue)" or "[Component] no longer exposes [data] (#issue)"
  • Deprecated: "The [feature/flag] will be removed in [version] — use [alternative] (#issue)"

Workflow

Step 1: Analyse Git History

# Get commits since last tag
git log $(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)..HEAD --oneline --no-merges

# Get tags for version comparison links
git tag --sort=-v:refname | head -10

# Check for conventional commit format
git log --oneline -20 | grep -E '^[a-f0-9]+ (feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?:'

Step 2: Classify Changes

For each commit:

  1. Parse the conventional commit type
  2. Determine if the change is user-visible
  3. Map to the correct Keep a Changelog category
  4. Rewrite the message in user-benefit language
  5. Link to the relevant issue/PR number

Step 3: Group by Version

  • If there's no existing CHANGELOG.md, create one with all tagged releases
  • If there's an existing one, only add the [Unreleased] section
  • Always include comparison links at the bottom

Step 4: Handle Non-Conventional Commits

If the repo doesn't use conventional commits:

  1. Analyse the commit message content
  2. Check if the commit touches tests, docs, config, or source code
  3. Read the diff to understand the nature of the change
  4. Classify manually based on the actual change

Breaking Changes

When a version contains breaking changes (BREAKING CHANGE: footer or feat!:/fix!: prefix), place them prominently:

  1. Add a Breaking Changes subsection at the top of the version entry, before ### Added
  2. Each entry must include: what changed, why, and a migration path
  3. Link to a migration guide if the change affects multiple areas
## [2.0.0] - 2026-03-15

### Breaking Changes

- Configuration format changed from JSON to YAML — run `npx migrate-config` to convert (#80)
- The `--format plain` flag has been removed — use `--format markdown` instead (#75)

### Added
...

For major versions with many breaking changes, recommend a standalone docs/guides/migration-v2.md and link to it from the CHANGELOG entry.

Anti-Patterns

  • Don't include every commit — changelogs are curated, not comprehensive
  • Don't include merge commits — they're noise
  • Don't include internal refactors — unless they change behaviour
  • Don't use past tense — "Added" not "We added"
  • Don't duplicate the git log — add context and user benefit
  • Don't forget comparison links — they're essential for navigation

Content Filter Awareness

Risk level: MEDIUM. CHANGELOG.md's template-like repetitive structure (version headers, category headers, bullet lists) can trigger Claude Code's content filter (HTTP 400) when writing large blocks.

Mitigation:

  1. Write in chunks of 5–10 entries at a time — use Write for the initial file, then Edit for appending
  2. Keep each write operation under 15 lines of template-like content
  3. Start with [Unreleased] (most project-specific), then append older versions
  4. If the filter triggers, break the blocked content into smaller pieces and rephrase
  5. If the filter triggers repeatedly on unrelated content, the session may be poisoned — run /clear or start a new session

See the docs-writer agent (Content Filter Mitigation section) for the full strategy playbook.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.