Code Commit

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")

4. Create a conventional commit message 5. 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

5. 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.

Pull Request Workflow

Creating GitHub pull requests via the gh CLI.

Prerequisites

• gh CLI installed and authenticated: gh auth status
• Remote origin points to GitHub: git remote -v
• On a feature branch (not main): git branch --show-current

Check for Project Template

Before creating a PR, check if the project has its own PR template:

# Check for PR template in .github/
ls .github/PULL_REQUEST_TEMPLATE.md 2>/dev/null || echo "No project template found"

If found: Use it. The gh pr create command will automatically pick it up.

If not found: Use the minimal template below.

---

Create Pull Request

Option 1: Auto-fill from commits (recommended)

gh pr create --fill

This uses the commit messages as the PR title and body. Best when commits are clean and conventional.

Option 2: Interactive

gh pr create

Opens an editor with the template. Fill in title and body interactively.

Option 3: Inline (for simple PRs)

gh pr create --title "feat(auth): add JWT authentication" --body "Implements token-based auth with refresh support."

---

PR Title Format

Follow conventional commit style for PR titles:

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

Examples:

• feat(api): add user profile endpoint
• fix(db): resolve connection pool leak
• docs(readme): update installation instructions

---

PR Body Template (fallback if no project template)

## Description
<!-- What does this PR do? -->

## Changes
<!-- What changed? -->

## Testing
<!-- How was this tested? -->

## Checklist
- [ ] Tests pass
- [ ] Commits follow conventional format
- [ ] Documentation updated (if needed)

---

Linking Issues

Add issue references in the PR body:

Closes #123
Fixes #456
Relates to #789

This auto-closes linked issues when the PR merges.

---

Draft PRs

For work-in-progress PRs:

gh pr create --draft

Mark as ready later:

gh pr ready <pr-number>

---

Review Requests

Request reviewers after creating the PR:

gh pr edit <pr-number> --add-reviewer username

Or add via the GitHub web UI.

---

Verify PR Created

gh pr view --web  # Open in browser
gh pr status      # Show PR status

---

Common Mistakes