git-tag
Skill3 starsChanged 23 days agoMITView on GitHub
Create an annotated vX.Y.Z version tag on a merge commit or named commit per the repo's release flow, and optionally push it to origin, each step gated. Use for "tag this release", "tag v1.2.0", "create the patch tag after the hotfix", or finishing a release/* or hotfix/* integration. Refuses to move, delete, or force-push tags, and to push a tag whose commit no origin branch contains.
- Commits and pushes
1 other project uses a version of this.
Adopted by
Most recently taken up by
- cognis-digital/skillsmiththeir own version, first seen Oct 11, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- cognis-digital/skillsmith★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository15 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- git-branch-createSkill
- git-branch-deleteSkill
- git-commitSkill
- git-fetchSkill
- git-mergeSkill
- git-pullSkill
- git-pushSkill
- hf-downloadSkill
- hf-setupSkill
- hf-uploadSkill
- py-env-setupSkill
- repo-docsSkill
- repo-initSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 7 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
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
- could be automatic: a setting could enforce it
- Distinctive: line 28
Run every command in this skill in a POSIX shell.
- Very specific: line 30
Read the spec: Read .gitmessage's "Tags" section for the naming scheme.
- Distinctive: line 32
Gather state: Run these independent reads:
- Distinctive: line 64
At least one contains it: ask with a choice question (push tag / local only):
- Very specific: line 79
NEVER pass -f/--force to git tag, and NEVER delete or retarget an existing tag, locally or on origin.
- Very specific: line 80
NEVER push with --tags (it sweeps every local tag) or --follow-tags, and always pass --no-follow-tags so push.followTags config cannot do …
- Very specific: line 81
NEVER create a lightweight tag.
- Very specific: line 82
NEVER write the tag message to a file on disk.
- Distinctive: line 83
NEVER add an AI tool, model, agent, or vendor attribution to the tag message.
- Distinctive: line 84
NEVER skip the step 5 confirmation, and NEVER fold the push into it.
- Distinctive: line 85
NEVER create or push an off-trunk tag, new or existing, without the step-3 explicit in-turn opt-in.
- Very specific: line 86
NEVER push a tag whose commit no refreshed origin branch contains (step 7).
- Distinctive: line 87
NEVER merge, commit, push branches, or delete branches from this skill.
≈ “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.
Files
Goal
Create one annotated tag with a .gitmessage-compliant name on an explicitly identified commit, and optionally publish it to origin once an origin branch contains the tagged commit. This completes the release/* and hotfix/* flows in .gitmessage's "Branch Types" section, which require a release or patch tag on main at the merge commit.
When NOT to use
- The release branch is not merged yet:
git-mergefirst, then return here to tag the merge commit. - The user wants a tag moved or deleted: out of scope. A published tag is an immutable public promise; ship a new version instead. For a tag that was never pushed, render the
git tag -d <name>command for the user to run themselves. - The user wants branches published:
git-push(it pushes branches only, never tags). A tag push waits for it: step 7 refuses to publish a tag whose commit is not yet on an origin branch.
Prerequisites
Resolve before step 1:
- Tag name:
v<major>.<minor>.<patch>(for examplev1.4.0), per.gitmessage's "Tags" section. Pre-release suffixes (v1.4.0-rc.1) are allowed when the user names one. If the user proposes a name outside this scheme, suggest the corrected form and confirm with a choice question before using it. - Target commit: the commit being tagged. Named by the user, or defaulting to the tip of the integration trunk right after the
git-mergerun that suggested this skill. Never tag a moving reference conceptually: resolve to a SHA in step 2 and tag that.
Procedure
Terms such as choice question, independent reads, invoke, and suggest follow AGENTS.md (Skill authoring); in a non-interactive session every gate ends this skill.
Run every command in this skill in a POSIX shell; the redirections and the heredoc are POSIX syntax and break under PowerShell.
- Read the spec. Read
.gitmessage's "Tags" section for the naming scheme. Fall back tov<major>.<minor>.<patch>when absent. Gather state. Run these independent reads:
git rev-parse --verify '<target>^{commit}'(resolve the target to a commit SHA; surface the verbatim error if it does not resolve). The^{commit}peel matters when<target>is itself a tag (promotingv1.4.0-rc.2tov1.4.0): without it the SHA is the tag object and step 6 would create a nested tag, whose only fix is the forbiddengit tag -f.git rev-parse --verify --quiet refs/tags/<name>(exact-name duplicate probe; any output means the tag already exists locally).git ls-remote origin refs/tags/<name> 'refs/tags/<name>^{}'whengit remotelistsorigin(the same probe against origin, for a tag published from another clone and never fetched here; a network failure is not fatal, note it and continue, since step 7 would surface the collision anyway).git -c versionsort.suffix=- tag --list 'v*' --sort=-v:refnamecapped at 10 (recent versions; theversionsort.suffixsetting ranksv1.4.0-rc.1belowv1.4.0, which plain version sort puts above it, to inform the next number and the step-4 changelog range; NOT the duplicate check, since ten newest entries would miss an older name).git log -1 --format='%h %s' <target>(what is being tagged, for the plan render).git branch -a --contains <target> --format='%(refname)'(local AND remote-tracking branches that reach the commit, as full refs such asrefs/heads/mainandrefs/remotes/origin/main, which stay unambiguous even when a tag shares a branch name; a localmainlags behind a merge that landed on the server, soorigin/maincounts in step 3).
If the tag name already exists, locally or on origin, STOP and report it with the commit it points at (
git rev-parse 'refs/tags/<name>^{commit}'locally; for origin, the SHA on the^{}line, which an annotated tag has, else the SHA on the plain line). Never retarget. For an origin-only hit, suggestgit-fetch, which brings the tag down so the two clones agree. One exception: when the tag exists locally, the origin probe succeeded and found nothing, and the user asked to push that tag (for example after a step-7 refusal), take<sha>fromgit rev-parse 'refs/tags/<name>^{commit}', recompute the containment list for it withgit branch -a --contains <sha> --format='%(refname)'(the list above describes<target>, which defaults to the trunk tip and may not be the tagged commit), run step 3 on that list (an off-trunk existing tag needs the same opt-in), then skip to step 7 with it.- Sanity-check placement. Release and patch tags belong on the trunk: if the step-2 containment list (recomputed, for the step-2 exception) includes neither
refs/heads/mainnorrefs/remotes/origin/main(or the repo's equivalent trunk), surface that prominently in the plan. Tagging off-trunk is allowed only with an explicit in-turn opt-in (AGENTS.md) that names the off-trunk tag and its target, typed or by choosing an option whose label states both; a generic yes or earlier-turn approval does not count. When onlyorigin/maincontains the target, the placement is fine and the localmainis merely behind; suggestgit-pullwithmainas a follow-up, not a blocker, since the tag pins a SHA rather than a branch. - Draft the tag message inline (no file). One short line naming the release (for example
Release v1.4.0), optionally followed by a blank line and one bullet per headline change since the previous tag (git log <prev-tag>..<target> --onelineis the fuel; skip the bullets for a patch tag with a single fix). Hold the draft in chat as a fenced code block. - Show the plan and confirm with a choice question (tag / edit / abort). Render the tag name, the target SHA and subject, the containment note from step 3, and the exact command:
The quoted heredoc terminator prevents shell expansion; if the draft contains a line equal togit tag -a <name> <sha> -F - <<'TAG_MSG_EOF' <approved message substituted verbatim> TAG_MSG_EOFTAG_MSG_EOF, pick a fresh terminator absent from the body. edit loops on free-text changes like the other skills in this family. - Create the tag. Execute the approved command verbatim. On failure, surface the error verbatim and stop.
Offer the push separately. Skip this step and stay local when the repo has no
originremote (git remotedoes not list it).First check that the tagged commit is published. Pushing a tag also uploads every commit it reaches, so a tag on an unpushed commit would publish that commit (for example a local merge into
main) pastgit-push's protected-branch gate. Refresh the candidate branches with one targeted fetch per branch:main(or the repo's equivalent trunk) plus everyrefs/remotes/origin/<b>in the step-2 containment list (for the step-2 exception, the list recomputed for the existing tag's commit):git fetch --no-tags origin +refs/heads/<b>:refs/remotes/origin/<b>An exit 128 with
couldn't find remote refmeans<b>is gone from origin: drop it, since its lingeringorigin/<b>is stale. Any other non-zero exit (network, auth, proxy): surface stderr verbatim, skip the question, and stay local. For each refreshed branch, rungit merge-base --is-ancestor <sha> refs/remotes/origin/<b>(exit 0 contains, exit 1 does not, anything else is an error to surface).- No refreshed branch contains
<sha>: refuse the tag push; do not ask the question below. Say the tag stays local because its commit is on no origin branch, and suggestgit-pushfor the branch that holds it (usuallymain), so that skill's protected-branch gate decides whether the commit may land. Once it has, the user can ask this skill to push<name>(the step-2 exception brings them back here, and the check runs again). - At least one contains it: ask with a choice question (push tag / local only):
- push tag:
git push --no-follow-tags origin refs/tags/<name>(the single tag ref only; the full ref avoids amatches more than onefailure when a branch shares the name, and--no-follow-tagsstops apush.followTags=trueconfig from publishing every other annotated tag reachable from this one). On rejection, surface the error verbatim and stop; never retry with--force. - local only: done; note that asking this skill to push
<name>later publishes it after the same check.
- push tag:
- No refreshed branch contains
- Report. Show
git log -1 --format='%h %s' refs/tags/<name>(this peels the annotated tag to its commit;git showwould print the tag object header first), the tag message, whether it was pushed, and the natural next step from.gitmessage's flow. Undergit-flow, suggestgit-mergeto back-merge the tagged branch intodevelop; for ahotfix/*tag, also into every activerelease/*branch. Then suggestgit-branch-deletefor the short-lived branch.
Rationale
- Annotated only. An annotated tag carries author, date, and message, which is what a release pin needs; lightweight tags are local bookmarks and invisible to
git describeby default. - The push is a separate gate, mirroring
git-branch-delete's scope question: creating a local tag is cheap to undo before publication, pushing it makes it a public promise every clone sees. - Resolving the target to a SHA before tagging removes the race where the branch tip moves between the plan render and the execution.
- A tag push waits for its commit to be on an origin branch.
git pushof a tag uploads the commits it points at, so without the step-7 check a tag on a local-only merge would publish that merge while bypassing the protected-branch gate thatgit-pushapplies to the branch itself.
Hard rules
- NEVER pass
-f/--forcetogit tag, and NEVER delete or retarget an existing tag, locally or on origin. A wrong published tag is corrected by publishing a new version, not by rewriting. - NEVER push with
--tags(it sweeps every local tag) or--follow-tags, and always pass--no-follow-tagssopush.followTagsconfig cannot do the same. Push exactly the one approved tag asrefs/tags/<name>. - NEVER create a lightweight tag.
git tag -a(or-swhen the user asks for signing) only. - NEVER write the tag message to a file on disk. It lives only in the chat conversation and the heredoc that feeds
git tag -F -, mirroring the discipline ofgit-commitandgit-merge. - NEVER add an AI tool, model, agent, or vendor attribution to the tag message.
- NEVER skip the step 5 confirmation, and NEVER fold the push into it; steps 5 and 7 are separate decisions with different blast radii.
- NEVER create or push an off-trunk tag, new or existing, without the step-3 explicit in-turn opt-in.
- NEVER push a tag whose commit no refreshed origin branch contains (step 7). Suggest
git-pushfor the branch first; never push the branch from here. - NEVER merge, commit, push branches, or delete branches from this skill. Suggest the matching skill without running it.
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
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.

