Conventional Commit Skill

Generate and validate commit messages following the Conventional Commits specification.

Conventional Commit Format

<type>(<scope>): <subject>

[optional body]

[optional footer(s)]

Types

Rules

• Subject: Short description, imperative mood, lowercase, no period at end
• Scope: Optional, lowercase, describes what was changed (e.g., auth, api, ui)
• Breaking changes: Add ! after type/scope: feat(auth)!: change API
• Footer: For breaking changes (BREAKING CHANGE:) or issue references (Closes #123)

Operations

1. Generate Commit from Diff

When user wants to commit changes:

1. Run git status to see changed files
2. Run git diff --staged for staged changes
3. Analyze what changed to determine:

• Type: Which type best describes the changes?
• Scope: What area was affected? (optional)
• Subject: What was done? (imperative: "add" not "added")

1. Create a conventional commit message
2. Run git commit -m "<message>"

Example:

feat(auth): add JWT token refresh

Implements token refresh endpoint to extend sessions
without requiring re-authentication.

Closes #142

2. Validate Commit Message

When user asks to validate or check a commit message:

1. Parse the commit message
2. Check format: <type>(<scope>): <subject>
3. Validate type is from the allowed list
4. Check subject follows rules (lowercase, imperative, no period)
5. Flag any issues found

3. Create Pull Request

When user wants to open a PR or after finishing commits on a feature branch:

1. Verify on a feature branch (not main): git branch --show-current
2. Check for project PR template: ls .github/PULL_REQUEST_TEMPLATE.md
3. Push branch if needed: git push -u origin <branch>
4. Create PR via gh pr create:

• Use --fill if commits are clean (auto-populates title/body)
• Use --draft for work-in-progress
• Use interactive mode if body needs custom content

1. Show the PR URL to the user

See references/pr-workflow.md for full workflow details.

Input Methods

Auto-Commit Workflow

When generating a commit:

1. Show the user the commit message first
2. Ask for confirmation before committing (unless user explicitly says "just do it")
3. Execute git commit -m "<message>" after confirmation
4. Show the result of the commit

Error Handling

• If no staged changes: git status shows nothing → warn user nothing to commit
• If git not initialized: Initialize repo or warn user
• If commit fails: Show error and offer to retry

Examples

Input: "I fixed the login bug" Output:

fix(auth): resolve login timeout issue

Users were logged out after 5 minutes due to
incorrect token expiry calculation.

Input: "I added a new API endpoint for users" Output:

feat(api): add user profile endpoint

GET /users/:id returns user profile data including
name, email, and avatar URL.

Closes #89

Input: "I changed the auth API, this breaks old clients" Output:

feat(auth)!: change token validation endpoint

The /auth/verify endpoint now requires Bearer token
instead of query parameter.

BREAKING CHANGE: Clients must update to send
Authorization header with Bearer token.