semantic-git — Claude Code skill: commits and installation
The semantic-git skill groups related changes into atomic commits and formats messages as Conventional Commits. Use it when an agent is preparing Git changes for commit.
MIT 201 installs ★ 22 updated 2026-03-21
npx skills add siviter-xyz/dot-agent --skill semantic-git -a claude-codeWhat semantic-git does
Before staging files, the skill asks the agent to check types, tests, and linting. If a check fails, it stops and reports the issue instead of moving on. Related files, such as implementation code and tests, are grouped into one commit, with a concise Conventional Commits message suggested.
The skill prints the exact git add and git commit commands, then asks whether the user wants to run them or have the agent do it. Execution requires explicit approval, and the agent confirms before preparing another commit. If zagi is available, the printed commands remain plain git commands and may be handled through an alias or wrapper.
What it helps with
- group related changes into atomic commits
- draft a Conventional Commits message
- review the exact staging and commit commands before execution
- run project checks before staging changes
Example prompts for the agent
- Prepare these changes for a commit, run the project checks, and group related files.
- Suggest a Conventional Commits message and show the commands without running them until I approve.
- Make a separate commit for the tests and print the commands first.
How to install semantic-git
1Skills CLI (Vercel)
npx skills add siviter-xyz/dot-agent --skill semantic-git -a claude-code2Manually: put the files in place
~/.claude/skills/semantic-git/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/semantic-git/
1Skills CLI (Vercel)
npx skills add siviter-xyz/dot-agent --skill semantic-git -a codex2Manually: put the files in place
.agents/skills/semantic-git/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add siviter-xyz/dot-agent --skill semantic-git -a cursor2Manually: put the files in place
.cursor/skills/semantic-git/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install siviter-xyz/dot-agent skills/semantic-git2Manually: put the files in place
.github/skills/semantic-git/SKILL.md1Skills CLI (Vercel)
npx skills add siviter-xyz/dot-agent --skill semantic-git -a gemini-cli2Platform CLI
gemini skills install https://github.com/siviter-xyz/dot-agent --path skills/semantic-gitManually: put the files in place
.devin/skills/semantic-git/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add siviter-xyz/dot-agent --skill semantic-git -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about semantic-git
How do I install semantic-git in Claude Code?
Run npx skills add siviter-xyz/dot-agent --skill semantic-git -a claude-code. The skill file is at ~/.claude/skills/semantic-git/SKILL.md.
What does semantic-git do?
It helps organize atomic Git commits, drafts Conventional Commits messages, and displays commands before execution. The agent needs explicit user approval to run them.
What happens if a CI check fails?
The skill stops and reports the failure before staging any files.
Source text
SKILL.md · MIT
---
name: semantic-git
description: Manage Git commits using conventional commit format with atomic staging. Always generate plain git commands before running them and offer to let the user run them manually.
---
# Semantic Git
Manage Git commits using conventional commit format with atomic commits and concise messages.
This skill is **zagi-aware** and is designed to work well with AI IDEs (Cursor, etc.)
## Tooling
- **Preferred**: [`zagi`](https://github.com/mattzcarey/zagi) (a better git interface for agents).
- Assume zagi is installed if:
- `git` is aliased to zagi in the shell **or**
- a `zagi` binary is available.
- When in doubt, treat `git` as if it may be zagi-compatible and avoid using exotic flags.
- Even when zagi is available, **generate plain `git` commands** and let any `git` → `zagi` integration handle them.
- **Fallback**: plain `git` when zagi is not available.
## When to Use
- Committing changes to git
- Staging files for commit
- Creating commit messages
- Managing atomic commits
- Before pushing changes
## Core Principles
- **Atomic commits**: Stage and commit related changes together. Tests go with implementation code.
- **User confirmation**: Always confirm with user before committing and before moving to the next commit.
- **Conventional format**: Use conventional commit message format (feat, fix, etc.) unless directed otherwise.
- **Concise messages**: Keep messages brief and to the point. Omit description unless change is complicated.
- **Command transparency**: Always show the exact `git` commands that will be run (which may be handled by zagi via alias/wrapper), and ask whether the user wants:
- to run them manually, or
- to have the agent run them.
## Commit Message Format
```
<type>[optional scope]: <subject>
[optional body]
[optional footer(s)]
```
### Types
- `feat`: A new feature
- `fix`: A bug fix
- `docs`: Documentation only changes
- `style`: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.)
- `refactor`: A code change that neither fixes a bug nor adds a feature
- `perf`: A code change that improves performance
- `test`: Adding missing tests or correcting existing tests
- `build`: Changes that affect the build system or external dependencies
- `ci`: Changes to CI configuration files and scripts
- `chore`: Maintenance tasks (updating build tasks, dependencies, etc.; no production code change)
- `revert`: Revert a previous commit
### Breaking Changes
Use `!` after the type/scope to indicate breaking changes:
- `feat!: add new API`
- `fix(api)!: change response format`
### Subject Line
- Use imperative mood: "add feature" not "added feature" or "adds feature"
- First letter lowercase (unless starting with proper noun)
- No period at the end
- Keep under 72 characters when possible
### Body and Footer
- Omit body unless change is complicated or requires explanation
- When needed, be concise and reference issues, PRs, or documentation
- Use footer for breaking changes: `BREAKING CHANGE: <description>`
## Workflow
1. **Implement atomic change**: Code + tests together.
- Use `test:` for test-only changes.
2. **Run CI checks**: Verify types, tests, and linting pass before staging.
- Prefer a single CI command if it exists (e.g., `pnpm ci`, `npm run ci`, `just ci`).
- If no CI command, run checks individually (typecheck, test, lint).
- If any check fails, stop and report – do not proceed.
3. **Stage atomic changes**: Group related files together (implementation + tests).
4. **Suggest commit message**: Generate a conventional commit message based on changes.
5. **Generate commands**:
- Construct explicit shell commands using `git` (which may be an alias or wrapper such as zagi), for example:
```bash
git add path/to/file1 path/to/file2
GIT_AUTHOR_DATE="YYYY-MM-DD HH:MM:SS" \
GIT_COMMITTER_DATE="YYYY-MM-DD HH:MM:SS" \
git commit -m "feat: add feature"
```
- Always **print these commands** to the user in order.
6. **Ask for execution preference**:
- Ask the user whether they want:
- to copy-paste and run the commands themselves, or
- to have the agent run them.
- Only execute commands after explicit user approval.
7. **Commit**:
- When executing, run **exactly** the printed commands.
- Respect any user instructions about backdating timestamps or additional flags.
8. **Next commit**:
- Before staging the next set of changes, confirm with the user that the previous commit is complete and understood.
## Automation Mode
If user requests "continue to X" or "automate until X":
- Proceed with atomic commits automatically, **but still print commands**.
- For each commit:
- Show the staging and commit commands.
- Optionally execute them automatically, as per the user’s automation request.
- Resume asking for confirmation when X is reached.
- X can be: specific file, feature completion, test passing, etc.
## Stop and Ask Protocols
Stop and ask user before:
- Adding type ignores (`@ts-ignore`, `# type: ignore`, etc.).
- Adding suppressions (ESLint disable, pylint disable, etc.).
- Using `any` type or similar type escapes.
- When uncertain how to proceed with implementation.
- When requirements are unclear.
- When a destructive git operation is proposed (`reset --hard`, `checkout .`, `clean -f`, `push --force`); prefer safer alternatives and explain the risks.
## Examples
**Simple feature or behaviour change:**
```
feat: add user authentication
```
**Feature with scope:**
```
feat(api): add user endpoint
```
**Bug fix:**
```
fix: resolve memory leak in cache
```
**Breaking change:**
```
feat!: migrate to new API version
```
**Test-only change:**
```
test: improve unit tests for auth service
```
**Refactor (no behavior change):**
```
refactor: extract validation logic into separate function
```
**Complex change (with body):**
```
feat(api): add pagination support
Implements cursor-based pagination for large datasets.
See docs/api/pagination.md for details.
```
## References
For detailed guidance, see:
- `references/conventional-commits.md` – Commit format and examples
- `references/ci-verification.md` – CI check patterns and verification
- `references/co-authors.md` – Handling Co-Authored-By trailers and zagi co-author stripping
© siviter-xyz · MIT · siviter-xyz/dot-agent