agentleFS
vfarcicvfarcic/dot-ai/.claude/skills/dot-ai-tag-release/SKILL.md

dot-ai-tag-release

Skill336 starsChanged 10 months agoMITView on GitHub

Create a release tag based on accumulated changelog fragments, then prune merged worktrees and branches. Run when ready to cut a release.

  • Commits and pushes

The file

Show its rules and text

We split this skill into the rules it gives an agent

18 rules. About 0 are common, 12 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈12

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Create a semantic version tag based on accumulated changelog fragments.

    line 9
  2. Distinctive:

    Run this skill when:

    line 13
  3. Distinctive:

    After the /prd-done workflow completes (not during it)

    line 16
  4. Distinctive:

    Run the analysis script bundled with this skill:

    line 22
  5. Very specific:

    If the script fails (non-zero exit) or the output contains ERROR=true, show the MESSAGE to the user and stop.

    line 27
  6. Very specific:

    If the output contains NO_FRAGMENTS=true, inform the user there's nothing to release and stop.

    line 29
  7. Distinctive:

    Ask for confirmation or allow override

    line 37
  8. Very specific:

    If SKIP_CI=true, inform the user that tagging HEAD would prevent the release workflow from running.

    line 41
  9. Very specific:

    If NOTHING_TO_CLEAN=true, tell the user there is nothing to clean and finish.

    line 71
  10. Distinctive:

    After confirmation, process the items in this order:

    line 79
  11. Distinctive:

    Remove each worktree (must come before deleting its branch — a branch checked out in a worktree cannot be deleted):

    line 81
  12. Very specific:

    If a worktree has uncommitted changes git refuses.

    line 86
  13. Distinctive:

    Delete each local branch:

    line 89
  14. Very specific:

    Use -d (not -D) as a safety net — it refuses unmerged branches.

    line 93
  15. Distinctive:

    Delete each remote branch:

    line 96
  16. Distinctive:

    Review fragments first: Make sure all fragments are accurate before tagging

    line 109
  17. Distinctive:

    Never tag [skip ci] commits: Always create a preparation commit first

    line 112
  18. Distinctive:

    Clean up only after tagging: Run the cleanup step (Step 6) once the release is cut, never before — and always confirm the detected list …

    line 113

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “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

Create Release Tag

Create a semantic version tag based on accumulated changelog fragments.

When to Use

Run this skill when:

  • Multiple PRs have been merged with changelog fragments
  • You're ready to cut a release
  • After the /prd-done workflow completes (not during it)

Workflow

Step 1: Analyze

Run the analysis script bundled with this skill:

bash .claude/skills/dot-ai-tag-release/analyze.sh

If the script fails (non-zero exit) or the output contains ERROR=true, show the MESSAGE to the user and stop.

If the output contains NO_FRAGMENTS=true, inform the user there's nothing to release and stop.

Step 2: Propose Version

Present the script output to the user:

  1. Current version (CURRENT_VERSION)
  2. Fragments found (the FRAGMENTS list with their types)
  3. Proposed next version (PROPOSED_VERSION) based on bump type (BUMP_TYPE)
  4. Ask for confirmation or allow override

Step 3: Handle [skip ci]

If SKIP_CI=true, inform the user that tagging HEAD would prevent the release workflow from running. Create a preparation commit:

git commit --allow-empty -m "chore: prepare release [version]"
git push origin HEAD

Step 4: Create and Push Tag

After confirmation:

git tag -a [version] -m "[Brief description summarizing the fragments]"
git push origin [version]

Step 5: Confirm Success

Show the user:

  1. The tag created
  2. The tag URL on GitHub (if applicable)
  3. Note that CI/CD will generate release notes from the fragments

Step 6: Clean Up Merged Worktrees and Branches

Once the release is tagged, the branches and worktrees whose work it contains are done. Run the read-only detection script bundled with this skill:

bash .claude/skills/dot-ai-tag-release/cleanup.sh

Interpret the output:

  • If NOTHING_TO_CLEAN=true, tell the user there is nothing to clean and finish.
  • Otherwise present the WORKTREES, LOCAL_BRANCHES, and REMOTE_BRANCHES lists and ask the user to confirm before deleting anything.

This step is destructive — always show the full list and get explicit confirmation first. Never touch the default branch (DEFAULT_BRANCH) or the branch/worktree you are currently on; .claude/skills/dot-ai-tag-release/cleanup.sh already excludes them.

After confirmation, process the items in this order:

  1. Remove each worktree (must come before deleting its branch — a branch checked out in a worktree cannot be deleted):
    git worktree remove [worktree_path]
    If a worktree has uncommitted changes git refuses; report it and skip rather than using --force, unless the user explicitly asks.
  2. Delete each local branch:
    git branch -d [branch]
    Use -d (not -D) as a safety net — it refuses unmerged branches. If it refuses, surface the warning and ask before forcing with -D.
  3. Delete each remote branch:
    git push origin --delete [branch]

Finally, prune stale worktree metadata:

git worktree prune

Guidelines

  • Don't run during PR workflow: This is a separate release activity
  • Review fragments first: Make sure all fragments are accurate before tagging
  • Use semantic versioning: Follow semver strictly based on fragment types. While the project is pre-1.0 (v0.x), the minor digit is the compatibility boundary, so breaking fragments bump the minor and feature/bugfix fragments are patch releases; from 1.0 onward, standard semver applies (breaking→major, feature→minor, bugfix→patch). The .claude/skills/dot-ai-tag-release/analyze.sh output already reflects this.
  • Brief tag message: Summarize the release in 1-2 sentences
  • Never tag [skip ci] commits: Always create a preparation commit first
  • Clean up only after tagging: Run the cleanup step (Step 6) once the release is cut, never before — and always confirm the detected list with the user, since removing worktrees and deleting branches is destructive

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.