tdg-personal/git-workflow
Git workflow patterns including branching strategies, commit conventions, merge vs rebase, conflict resolution, and collaborative development best practices for teams of all sizes.
52
52%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
42%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 does a good job listing specific git workflow topics, providing a clear picture of the skill's domain coverage. However, it critically lacks any 'Use when...' guidance, which would help Claude know when to select this skill over others. The trigger terms are decent but could include more natural user language variations and common git-related keywords.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks about git workflows, branching strategies, commit message formatting, resolving merge conflicts, or choosing between merge and rebase.'
Include additional natural trigger terms users might say, such as 'pull request', 'PR review', 'gitflow', 'trunk-based development', 'feature branch', 'squash commits', or 'git history'.
Narrow the overly broad phrase 'collaborative development best practices for teams of all sizes' to something more specific like 'code review workflows, PR conventions, and branch protection rules' to reduce conflict risk with general software engineering skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions/topics: branching strategies, commit conventions, merge vs rebase, conflict resolution, and collaborative development best practices. These are distinct, concrete areas of git workflow. | 3 / 3 |
Completeness | Describes what the skill covers well, but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and since the 'when' is entirely absent (not even implied through usage scenarios), this scores at 1. | 1 / 3 |
Trigger Term Quality | Includes good terms like 'branching', 'commit conventions', 'merge vs rebase', 'conflict resolution' that users might naturally use. However, it misses common variations like 'git branch', 'pull request', 'PR', 'cherry-pick', 'gitflow', 'trunk-based development', or file extensions like '.gitignore'. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on git workflow patterns is fairly specific, but terms like 'collaborative development best practices' and 'teams of all sizes' are broad enough to overlap with general software engineering or project management skills. The git-specific terms help but the scope is still somewhat wide. | 2 / 3 |
Total | 8 / 12 Passed |
Implementation
42%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is essentially a comprehensive Git reference manual rather than a focused skill file. While it excels at actionability with concrete, executable commands and clear examples throughout, it is far too verbose — most of this content (basic Git concepts, semver, gitignore patterns, aliases) is knowledge Claude already has. The lack of progressive disclosure means everything is crammed into one enormous file with no external references, and workflows lack explicit validation checkpoints.
Suggestions
Reduce content by 70-80% — remove sections Claude already knows (semver basics, what merge vs rebase is, standard gitignore patterns, basic git commands) and focus only on project-specific conventions and decisions (e.g., which branching strategy to use, the team's commit message format).
Split into multiple files: keep SKILL.md as a concise overview with links to separate files like BRANCHING.md, COMMIT_CONVENTIONS.md, PR_TEMPLATE.md, and HOOKS.md.
Add validation checkpoints to multi-step workflows — e.g., after conflict resolution, add 'Run tests to verify merge is correct' and 'Review git diff to confirm no unintended changes'.
Remove the Quick Reference table and git aliases section entirely — these are standard Git knowledge that adds no value to Claude's capabilities.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | This is extremely verbose at 400+ lines, covering nearly every Git concept imaginable. Much of this content (what semantic versioning is, how merge vs rebase works, basic git commands, gitignore patterns, git aliases) is knowledge Claude already possesses. The skill reads like a comprehensive Git tutorial rather than a concise skill file adding novel information. | 1 / 3 |
Actionability | The content is highly actionable with executable bash commands, concrete examples of commit messages (good vs bad), specific branch naming conventions, copy-paste ready git configurations, and complete hook scripts. Nearly every section provides directly usable commands and templates. | 3 / 3 |
Workflow Clarity | Multi-step workflows like 'Starting a New Feature' and 'Conflict Resolution' are clearly sequenced with numbered steps. However, there are no explicit validation checkpoints or feedback loops — for example, the conflict resolution workflow doesn't include a step to verify the merge result is correct or that tests pass after resolution. | 2 / 3 |
Progressive Disclosure | The entire skill is a monolithic wall of text with no references to external files. Content like the full gitignore patterns, git hooks, git configuration, and the detailed PR template could easily be split into separate reference files. Everything is inlined in one massive document with no navigation structure beyond section headers. | 1 / 3 |
Total | 7 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (716 lines); consider splitting into references/ and linking | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
Reviewed
Table of Contents