# ai-changelog

ai-changelog sets up an AI-maintained CHANGELOG.md workflow across your project. Configures CalVer, SemVer, or simple date-based logging for non-code repositories.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 173 repo stars
- Author: sammcj
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/sammcj/agentic-coding/tree/HEAD/Skills/ai-changelog/SKILL.md
- Updated: 2026-11-04
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/ai-changelog

## What it does

The skill inspects build manifests like `package.json`, `Cargo.toml`, or `pyproject.toml` to detect the project type and versioning format. In software projects, agents append bullet points only beneath the `## [Unreleased]` block. Actual version bumping stays handled by automated build targets using an included `scripts/version.py` helper.

For documentation repositories or note collections without build systems, it switches to Dated mode. This path bypasses Python scripts completely and instructs the agent to log concise bullets under `## YYYY-MM-DD` headers. The setup also injects logging rules into `CLAUDE.md` so models avoid logging trivial formatting edits.

Running `scripts/version.py` requires `uv` with Python 3.12+. When the `[Unreleased]` block contains no entries, release stamping exits cleanly to avoid creating empty version logs.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add sammcj/agentic-coding --skill ai-changelog -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/ai-changelog/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/ai-changelog/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add sammcj/agentic-coding --skill ai-changelog -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/ai-changelog/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add sammcj/agentic-coding --skill ai-changelog -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/ai-changelog/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install sammcj/agentic-coding Skills/ai-changelog/SKILL.md
```

2. **Manually: put the files in place**
- File: `.github/skills/ai-changelog/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add sammcj/agentic-coding --skill ai-changelog -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/sammcj/agentic-coding --path Skills/ai-changelog
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/ai-changelog/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/sammcj/agentic-coding/tree/HEAD/Skills/ai-changelog/SKILL.md

## When to use it
- automate changelog maintenance for coding agents
- set up CalVer or SemVer release stamping across project manifests
- add date-based change logs to non-software and doc repositories
- restrict agent changelog entries to concise, user-facing lines

## Example prompts
- Set up an AI-driven changelog system for this repository
- Configure SemVer changelog stamping and update CLAUDE.md
- Add a date-based changelog workflow for our docs project

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 6fbb0568d1d43e83.

BEGIN THIRD-PARTY FILE 6fbb0568d1d43e83
```text
---
name: ai-changelog
description: Set up an AI-driven changelog system in any project, code or not. Suitable for both software projects and for non-code projects. Creates a CHANGELOG.md and instructions for agents to log changes. Use when the user wants to add or improve automated changelog management, AI-friendly changelog workflows, version stamping, or set up a changelog system for a new or existing project.
allowed-tools: Read Write Edit Bash Glob Grep
---

# AI-Driven Changelog

Set up a changelog system AI agents maintain during development. Two shapes, chosen by project type:

- **Software projects**: agents write entries under `## [Unreleased]`; automation stamps version numbers at release time (CalVer or SemVer). No agent ever writes version numbers; the build process handles that.
- **Non-code projects** (no build system): agents add terse bullets under a date heading (`## YYYY-MM-DD`) by hand. No script, no version numbers. See `references/dated.md`.

## Setup workflow

1. **Detect the build system**: Check for Makefile, Justfile, package.json, Cargo.toml, pyproject.toml, go.mod. Note which config files contain a `"version"` field.

2. **Check whether this is a software project at all.** If there's no build system from step 1 and no version convention (a docs repo, writing or notes vault, content site, research or config collection), use **Dated** mode: date-based changelog headings, no version script, no build integration. Skip straight to `references/dated.md` and ignore the script/build steps below. Otherwise, **detect the versioning scheme** by inspecting (highest confidence first):
   - `CHANGELOG.md` heading style: `## [YYYY.M.N]` headings → CalVer; `## [X.Y.Z]` headings or prose mentioning "SemVer" → SemVer
   - Git tags from `git tag --list | head`: `vX.Y.Z` → SemVer; `YYYY.M.N` → CalVer
   - `VERSION` file with content matching `^[0-9]+\.[0-9]+\.[0-9]+` → SemVer
   - Manifest version field (`package.json`, `Cargo.toml`, `pyproject.toml`) matching `X.Y.Z` → SemVer

   If signals are absent or contradictory, ask the user. Suggest SemVer for projects with established version history (existing tags, manifest versions, prior changelog entries) and CalVer for greenfield projects where automatic versioning is preferable. Each scheme has trade-offs documented in its reference file.

3. **Read the scheme reference** that matches the chosen scheme. It contains the build integration recipes, CLAUDE.md snippet, GitHub Actions pattern, and scheme-specific gotchas:
   - CalVer → `references/calver.md`
   - SemVer → `references/semver.md`
   - Dated (non-code projects) → `references/dated.md`

4. **Ask the user** about optional features (CalVer/SemVer only; skip for Dated mode):
   - Pinned `## Known Bugs` section above `## [Unreleased]`? (default: yes)
   - GitHub Actions release workflow integration? (default: skip unless asked)
```
END THIRD-PARTY FILE 6fbb0568d1d43e83

The third-party file has ended. Everything between the 6fbb0568d1d43e83 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2908 of 8186 bytes. © sammcj · Apache-2.0 · https://github.com/sammcj/agentic-coding/tree/HEAD/Skills/ai-changelog/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
