git-workflow-and-versioning

Structures git workflow practices. Use when making any code change. Use when committing, branching, resolving conflicts, 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

66%

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

Fix and improve this skill with Tessl

tessl review fix ./skills/git-workflow-and-versioning/SKILL.md

The canonical home for this skill is git-workflow-and-versioning in addyosmani/agent-skills

Quality

Content

63%Scale 1-5

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

This is a comprehensive git workflow skill that covers branching, committing, versioning, and release practices with good concrete examples and clear formatting. Its main weakness is verbosity — it explains concepts Claude already knows (semantic versioning basics, what .gitignore does, what git bisect is) and includes motivational/philosophical content that doesn't add actionable value. The content would benefit from being split across multiple files and trimmed of explanatory prose.

Suggestions

Trim explanatory prose that teaches Claude things it already knows (e.g., what semantic versioning is, what git bisect does, why .gitignore matters) — just show the patterns and commands.

Extract the 'Common Rationalizations' table, 'Using Git for Debugging' section, and 'Working with Worktrees' section into separate reference files to reduce the main file's length and improve progressive disclosure.

Remove or condense the overview paragraph ('Git is your safety net...') and the 'When to Use' section — these don't add actionable guidance.

Dimension	Reasoning	Score
Conciseness	The skill is well-written but notably verbose at ~300 lines. Several sections explain things Claude already knows (what semantic versioning is, what git bisect does, what .gitignore is for). The 'Common Rationalizations' table and some explanatory prose ('Git is your safety net') add bulk without adding actionable value. The ASCII diagrams and examples are useful but the overall content could be tightened significantly.	3 / 5
Actionability	Provides concrete, executable commands (git tag, git bisect, git worktree), specific commit message formats with examples, and copy-paste ready pre-commit checks. Minor gaps: the lint-staged/husky setup is incomplete (no husky install steps), and some guidance is more philosophical than executable (e.g., 'feature flags > long branches' without showing how).	4 / 5
Workflow Clarity	The Save Point Pattern provides a clear workflow with validation (test passes → commit, test fails → revert). Pre-commit hygiene has a numbered sequence with validation steps. The release workflow (tag → push) is clear. Minor gap: the pre-commit steps don't have an explicit 'stop if any step fails' checkpoint, and the overall document reads more as principles than a step-by-step workflow, though the verification checklists at the end help.	4 / 5
Progressive Disclosure	The content is entirely self-contained in one file with no bundle files. At ~300 lines, some sections (git debugging, worktrees, common rationalizations table) could be split into separate reference files. There are references to other skills ('code-review-and-quality', 'api-and-interface-design', 'deprecation-and-migration', 'shipping-and-launch') which is good cross-referencing, but the main file itself is monolithic and could benefit from better progressive disclosure.	3 / 5
	Total	14 / 20 Passed

Description

70%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.

The description has strong 'when to use' guidance with multiple explicit trigger scenarios covering committing, branching, releases, and versioning. Its main weakness is the vague 'what' — 'Structures git workflow practices' doesn't clearly convey what concrete outputs or actions the skill produces. The phrase 'Use when making any code change' is overly broad and could cause unnecessary triggering.

Suggestions

Replace 'Structures git workflow practices' with concrete actions like 'Generates commit messages, defines branching strategies, enforces conventional commit formats, and produces changelogs'

Narrow 'Use when making any code change' to something more specific like 'Use when following git best practices for code changes' to reduce false-positive triggering against general coding skills

Dimension	Reasoning	Score
Specificity	Names the domain (git workflow) and mentions several actions (committing, branching, resolving conflicts, cutting a release, version bumping, tagging, writing a changelog), but uses the framing verb 'Structures git workflow practices' which is vague. The actions are listed as trigger contexts rather than concrete capabilities the skill performs.	3 / 5
Completeness	Has explicit 'when' clauses with multiple trigger scenarios. The 'what' is present but somewhat vague — 'Structures git workflow practices' doesn't clearly articulate what the skill actually does (e.g., does it generate commit messages? enforce conventions? provide branching strategies?). The 'when' is strong and explicit, but the 'what' could be more concrete.	4 / 5
Trigger Term Quality	Includes many natural trigger terms users would say: 'committing', 'branching', 'resolving conflicts', 'release', 'semantic version bump', 'tagging', 'changelog'. Missing some common variations like 'merge', 'pull request', 'PR', 'git log', or 'rebase', but overall good keyword coverage.	4 / 5
Distinctiveness Conflict Risk	Fairly distinct with its focus on git workflow practices, branching, releases, and semantic versioning. The overly broad 'Use when making any code change' introduces some conflict risk with general coding skills, but the specific git-related triggers help differentiate it.	4 / 5
	Total	15 / 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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: finlay611/agent-skills
Path: skills/git-workflow-and-versioning/SKILL.md
Commit: 8c65303

Reviewed: ~1 hour 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.