Git Commit Skill
Relevant source files
The following files were used as context for generating this wiki page:The git-commit skill is a workflow-based capability designed for AI agents to create clear, atomic, and conventional git commits. It does not have a direct entry script but provides a structured process for agents to follow. The primary goal is to ensure commit messages are consistent with project standards, either by detecting existing conventions or by applying the Conventional Commits specification as a fallback. This skill is typically triggered automatically after an agent has completed a piece of work that successfully builds and passes all tests.
This skill emphasizes a "commit early, commit often" philosophy, promoting the creation of small, logical, and revertible changes. It is an integral part of the development lifecycle, interacting with other skills like code-quality and docs-check to ensure a robust and maintainable codebase.
Sources: skills/git-commit/SKILL.md:1-8, 10-12, skills/README.md:10, AGENTS.md:25
Core Workflow
The skill defines a four-step workflow for an agent to construct a valid commit message. The process begins with analyzing the project's history and configuration to ensure compliance with established patterns.
Sources: skills/git-commit/SKILL.md:26-30
This diagram illustrates the sequential process an agent follows when using the git-commit skill.
Step 1: Detect Project Conventions
Before formatting a commit, the agent must first inspect the project for existing commit message conventions. This is a mandatory step to ensure consistency. The agent uses shell commands to look for configuration files and recent commit history.
Sources: skills/git-commit/SKILL.md:30-32
The agent's action is determined by the findings from these commands:
ls .commitlintrc* commitlint.config.* .czrc .cz.json 2>/dev/null
git log --oneline -15
Sources: skills/git-commit/SKILL.md:33-34
| Finding | Action |
|---|---|
Config file exists (.commitlintrc, .czrc, etc.) | Follow the rules defined in the file exactly. |
feat:, fix: pattern in git log | Use Conventional Commits. |
[JIRA-123] pattern in git log | Match the ticket prefix format. |
Component: message pattern in git log | Match the component prefix format. |
| No clear pattern found | Default to using Conventional Commits. |
Sources: skills/git-commit/SKILL.md:36-42
Step 2: Format Message (Conventional Commits)
If no overriding project convention is found, the skill defaults to the Conventional Commits format. The message is composed of a subject, an optional body, and an optional footer.
The structure of a Conventional Commit message is as follows.
Sources: skills/git-commit/SKILL.md:44-50
Subject Line
The subject line has a strict format and should ideally be under 50 characters (72 max).
<type>: Describes the kind of change.(<scope>): Optional, specifies the part of the codebase affected.!: Optional, indicates a breaking change.<subject>: A short description in the imperative mood (e.g., "add" not "added").
Sources: skills/git-commit/SKILL.md:44-54
Commit Types
The <type> tag is crucial as it can influence semantic versioning.
| Type | Purpose | SemVer Impact | Example |
|---|---|---|---|
feat | A new feature | MINOR | feat(auth): add OAuth |
fix | A bug fix | PATCH | fix(cart): prevent neg qty |
docs | Documentation only changes | - | docs(api): add examples |
style | Code style changes (formatting, etc.) | - | style: fix indentation |
refactor | A code change that neither fixes a bug nor adds a feature | - | refactor: extract helper |
perf | A code change that improves performance | - | perf(db): add index |
test | Adding missing tests or correcting existing tests | - | test(auth): add edge cases |
build | Changes that affect the build system or external dependencies | - | build: update webpack |
ci | Changes to CI configuration files and scripts | - | ci: add deploy workflow |
chore | Other changes that don't modify src or test files | - | chore: update gitignore |
revert | Reverts a previous commit | - | revert: let us not... |
Sources: skills/git-commit/SKILL.md:56-70
Step 3: Body
The body is optional and used to provide additional context. It should explain the "why" and "what" of the change, not the "how".
A body is required for:
- Breaking changes: Must explain the impact and migration path.
- Non-obvious fixes: Should detail the root cause.
- Complex features: Can describe design decisions.
Sources: skills/git-commit/SKILL.md:78-87
Step 4: Footer
The footer is optional and used for metadata, such as referencing issues or declaring breaking changes.
Example footer lines:
Closes #123
Fixes #456
Refs: #789
BREAKING CHANGE: <description>
Co-authored-by: Name <email@example.com>
Sources: skills/git-commit/SKILL.md:89-96
Commit Granularity
The skill mandates the use of "atomic commits," which are defined as the smallest complete and working change. This practice is essential for easy rollbacks and effective debugging with tools like git bisect.
Sources: skills/git-commit/SKILL.md:13-16, 98-104
Commit Grouping Rules
| Group in a Single Commit | Create Separate Commits |
|---|---|
| A feature and its corresponding unit tests. | A feature and unrelated code formatting. |
| A bug fix and its regression test. | A bug fix and a dependency update. |
| An API change and its documentation update. | A refactor and a new feature. |
| A refactor and updates to affected tests. | Multiple unrelated bug fixes. |
Sources: skills/git-commit/SKILL.md:106-111
When to Commit
The skill provides clear triggers for when to create a commit, following a "verify-then-commit" workflow. A commit should only be made when the code is in a stable, working state.
This flowchart shows the decision process for committing changes.
Commits should not be made if:
- The code does not build.
- Tests are failing (except for TDD red-phase commits).
- The work is untested or mid-debug.
- CI is red.
Sources: skills/git-commit/SKILL.md:122-132
Integration with Other Skills
The git-commit skill is designed to work in sequence with other skills in the ai-dev-atelier pack to form a complete development loop.
This sequence diagram shows the typical interaction between skills during a development task.
Summary
The git-commit skill provides a robust framework for AI agents to create high-quality, conventional, and atomic commits. By enforcing a "detect-then-format" approach and a "verify-then-commit" workflow, it ensures that the project's version history remains clean, understandable, and consistent. Its integration with other quality and documentation skills makes it a cornerstone of the automated development process within the AI Dev Atelier ecosystem.
Sources: skills/git-commit/SKILL.md, skills/README.md