| name | changelog-automation |
| description | Standardize changelog updates, git tag versioning, release notes, and commit conventions. Prefer a lightweight CHANGELOG.md + git tag workflow for small documentation or student projects; only introduce automation when explicitly needed. |
| risk | medium |
| source | customized |
| version | v1.0.0 |
| created_date | "2026-06-29T00:00:00.000Z" |
| last_updated_date | "2026-06-29T00:00:00.000Z" |
Changelog Automation
Use this skill to help maintain a clear project history through CHANGELOG.md, git tags, version rules, and commit conventions.
This skill supports both:
- Minimal workflow: manual
CHANGELOG.md updates + git tags.
- Automated workflow: tools such as
standard-version, semantic-release, GitHub Actions, git-cliff, or commitizen.
For small projects, documentation repositories, school projects, or repositories without a formal release process, prefer the minimal workflow by default.
Use this skill when
- Updating or standardizing
CHANGELOG.md.
- Deciding whether a change should be recorded in the changelog.
- Suggesting the next version tag.
- Preparing release notes from recent commits, pull requests, or issue summaries.
- Defining or applying commit message conventions.
- Managing semantic versioning.
- Creating a lightweight release workflow using
CHANGELOG.md and git tag.
- Reviewing whether changelog content is safe, clear, and complete.
Do not use this skill when
- The project has no versioning, no changelog, and no need to track notable changes.
- The user only needs a quick one-time summary that should not be stored in
CHANGELOG.md.
- Commit history is unavailable, unreliable, or too vague to infer meaningful changes.
- The user asks for unrelated project documentation such as SRS, README, wiring guides, test plans, or implementation plans without mentioning changelog, release notes, versioning, tags, or commit conventions.
- The user is asking for deployment automation, CI/CD setup, or package publishing without needing changelog or version management.
Core principles
1. Prefer minimal workflow for small projects
For projects that only use CHANGELOG.md and git tags, do not introduce external release tools by default.
Recommended minimal flow:
Make changes
→ Commit changes with a clear message
→ Update CHANGELOG.md manually
→ Review changelog for accuracy and safety
→ Create a git tag only when the user explicitly asks
Use this workflow unless the user explicitly asks for automation or the repository already has a formal release process.
2. Use Keep a Changelog structure
Use a clear changelog structure inspired by Keep a Changelog.
Recommended sections:
# Changelog
All notable changes to this project will be documented in this file.
## [Unreleased]
### Added
- New features, documents, modules, or major sections.
### Changed
- Meaningful changes to existing behavior, structure, or documentation.
### Fixed
- Corrections, resolved contradictions, bugs, or wrong descriptions.
### Removed
- Removed features, documents, modules, or obsolete content.
### Security
- Security-related changes that are safe to disclose.
Use only the sections that are needed. Do not create empty sections unless the project convention requires them.
3. Treat CHANGELOG.md as the source of release history
For lightweight projects, CHANGELOG.md is the main human-readable history.
A git tag marks a stable point in repository history, but the changelog explains what changed.
Before suggesting a tag, check that:
- The changelog has an entry for the intended version.
- The entry is understandable to humans.
- The entry does not expose secrets or internal-only details.
- The version bump matches the actual change scope.
4. Do not create or push tags without explicit permission
Never create, push, delete, overwrite, or move git tags unless the user explicitly asks.
Allowed by default:
- Suggest the next version tag.
- Explain why a version should be patch, minor, or major.
- Provide commands the user can run manually.
- Prepare changelog text.
Not allowed unless explicitly requested:
git tag ...git push origin ...git tag -d ...git push origin --delete ...- Any action that changes remote release history.
Version policy
Use Semantic Versioning when the project does not define a different rule.
Format:
MAJOR.MINOR.PATCH
Meaning:
- MAJOR: breaking change or large structural change.
- MINOR: new feature, new document, new major section, or meaningful capability added.
- PATCH: bug fix, correction, clarification, small documentation update, metadata update, or minor cleanup.
Examples:
v1.0.2 → v1.0.3 patch update
v1.0.2 → v1.1.0 minor update
v1.0.2 → v2.0.0 major update
Draft version policy
If the project uses v0.x.x as draft versions:
v0.x.x means the document or project state is still draft, unstable, or under review.- Do not treat
v0.x.x as a stable release.
- Avoid aggressive edits to
v0.x.x documents unless the user explicitly asks.
- Prefer reporting issues, suggesting improvements, or preparing proposed changes.
- Use
v1.0.0 or higher only when the user confirms the document or project is stable enough.
Commit convention
Use clear commit messages. Conventional Commits are recommended but not mandatory for minimal projects.
Recommended format:
<type>(<scope>): <short description>
Common types:
| Type | Use for | Changelog mapping |
|---|
feat | New feature or capability | Added |
fix | Bug fix or contradiction fix | Fixed |
docs | Documentation changes | Added / Changed / Fixed depending on meaning |
chore | Maintenance, metadata, version updates | Changed or usually excluded |
refactor | Restructure without changing meaning | Changed |
ci | CI/CD workflow changes | Changed or usually excluded |
test | Test changes | Usually excluded unless notable |
build | Build system changes | Usually excluded unless notable |
Examples:
git commit -m "docs(srs): update intrusion detection scenario"
git commit -m "fix(wiring): correct RC522 pin description"
git commit -m "chore(changelog): record v1.0.2 changes"
git commit -m "docs(readme): update project setup guide"
Do not rely only on vague commits such as:
git commit -m "update"
git commit -m "fix"
git commit -m "done"
If the commit history is vague, ask for or infer from file diffs, PR descriptions, issue summaries, or user-provided context.
Changelog entry rules
Record changes that are notable to the project, team, instructor, reviewer, or future maintainer.
Good changelog entries:
### Changed
- Updated the hardware wiring guide to describe connections by device instead of by ESP32-CAM pin.
### Fixed
- Corrected the RC522 module pin description to avoid wiring ambiguity.
Weak changelog entries:
### Changed
- Updated file.
- Fixed stuff.
- Changed something.
Prefer human-readable descriptions over raw commit messages.
Safety rules
Never expose secrets, credentials, internal-only values, or private contact details in release notes or changelog entries.
Do not include:
- API keys.
- Tokens.
- Passwords.
- Private URLs.
- Private email addresses unless explicitly intended for public documentation.
- Internal-only deployment details.
- Sensitive security exploit details that increase risk.
Bad:
### Fixed
- Fixed Telegram bot token 123456:ABCDEF...
Good:
### Fixed
- Improved Telegram alert configuration handling.
For security changes, describe the impact safely.
Minimal workflow commands
Use these as suggestions only. Do not execute tag-changing commands unless explicitly requested.
Check changes:
git status
git diff
git log --oneline
Commit changelog update:
git add CHANGELOG.md
git commit -m "chore(changelog): update release notes"
Create a local tag:
git tag v1.0.2
Push a tag:
git push origin v1.0.2
List tags:
git tag --list
Show current version history:
git log --oneline --decorate
Automation guidance
Do not introduce automation tools by default.
Only recommend tools such as standard-version, semantic-release, GitHub Actions, git-cliff, or commitizen when:
- The user explicitly asks for changelog automation.
- The repository already has CI/CD.
- The project has a real release process.
- The team needs repeated release-note generation.
- Manual changelog maintenance is becoming error-prone.
When automation is appropriate, choose the simplest tool that matches the project:
| Situation | Suggested approach |
|---|
| Small documentation repo | Manual CHANGELOG.md + git tags |
| Java or mixed repo with no package release | Manual changelog or git-cliff |
| Node.js package | standard-version or semantic-release |
| Python package | commitizen |
| Mature GitHub project | GitHub Actions + release notes |
| Team with strict commit rules | commitlint + PR review |
Agent behavior
When asked to update or review changelog/versioning:
- Identify the project workflow: minimal or automated.
- Inspect the available context: changed files, commits, PRs, issues, or user notes.
- Decide whether the change is notable.
- Classify the change under
Added, Changed, Fixed, Removed, or Security.
- Suggest the version bump if needed.
- Do not create or push tags unless explicitly asked.
- Check for secrets or internal-only details.
- Keep entries concise and understandable.
- Explain uncertain assumptions instead of inventing release history.
Recommended prompt for small projects
Use this prompt when asking an agent to update a lightweight changelog:
Dựa trên các thay đổi gần đây trong repo, hãy cập nhật CHANGELOG.md theo format Keep a Changelog.
Chỉ ghi các thay đổi đáng chú ý.
Không ghi secret, token, private URL, mật khẩu, email riêng tư hoặc chi tiết nội bộ nhạy cảm.
Dự án này chỉ dùng CHANGELOG.md và git tag, nên không tự thêm semantic-release, standard-version, GitHub Actions hoặc automation tool khác.
Nếu phù hợp, hãy đề xuất version tag tiếp theo theo Semantic Versioning, nhưng không tự tạo hoặc push tag nếu chưa được yêu cầu.
Resources
resources/implementation-playbook.md for detailed patterns, templates, and examples.- Use the resource file only when the user needs detailed automation setup, tool configuration, release workflow examples, or implementation templates.
Limitations
- This skill does not replace manual review.
- Generated changelog entries may be incomplete if commit history is vague.
- Version suggestions are recommendations, not final decisions.
- Environment-specific validation is still required before release.
- If required inputs, permissions, safety boundaries, or success criteria are missing, ask for clarification or make the safest minimal recommendation.
