conventional-commits

majiayu000

Updated Yesterday

Metageneral

About

This skill helps developers follow the Conventional Commits specification when creating, analyzing, or reviewing git commits in Aurora projects. It automatically triggers during commit operations, git history analysis, or when users mention conventional commits. The skill enforces structured commit messages with types like feat, fix, and scope formatting.

Quick Install

Claude Code

Recommended

Plugin CommandRecommended

/plugin add https://github.com/majiayu000/claude-skill-registry

Git CloneAlternative

git clone https://github.com/majiayu000/claude-skill-registry.git ~/.claude/skills/conventional-commits

Copy and paste this command in Claude Code to install this skill

Documentation

When to Use

User asks to create a commit or "commit changes"
User asks to review git status or diff
User wants to analyze commit history
After completing features/fixes that need to be committed
User mentions "conventional commits" or asks about commit format

Critical Patterns

Commit Format

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

[optional body]

[optional footer]

Types (in order of usage frequency)

Type	Description	Example
`feat`	New functionality	`feat(library/book): add ISBN validation`
`fix`	Bug fix	`fix(auth): resolve token refresh race condition`
`refactor`	Code refactoring, no functional change	`refactor(core): extract validation logic to service`
`test`	Add or modify tests	`test(book): add unit tests for create handler`
`docs`	Documentation changes	`docs(readme): add installation instructions`
`chore`	Maintenance tasks	`chore(deps): update nestjs to v10`
`style`	Formatting, semicolons, etc.	`style(api): apply prettier formatting`
`perf`	Performance improvements	`perf(query): optimize book search with index`
`ci`	CI/CD changes	`ci(github): add deployment workflow`
`build`	Build system or dependencies	`build(docker): optimize production image`
`revert`	Revert previous commit	`revert: feat(book): add ISBN validation`

Subject Rules

✅ Use imperative mood: "add" NOT "added" or "adds"
✅ Lowercase first letter
✅ No period at the end
✅ Maximum 120 characters
✅ Describe WHAT, not HOW

Good:

feat(book): add publication date validation
fix(auth): resolve token refresh issue

Bad:

feat(book): Added publication date validation (past tense)
fix(auth): Resolve token refresh issue (uppercase)
feat(book): add publication date validation. (period)

Body Rules (Optional)

Separate from subject with blank line
Explain WHY, not WHAT
Wrap at 72 characters per line
Can use bullet points with -

Footer Rules (Optional)

Reference issues: Closes #123, Fixes #456
Breaking changes: BREAKING CHANGE: <description>
❌ NEVER add "Co-Authored-By" or AI attribution

Commit Workflow

1. Analyze Changes

git status                # See modified/untracked files
git diff                  # See unstaged changes
git diff --staged         # See staged changes
git log --oneline -10     # See recent commit style

2. Group Related Changes

Rules:

One commit = one logical change
❌ Don't mix features with fixes
❌ Don't mix multiple unrelated modules
✅ Multiple files are OK if they implement one feature

3. Generate Message

Analyze the changes and determine:

Type: feat, fix, refactor, etc.
Scope: Which module/component is affected?
Subject: What does this change do?
Body (if needed): Why was this change necessary?
Footer (if needed): Issue references, breaking changes

4. Execute Commit

git add <files>
git commit -m "$(cat <<'EOF'
<type>(<scope>): <subject>

<body>

<footer>
EOF
)"

Code Examples

Simple Feature

feat(library/book): add publication date validation

Validate that publication date is not in the future
when creating or updating a book.

Closes #234

Bug Fix with Context

fix(auth): resolve token refresh race condition

Multiple simultaneous requests could trigger parallel
token refreshes, causing some requests to fail.

- Add mutex lock during refresh
- Queue pending requests until refresh completes
- Add retry logic for failed requests

Fixes #567

Refactor (No Functional Change)

refactor(library/book): extract ISBN validation to service

Move ISBN validation logic from command handler to
dedicated IsbnValidatorService for reusability.

No functional changes.

Breaking Change

feat(api)!: change pagination response format

BREAKING CHANGE: Pagination response now uses cursor-based
format instead of offset-based.

Before: { items: [], total: 100, page: 1 }
After: { items: [], nextCursor: "abc", hasMore: true }

Migration guide in docs/migration/v2-pagination.md

Aurora YAML Changes

feat(aurora): add category entity to library module

Define new Category aggregate with:
- id, name, description fields
- many-to-many relation with Book

Run: aurora load back module -n=library/category

Dependency Update

chore(deps): update @nestjs packages to v10.2.0

- @nestjs/core: 10.1.0 -> 10.2.0
- @nestjs/common: 10.1.0 -> 10.2.0
- @nestjs/platform-express: 10.1.0 -> 10.2.0

No breaking changes in this update.

Multiple Modules (Related Change)

feat(tesla): add maintenance validation across models

- Add validation in Model aggregate
- Update MaintenanceHistory to check model status
- Add integration tests for both modules

This ensures consistency when creating maintenance records.

Commands

# View status
git status

# View changes
git diff                    # Unstaged changes
git diff --staged          # Staged changes
git diff --cached          # Same as --staged

# Stage files
git add <file>             # Stage specific file
git add -p                 # Interactive staging (choose hunks)

# Commit
git commit -m "message"    # Simple commit
git commit                 # Opens editor for body

# View history
git log --oneline -20                      # Last 20 commits
git log --pretty=format:"%h %s" -20       # Custom format
git log --graph --oneline --all           # Visual graph

# Amend last commit (use with caution)
git commit --amend -m "new message"       # Change message
git commit --amend --no-edit              # Add files to last commit

Anti-Patterns to Avoid

❌ Bad	✅ Good
`git commit -m "fix"`	`fix(auth): resolve token expiration bug`
`git commit -m "WIP"`	Finish the work or use feature branch
`git commit -m "changes"`	`refactor(core): extract common validation logic`
`git commit -m "update files"`	`feat(book): add ISBN field to entity`
`git commit -am "everything"`	Split into logical commits
Mix feat + fix + refactor	Separate commits for each type
Commit generated files only	Commit YAML changes + explain regeneration

Aurora-Specific Notes

1. YAML Changes

feat(aurora): add category entity to library module

Define new Category aggregate with id, name, description.

Run: aurora load back module -n=library/category

2. Custom Logic in Generated Files

feat(library/book): add complex ISBN validation logic

Implement custom validation in CreateBookHandler:
- Validate ISBN format (10 or 13 digits)
- Check checksum digit
- Verify not in blacklist

This logic is in a generated file marked as custom.

3. Multiple Related Modules

feat(tesla): integrate maintenance history with models

- Update Model aggregate with maintenance status
- Add validation in MaintenanceHistory creation
- Add integration tests

Changes span tesla/model and tesla/maintenance-history.

4. Test Commits

Option A: Combined with feature

feat(book): add ISBN validation with tests

- Add ISBN validation in CreateBookHandler
- Add unit tests for validation logic
- Add e2e tests for create endpoint

Option B: Separate commit

test(book): add unit tests for ISBN validation

Add comprehensive test coverage for:
- Valid ISBN-10 and ISBN-13 formats
- Invalid formats and checksums
- Edge cases (empty, null, special chars)

Decision Trees

Should I commit now?

Has code changed? ────NO───> No commit needed
      │
     YES
      │
Is it a logical unit? ────NO───> Break into smaller commits
      │
     YES
      │
Do tests pass? ────NO───> Fix tests first
      │
     YES
      │
  Create commit

What type should I use?

New functionality? ────YES───> feat
      │
      NO
      │
Fixing a bug? ────YES───> fix
      │
      NO
      │
No functional change? ────YES───> refactor
      │
      NO
      │
Only tests? ────YES───> test
      │
      NO
      │
Dependencies? ────YES───> chore(deps)
      │
      NO
      │
Documentation? ────YES───> docs
      │
      NO
      │
    Default: chore

How to scope?

Single module changed? ────YES───> Use <bc>/<module>
      │
      NO
      │
Multiple related modules? ────YES───> Use common <bc> or higher scope
      │
      NO
      │
Infrastructure? ────YES───> Use: ci, docker, config, deps
      │
      NO
      │
Core/API/GraphQL? ────YES───> Use: core, api, graphql
      │
      NO
      │
    Omit scope or use project name

Related Skills

This skill works with:

aurora-cli: Commit YAML changes and regenerated code
aurora-development: Commit business logic implementations (feat commits)
jest-nestjs: Commit test files (test commits or include with feat)
logger: Log commit information in session reports

Workflow:

Make changes (YAML modifications, business logic, tests)
Use aurora-cli to regenerate code (if YAML changed)
Use conventional-commits to create proper commit
Use logger to document the session (optional)

Resources

Specification: https://www.conventionalcommits.org/
Aurora Config: commitlint.config.js (read this for project-specific rules)
Git Hooks: Pre-commit hooks may enforce format validation

GitHub Repository

majiayu000/claude-skill-registry

Path: skills/conventional-commits

Related Skills

algorithmic-art

subagent-driven-development

Development

This skill executes implementation plans by dispatching a fresh subagent for each independent task, with code review between tasks. It enables fast iteration while maintaining quality gates through this review process. Use it when working on mostly independent tasks within the same session to ensure continuous progress with built-in quality checks.

View skill

executing-plans

Design

Use the executing-plans skill when you have a complete implementation plan to execute in controlled batches with review checkpoints. It loads and critically reviews the plan, then executes tasks in small batches (default 3 tasks) while reporting progress between each batch for architect review. This ensures systematic implementation with built-in quality control checkpoints.

View skill

cost-optimization

Other

This Claude Skill helps developers optimize cloud costs through resource rightsizing, tagging strategies, and spending analysis. It provides a framework for reducing cloud expenses and implementing cost governance across AWS, Azure, and GCP. Use it when you need to analyze infrastructure costs, right-size resources, or meet budget constraints.

View skill