SKILL.md

name: writing-git-tags description: Generates git tag annotations from commit history following Semantic Versioning and Conventional Commits. Use when creating git tags, writing release notes, tagging versions, or generating changelog entries. compatibility: Requires git and git-format CLI tools (invoked as git formatted-tag) license: GPL-3.0-or-later metadata: author: Amolith amolith@secluded.site

Generate well-structured git tag annotations by analyzing commits since the last tag. Follows Semantic Versioning 2.0.0 and organizes changes by impact.

Tag generation workflow

  1. Determine base reference

    • Get latest tag: git describe --tags --abbrev=0
    • If no tags exist, use first commit or last 10 commits
    • User may specify a different base tag

  2. Collect commit data

    • Git status: git status
    • Commits since base: git log --format="# %s%n%n%b" BASE..HEAD
    • If no base tag: git log -10 --format="# %s%n%n%b"

  3. Analyze commits

    • Parse conventional commit format: type(scope): description
    • Identify breaking changes (! suffix or BREAKING CHANGE footer)
    • Categorize by type: feat, fix, perf, docs, style, refactor, test, build, chore

  4. Determine version bump

    • Breaking changes present → MAJOR
    • Features without breaking → MINOR
    • Only fixes → PATCH
    • Reset lower components per SemVer (1.9.0 → 2.0.0, not 2.9.0)

  5. Generate annotation

    • Subject: Brief description (≤50 characters total, version comes from tag name)
    • Body sections in priority order:
      • ⚠️ BREAKING CHANGES (always first if present)
      • ✨ Features
      • 🐛 Bug Fixes
      • ⚡ Performance Improvements
      • 📚 Documentation
      • ♻️ Code Refactoring
      • 🧪 Tests
      • 🔧 Build System
      • 🎨 Styling
    • Format: - [scope]: description or - description
    • Wrap all body lines at 72 characters maximum
    • For breaking changes, include what changed and migration path

  6. Create tag

    • Lightweight tag (no body): git tag TAG_NAME
    • Annotated tag with body: git formatted-tag TAG_NAME -m "SUBJECT" -b "BODY"
    • Or show to user for review: echo "Proposed annotation:" && echo "..."

git formatted-tag requires a tag NAME as the first argument and supports:

-m --message Tag subject (required, max 50 characters) -b --body Tag body (optional) -f --force Replace existing tag -h --help Help for git-formatted-tag -v --version Version for git-formatted-tag git formatted-tag v1.2.0 -m "Add user authentication" -b "$(cat <<'EOF' ✨ Features - [auth]: implement JWT-based authentication - [api]: add login and logout endpoints

🐛 Bug Fixes

  • [login]: correct password validation error EOF )"

Commit type mapping

Type Section
feat ✨ Features
fix 🐛 Bug Fixes
perf ⚡ Performance Improvements
docs 📚 Documentation
style 🎨 Styling
refactor ♻️ Code Refactoring
test 🧪 Tests
build, ci 🔧 Build System
chore 🔧 Build System (or omit if trivial)
revert Include in relevant section with "(revert)"

Subject line constraints

  • Maximum 50 characters
  • Use past tense for completed work
  • Capitalize first letter
  • No period at end
  • Focus on primary user value

Example output

Tag: v1.2.0

Annotation:

Add user authentication and session management

✨ Features
- [auth]: implement JWT-based authentication
- [api]: add login and logout endpoints
- [session]: add session middleware

🐛 Bug Fixes
- [login]: correct password validation error