К основному содержанию
скилл CX Codex

ai-changelog — скилл для Claude Code: настройка ченджлога

Скилл ai-changelog внедряет в репозиторий систему ведения CHANGELOG.md силами ИИ-агентов. Поддерживает SemVer, CalVer и датированные записи для проектов без сборщика.

Apache-2.0 ★ 173 обновлён 2026-11-04

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add sammcj/agentic-coding --skill ai-changelog -a claude-code
Открыть на GitHub

Что делает ai-changelog

Скилл определяет тип проекта по конфигам вроде package.json, Cargo.toml, pyproject.toml или go.mod. Для программных проектов агенты записывают изменения только под заголовок ## [Unreleased], а номера релизов проставляет автоматика. В проект копируется скрипт scripts/version.py, который обновляет версию в манифестах и ченджлоге.

Для документации и заметок без сборщика включается режим дат. В этом случае скрипты не создаются, а агент пишет короткие пункты под заголовки ## YYYY-MM-DD. Скилл также вносит правила ведения записей в CLAUDE.md, запрещая агентам раздувать текст до параграфов и логировать тривиальные правки форматирования.

Скрипт версионирования запускается через uv run и требует установленного Python 3.12 или новее. Если в секции [Unreleased] нет текста, фиксация релиза не сработает, что защищает историю от пустых версий.

Какие задачи решает

  • настроить ведение CHANGELOG.md агентами без ручного вмешательства
  • интегрировать автопростановку версий по SemVer или CalVer в сборку
  • организовать фиксацию изменений по датам в репозиториях документации
  • задать агенту чёткие правила краткости записей через CLAUDE.md

Примеры запросов агенту

  • Настрой в этом репозитории ченджлог для Claude Code
  • Добавь систему версионирования CalVer и подготовь CHANGELOG.md
  • Настрой ведение истории изменений по датам для нашей документации

Как установить ai-changelog

1Через Skills CLI (Vercel)

npx skills add sammcj/agentic-coding --skill ai-changelog -a claude-code

2Вручную: положить файлы

~/.claude/skills/ai-changelog/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/ai-changelog/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об ai-changelog

Как установить ai-changelog в Claude Code?

Выполните команду npx skills add sammcj/agentic-coding --skill ai-changelog -a claude-code или сохраните файл в ~/.claude/skills/ai-changelog/SKILL.md.

Что делает скилл ai-changelog?

Он анализирует репозиторий, создаёт шаблон CHANGELOG.md, добавляет скрипт штамповки версий scripts/version.py и прописывает в CLAUDE.md правила ведения записей.

Перезапишет ли скилл уже существующий CHANGELOG.md?

Нет, существующий файл не стирается: скилл аккуратно вставляет секцию [Unreleased] или заголовок с датой над старыми записями.

Исходный текст

SKILL.md · Apache-2.0
---
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)

5. **Generate or update CHANGELOG.md**. For CalVer/SemVer use `references/changelog-template.md`; for Dated use the template in `references/dated.md`. If a CHANGELOG.md already exists, do NOT overwrite it; insert the HTML comment and the appropriate structure (`## [Unreleased]` for CalVer/SemVer, today's date heading for Dated) above existing entries.

6. **Copy `scripts/version.py`** from this skill into the target project's `scripts/` directory. Make it executable (`chmod +x`). _Skip in Dated mode - there is no script._

7. **Apply the scheme reference**: follow the build-integration recipe from the chosen reference file. Add targets to the existing build system, or create a minimal Makefile if none exists. _Skip in Dated mode - there is no build integration._

8. **Update CLAUDE.md** with the snippet from the chosen scheme reference. Insert into the project's development workflow section, or create one. In Dated mode this is the only mechanism that keeps the changelog current, so make sure the snippet lands. Add "Squash changes within the same day/version (do not add changes to changes)." Keep the snippet's what-to-log and entry-length rules intact - they are what stops agents logging trivia and writing paragraphs for simple changes.

9. **Verify**:
   - CalVer: `uv run scripts/version.py version` should print today's CalVer; then `uv run scripts/version.py stamp --dry-run` previews the stamp
   - SemVer: `uv run scripts/version.py stamp --version <current-version> --dry-run --changelog-only` previews the stamp without touching the canonical version source
   - Dated: confirm CHANGELOG.md has today's date heading and the CLAUDE.md snippet is in place; nothing to run

## Project detection

Indicator, then what to stamp and how to integrate:

- `Makefile` - stamp whatever config files the project has; add make targets
- `Justfile` - same config files; add just recipes
- `package.json` - stamp `package.json`; add npm scripts, or a Makefile
- `Cargo.toml` - stamp `Cargo.toml`; Makefile wrapper
- `pyproject.toml` - stamp `pyproject.toml`; Makefile wrapper
- `go.mod` - stamp `VERSION` if present, otherwise nothing; Makefile wrapper
- `VERSION` file - stamp `VERSION`; Makefile wrapper
- No build system, code project - nothing to stamp; create a minimal Makefile
- No build system, non-code project - Dated mode: no script, no Makefile

## How the script works

`scripts/version.py` subcommands:
- `version`: prints today's CalVer to stdout (CalVer projects only)
- `stamp`: replaces `## [Unreleased]` with `## [VERSION] - DATE`, re-inserts a fresh `## [Unreleased]`, and stamps version into auto-discovered config files (`package.json`, `Cargo.toml`, `pyproject.toml`, `tauri.conf.json`, `VERSION`)

Flags: `--version X.Y.Z` (required for SemVer; optional override for CalVer), `--dry-run`, `--changelog-only`, `--no-changelog`.

The script is scheme-agnostic. With no `--version`, it auto-computes CalVer; with `--version`, it stamps whatever string you give it. Validation lives in the build system, so SemVer recipes always pass `--version` and reject malformed input before invoking the script. See `references/semver.md` for why this split matters.

Run via `uv run scripts/version.py stamp` (stdlib only). uv supplies the Python 3.12+ its inline metadata requires.

## Gotchas

- **Never overwrite existing changelog history.** If a CHANGELOG.md exists with content, merge the `[Unreleased]` structure into it rather than replacing the file.
- **Empty Unreleased section**: stamping is a no-op if `[Unreleased]` has no content. This prevents empty version entries.
- **`fetch-depth: 0` in CI for CalVer**: CalVer uses `git rev-list --count HEAD`. Shallow clones produce wrong commit counts.
- **A changelog is not a commit log.** Two rules keep it useful, and both must appear in the HTML comment and the CLAUDE.md snippet: log only reader-visible changes (git history covers the rest), and keep entries to one line unless the change is genuinely complex. Without them agents log formatting tweaks and write paragraphs for one-line fixes.
- **The HTML comment is the agent's instruction source.** The `<!-- AI agents: ... -->` comment in CHANGELOG.md tells future agents how to write entries. Don't omit it.
- **Known Bugs stays pinned.** The stamp script preserves `## Known Bugs` above `## [Unreleased]`. If you add it, agents should maintain it there.
- **SemVer + auto-CalVer = silent footgun.** If a Makefile in a SemVer project calls `uv run scripts/version.py stamp` without `--version`, the script auto-computes CalVer and writes that into the changelog. The recipes in `references/semver.md` always pass `--version`; preserve that contract in any custom integration.
- **Run it with `uv`, not `python3`.** macOS's stock `python3` is 3.9 and fails on the script's `str | None` hints with a `TypeError`.
- **Config file stamping is first-match-only for TOML.** The regex replaces only the first `version = "..."` line, which is the package version. Dependency versions are unaffected.
- **VERSION file stamping requires existing semver-shaped content.** The script's `VERSION` handler only rewrites the file if its current content matches `^\d+\.\d+\.\d+`. Build numbers, tag-prefixed versions, or other formats are left alone.

© sammcj · Apache-2.0 · sammcj/agentic-coding

Похожие скиллы

Все скиллы по теме «Git и GitHub» →
changelog-writer patricio0312rev Скилл changelog-writer собирает CHANGELOG и release notes из git-коммитов, заголовков PR и ссылок на issues. Пригодится перед релизом, когда нужно разложить изменения по типам и подобрать версию. CX Codex +1 631установок changelog-generator Alireza Rezvani Скилл changelog-generator для Claude Code формирует заметки к релизу из Conventional Commits и определяет следующий SemVer-бамп. Запускается при подготовке релиза, проверке сообщений коммитов и планировании hotfix. CX Codex +1 618установок changelog itechmeat Скилл задаёт структуру CHANGELOG.md по Keep a Changelog 1.1.0: разделы Added/Changed/Fixed, заголовки версий, даты ISO 8601 и ссылки на сравнения. CX Codex +1 192установок release-manager borghei Скилл release-manager для Claude Code, Codex, Cursor, Copilot и Gemini CLI берёт вывод git log или JSON-план и выдаёт changelog, SemVer-версию и оценку готовности к релизу. Запускается вручную перед каждым релизом или хотфиксом. CX Codex +1 132установок changelog-maintenance aj-geddes Скилл changelog-maintenance помогает агенту писать и поддерживать CHANGELOG.md по формату Keep a Changelog: разделы Added, Changed, Fixed, Security и отметки о ломающих изменениях. CX Codex +1 503установок add-to-changelog davila7 Команда add-to-changelog для Claude Code, которая добавляет запись в CHANGELOG.md по формату Keep a Changelog. Принимает версию, тип изменения и описание прямо в аргументах. CX Codex +1 277установок

Из того же набора73

Весь набор →
release-debrief Скилл release-debrief для Claude Code сравнивает свежий релиз поддерживаемого инструмента с последней сохранённой сводкой. Разбирает изменения в Claude Code, OpenCode, llama-swap и llama.cpp. CX Codex +1 ★ 173звёзд репо pptx-to-md Скилл pptx-to-md для Claude Code превращает PPTX в Markdown: один файл на слайд, с текстом, позициями изображений и описанием диаграмм и скриншотов. CX Codex +1 ★ 173звёзд репо web-artifacts-builder-v2 Скилл web-artifacts-builder-v2 собирает сложные HTML-артефакты на React с несколькими компонентами, состоянием или маршрутизацией. Он пригодится, когда нужен готовый автономный HTML-файл. CX Codex +1 ★ 173звёзд репо glean-cli Скилл glean-cli учит агента работать с CLI glean: искать по корпоративному индексу, спрашивать Glean Assistant, читать документы и карточки людей. CX Codex +1 ★ 173звёзд репо rust-engineer Скилл rust-engineer на Claude Code настраивает помощника по Rust: от владения памятью и async-кода до тестов, Miri и оптимизации. Охватывает системные проекты. CX Codex +1 ★ 173звёзд репо software-research-assistant Субагент software-research-assistant для Claude Code исследует библиотеки, фреймворки и API по документации, примерам кода и актуальным рекомендациям из источников. Помогает внедрить инструмент или выбрать между вариантами. CX Codex ★ 173звёзд репо guided-demo Скилл guided-demo добавляет в веб-приложения и HTML-страницы интерактивные демо с пошаговой подсветкой элементов и печатью текста. CX Codex +1 ★ 173звёзд репо diagnose-hard-problem Скилл diagnose-hard-problem для Claude Code ведёт агента через диагностику сложных багов: строит проверяемый цикл воспроизведения, сужает сценарий и проверяет гипотезы. Разбирает регрессии и нестабильные ошибки. CX Codex +1 ★ 173звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой