# Conventional Commit Gen

> Analyzes git diff to generate commit messages following the Conventional Commits spec, with automatic scope detection and commit type inference. Trigger when users ask to write or generate a commit message, mention Conventional Commits, git commits, standardized commits, scope detection, or phrases like 'help me write a commit message'.

- Skill: `serejaris/conventional-commit-gen` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add serejaris/conventional-commit-gen`
- Raw SKILL.md: https://api.skillmd.com/api/skills/serejaris/conventional-commit-gen/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: serejaris (https://skillmd.com/u/serejaris)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/serejaris/conventional-commit-gen

---


# Conventional Commit Gen

Analyzes the current git diff and automatically generates a commit message that follows the [Conventional Commits](https://www.conventionalcommits.org/) specification, with smart scope detection.

## Quick Start

```bash
# Analyze unstaged changes and generate a commit message
python3 scripts/analyze_diff.py

# Analyze staged changes only
python3 scripts/analyze_diff.py --staged

# Specify a repository path
python3 scripts/analyze_diff.py --repo /path/to/repo

# JSON output (useful for programmatic integration)
python3 scripts/analyze_diff.py --staged --format json

# Manually override type or scope
python3 scripts/analyze_diff.py --staged --type-override feat --scope-override auth
```

## Usage Workflow (SOP)

### 1. Get the Diff Analysis

Run the script in the user's git repository to get the automated analysis:

```bash
python3 scripts/analyze_diff.py --staged --format json
```

### 2. Review and Adjust

The script outputs:
- **type**: The auto-detected commit type (feat / fix / docs / style / refactor / test / chore / perf / ci / build)
- **scope**: The scope detected from file paths (e.g., auth, api, ui)
- **description**: A brief description generated from the change summary
- **commit_message**: The fully assembled commit message

After reviewing the output, adjust as needed:
- If the type is inaccurate (e.g., the script detected `chore` but it's actually a `feat`), use `--type-override` to override
- If the scope doesn't fit, use `--scope-override` to override
- The description should ideally be hand-written based on the actual changes; treat the script output as a starting point

> **Note**: Type detection is based on file paths and change statistics. It works well for types like test/docs/ci/build, but for modifications to existing source code files (feat vs fix vs refactor), you should read the diff content and make the final call.

### 3. Conventional Commits Reference

```
<type>(<scope>): <description>

[optional body]

[optional footer(s)]
```

| Type       | Meaning                                    |
|------------|--------------------------------------------|
| `feat`     | A new feature                              |
| `fix`      | A bug fix                                  |
| `docs`     | Documentation changes                      |
| `style`    | Code formatting (no logic changes)         |
| `refactor` | Refactoring (no new features or bug fixes) |
| `test`     | Test-related changes                       |
| `chore`    | Build/tooling/dependency maintenance       |
| `perf`     | Performance improvements                   |
| `ci`       | CI/CD configuration changes                |
| `build`    | Build system or external dependency changes|

### 4. Breaking Changes

If the change includes a breaking change, add `!` after the type:

```
feat(api)!: change authentication endpoint response format
```

## Parameters

| Parameter           | Description                                       | Default  |
|---------------------|---------------------------------------------------|----------|
| `--repo`            | Path to the git repository                        | `.`      |
| `--staged`          | Analyze staged changes only                       | No       |
| `--format`          | Output format: `text` or `json`                   | `text`   |
| `--type-override`   | Manually specify the commit type, skipping auto-detection | None |
| `--scope-override`  | Manually specify the scope, skipping auto-detection | None   |

## Prerequisites

- Python 3.6+
- git installed and available in PATH
- Current directory or `--repo` points to a valid git repository