git-workflow-and-versioning

Structures git workflow practices. Use when making any code change. Use when committing, branching, resolving conflicts, splitting uncommitted work in a messy working tree into clean atomic commits, opening or reviewing a pull request (PR), pushing to a remote, or when you need to organize work across multiple parallel streams. Use when cutting a release, choosing a semantic version bump, tagging, or writing a changelog.

Quality

84%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

81%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

Highly actionable content with explicit validation checkpoints and feedback loops across commit, branch, and release workflows. The main cost is token efficiency: background explanations (SemVer basics, DORA research, rationalizations table) pad the body with material Claude already knows, and the single file could offload the versioning detail to a reference file.

Suggestions

Trim the SemVer MAJOR.MINOR.PATCH explanation and DORA research citation to a one-line reminder — Claude already knows SemVer and trunk-based development rationale; keep only the project-specific policy (e.g., "when unsure whether a change is breaking, assume it is").

Cut or compress the 9-row "Common Rationalizations" table to the 3-4 most frequent traps; the rest restate guidance already given in Core Principles.

Move the Release & Versioning section (semver contract, tagging commands, changelog format) into a references/ file and keep a short pointer plus the release verification checklist in SKILL.md to reduce always-loaded tokens.

Dimension	Reasoning	Score
Conciseness	Mostly efficient command-driven guidance, but it explains concepts Claude already knows — the MAJOR.MINOR.PATCH SemVer table, a "DORA research consistently shows" citation, and repeated "commits are save points" phrasing — plus a 9-row "Common Rationalizations" table that could be trimmed. This is more than the minor over-explanation of a 4.	3 / 5
Actionability	Fully executable, copy-paste ready guidance throughout: "git worktree add ../project-feature-a feature/task-creation", "git tag -a v1.4.0 -m \"Release 1.4.0\"", a concrete pre-commit hygiene block (staged-diff secrets grep, npm test, lint, tsc), lint-staged JSON config, concrete commit-message examples, and branch-naming patterns.	5 / 5
Workflow Clarity	Multi-step processes are clearly sequenced with explicit validation and feedback loops: the Save Point Pattern decision tree ("Test passes? → Commit → Continue / Test fails? → Revert to last commit → Investigate"), the 5-step pre-commit checklist, and "For every commit" / "For every release" verification checklists.	5 / 5
Progressive Disclosure	A single well-sectioned ~350-line file with clear headers, ASCII diagrams, and clearly signaled one-level cross-references to sibling skills ("See the splitting strategies in `code-review-and-quality`"). No bundle files exist to split into, but the ~40-line Release & Versioning section is long enough that it could be a separate reference file — a minor organization gap.	4 / 5
	Total	17 / 20 Passed

Description

87%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description with explicit, concrete trigger coverage and comprehensive natural keywords. Its main weaknesses are an abstract one-line statement of what the skill does (the specifics live only in the when-clauses) and an intentionally broad "any code change" trigger that creates overlap risk with general coding skills.

Dimension	Reasoning	Score
Specificity	Enumerates many concrete actions — "committing, branching, resolving conflicts, splitting uncommitted work... into clean atomic commits, opening or reviewing a pull request (PR), pushing to a remote... cutting a release, choosing a semantic version bump, tagging, or writing a changelog" — giving comprehensive, non-generic coverage of the domain.	5 / 5
Completeness	Both are present: the explicit "Use when..." clauses give a very concrete when, but the what ("Structures git workflow practices") is a single abstract verb phrase — the concrete capabilities only appear inside the when-clauses, so it falls between the 4 and 5 anchors.	4 / 5
Trigger Term Quality	Natural user phrasing is comprehensively covered: "committing", "branching", "conflicts", "pull request (PR)" (spelled out with synonym), "pushing to a remote", "tagging", "changelog", "messy working tree", "parallel streams". No commonly-said term is conspicuously missing.	5 / 5
Distinctiveness Conflict Risk	The git/versioning niche has distinct triggers (commit, branch, PR, tag, changelog), but "Use when making any code change" is a deliberately broad trigger that overlaps with virtually every coding-related skill, preventing a 5.	4 / 5
	Total	18 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: addyosmani/agent-skills
Path: skills/git-workflow-and-versioning/SKILL.md
Commit: 2686b62

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.