CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

53

Quality

58%

Does it follow best practices?

Impact

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/git-workflow-and-versioning/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Discovery

82%

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 good completeness with explicit 'Use when' clauses and decent trigger terms covering common git operations. However, the overly broad 'Use when making any code change' clause creates significant conflict risk with other skills, and the 'what' portion ('Structures git workflow practices') is somewhat vague about the concrete actions the skill performs.

Suggestions

Replace 'Structures git workflow practices' with more specific actions like 'Defines branch naming conventions, commit message formats, and merge strategies'.

Remove or narrow 'Use when making any code change' to avoid conflicting with other skills—instead specify 'Use when setting up a git workflow, choosing a branching strategy, or organizing commits'.

DimensionReasoningScore

Specificity

Names the domain (git workflow) and some actions (committing, branching, resolving conflicts), but 'Structures git workflow practices' is vague and doesn't list concrete specific actions like 'create feature branches with naming conventions' or 'write commit messages following conventional commits'.

2 / 3

Completeness

Clearly answers both what ('Structures git workflow practices') and when ('Use when making any code change. Use when committing, branching, resolving conflicts, or when you need to organize work across multiple parallel streams'). Has explicit 'Use when' clauses with specific triggers.

3 / 3

Trigger Term Quality

Includes strong natural trigger terms users would say: 'committing', 'branching', 'resolving conflicts', 'code change', and 'parallel streams'. These cover common git workflow scenarios well and match natural user language.

3 / 3

Distinctiveness Conflict Risk

'Use when making any code change' is overly broad and would likely conflict with many other skills (e.g., coding style, testing, linting skills). The git-specific triggers help, but the blanket 'any code change' clause significantly increases conflict risk.

2 / 3

Total

10

/

12

Passed

Implementation

35%

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

This skill reads more like a comprehensive git best-practices guide for human developers than a concise instruction set for Claude. It over-explains concepts Claude already knows (atomic commits, trunk-based development, git bisect) and includes motivational content (rationalizations table, red flags) that consume tokens without adding actionable value. The strongest sections are the concrete templates (commit message format, change summary structure, verification checklist), but these are buried in extensive philosophical guidance.

Suggestions

Cut the document by 50-60% by removing explanations of concepts Claude already knows (what atomic commits are, why version control matters, the rationalizations table, the red flags list) and focus on the specific conventions and templates this project expects.

Move detailed reference content (git debugging commands, pre-commit hook configuration, worktree usage) into separate files and link to them from a concise overview.

Add explicit error recovery steps to the pre-commit hygiene workflow (e.g., what to do when secrets are detected, when tests fail) to improve workflow clarity.

Restructure around a single clear workflow (branch → implement slice → test → commit → repeat → PR) with the commit message format and change summary template as the key actionable outputs, rather than organizing around principles.

DimensionReasoningScore

Conciseness

Significantly verbose for its target audience (Claude). Explains well-known concepts like what atomic commits are, what trunk-based development is, what git bisect does, and includes a 'Common Rationalizations' table that teaches philosophy rather than providing actionable instructions. The overview paragraph explaining what git is and why version control matters is unnecessary. Much of this content is general software engineering knowledge Claude already possesses.

1 / 3

Actionability

Contains concrete commands and examples (git worktree usage, pre-commit hygiene commands, branch naming conventions, commit message format), but much of the content is philosophical guidance rather than executable instructions. The code examples are illustrative rather than copy-paste ready for a specific task. The change summary template and verification checklist are actionable, but many sections describe principles rather than instruct.

2 / 3

Workflow Clarity

The 'Save Point Pattern' provides a clear workflow with a decision tree, and the pre-commit hygiene section has a sequenced checklist. However, the overall document lacks explicit validation checkpoints integrated into the main workflow — the verification checklist is at the end rather than woven into the process. The pre-commit steps are listed but there's no error recovery guidance (e.g., what to do if secrets are found, if tests fail).

2 / 3

Progressive Disclosure

The document is a monolithic wall of text at ~200+ lines with no references to supporting files (except one mention of 'code-review-and-quality' for splitting strategies). Content like git debugging commands, the rationalizations table, and detailed pre-commit hook configuration could be split into separate reference files. The sections are well-organized with clear headers, but the sheer volume inline hurts discoverability.

2 / 3

Total

7

/

12

Passed

Validation

100%

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

Validation11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository
addyosmani/agent-skills
Reviewed

Table of Contents

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.