# Smart Commit

> This skill should be used when "write a commit message", "commit these changes", "create a commit", "what should my commit message be", "help me commit", "write conventional commits", "generate PR description", "create a pull request description", "write PR body".

- Skill: `kwokyc/smart-commit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kwokyc/smart-commit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kwokyc/smart-commit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: KwokYC (https://skillmd.com/u/kwokyc)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/kwokyc/smart-commit

---


# Smart Commit

Generate clear, conventional commit messages and PR descriptions from actual code changes.

## Commit Message Format

Follow [Conventional Commits](https://www.conventionalcommits.org/):

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

<body>

<footer>
```

### Types

| Type | When to use |
|------|------------|
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation only |
| `refactor` | Code change that neither fixes a bug nor adds a feature |
| `perf` | Performance improvement |
| `test` | Adding or updating tests |
| `chore` | Build process, CI, dependencies |
| `style` | Formatting, whitespace (no code change) |
| `ci` | CI/CD configuration |
| `revert` | Reverting a previous commit |

### Subject Rules

```
✅ feat(auth): add JWT refresh token support
✅ fix(api): handle null response in user endpoint
✅ refactor(db): extract connection pooling logic

❌ feat: update stuff
❌ fix: fixed bug
❌ WIP
❌ .
```

Rules:
- Use imperative mood: "add" not "added", "fix" not "fixed"
- Lowercase first letter
- No period at the end
- Max 72 characters
- Describe WHAT, not HOW

### Body (when needed)

```
feat(payments): add Stripe webhook handler

Add endpoint to handle Stripe payment_intent.succeeded events.
Updates order status and sends confirmation email on success.

Previously we only polled for payment status, which caused
delays of up to 30 seconds for order confirmation.
```

Rules:
- Wrap at 72 characters
- Explain WHY, not WHAT (the diff shows WHAT)
- Separate from subject with blank line
- Use present tense

### Footer

```
Fixes #123
Closes #456
BREAKING CHANGE: removed legacy API endpoint /v1/users
Co-authored-by: Name <email@example.com>
```

## How to Generate a Commit Message

```
1. Run: git diff --staged
2. Analyze what changed and why
3. Determine type (feat/fix/refactor/etc.)
4. Identify scope from file paths
5. Write subject: type(scope): what changed
6. Write body if change is non-trivial
7. Reference issue if applicable
```

### Scope Detection

```
Files in src/auth/ → scope: auth
Files in src/api/users → scope: users or api
Files in tests/ → scope: test (or match the feature scope)
Files in docs/ → docs type
package.json changes → chore type, no scope or deps scope
CI files → ci type
```

## Multi-File Commit Strategy

When changes span multiple concerns:

```
❌ Single commit: "update user module" (touches auth, API, DB, tests, docs)

✅ Split into:
  1. feat(db): add refresh_token column to users table
  2. feat(auth): implement JWT refresh token logic
  3. feat(api): add POST /auth/refresh endpoint
  4. test(auth): add refresh token tests
  5. docs(api): document refresh token endpoint
```

## PR Description Template

```markdown
## What

Brief description of what this PR does.

## Why

Why this change is needed. Link to issue or context.

## How

Key implementation decisions. Not line-by-line, but notable choices.

## Testing

- [ ] Unit tests added/updated
- [ ] Manual testing done (describe what)
- [ ] Edge cases considered

## Screenshots (if UI changes)

[Before] → [After]
```

## PR Description Rules

```
✅ PR Description:
## What
Add user avatar upload with S3 storage.

## Why
Users currently can't customize their profile. Issue #234.

## How
- Added presigned URL generation for S3 uploads
- Image resizing via Sharp on upload
- Max file size: 5MB, formats: jpg/png/webp

## Testing
- Unit tests for upload validation
- Integration test with S3 mock
- Manually tested with 10MB file (rejected), 4MB file (accepted)

❌ PR Description:
"updated user profile"
"fixes"
"changes"
```

## Commit Workflow

```
1. Stage specific files (not git add .)
   git add src/auth/jwt.ts src/auth/jwt.test.ts

2. Review what you're staging
   git diff --staged

3. Generate message based on actual changes
   - What files changed?
   - What's the net effect?
   - What type of change?

4. Write commit
   git commit -m "$(cat <<'EOF'
   feat(auth): add JWT refresh token logic

   Implement automatic token refresh when access token expires.
   Uses sliding window expiration with 7-day max lifetime.
   EOF
   )"
```

## Handling Special Cases

### Squash Commits
```
When merging PR, squash to one meaningful commit:
feat(payments): add Stripe integration (#123)
```

### Revert
```
revert: feat(auth): add SSO login support

This reverts commit abc123.
Reason: SSO provider has outage, reverting until resolved.
```

### WIP / Draft
```
Only in local branches, never in main/develop:
wip: exploring payment webhook approach

Squash before merge into meaningful commits.
```

## Quick Reference

```bash
# See staged changes
git diff --staged

# See recent commits for style reference
git log --oneline -10

# Amend last commit message (before push)
git commit --amend -m "better message"

# Interactive rebase to clean up commits
git rebase -i main
```

