Commit Message Creator

Commit Message Creator

This skill guides agents in creating clear, standards-compliant commit messages that follow the Conventional Commits specification with meaningful emojis.

When to Use This Skill

Use this skill when:

• Creating a commit message for code changes
• Reviewing or improving existing commit messages
• Asked to "commit", "write a commit message", or "create a commit"
• Ensuring consistent commit history
• Generating release notes from commits
• Following semantic versioning practices

Prerequisites

• Understanding of the code changes being committed
• Knowledge of related issue numbers or tickets
• Familiarity with the project's scope naming conventions
• Git repository with staged changes

Instructions

1. Identify the Commit Type

Choose the appropriate type with emoji:

2. Determine the Scope (Optional but Recommended)

Add contextual scope in parentheses:

For this project (nomos-provider-terraform-remote-state):

• provider - gRPC provider service implementation
• backend - Backend implementations (local, Azure, etc.)
• state - State parsing and handling logic
• config - Configuration management
• deps - Dependency updates
• spec - Specification/documentation in specs/ folder
• api - gRPC API contract changes

General common scopes:

• auth - Authentication
• api - API endpoints
• ui - User interface
• db - Database
• core - Core functionality

3. Write the Description

Follow these rules:

1. Use imperative, present tense

   • ✅ "add feature" NOT "added feature" or "adds feature"
   • Think: "This commit will..."

2. Don't capitalize first letter

   • ✅ "add two-factor authentication"
   • ❌ "Add two-factor authentication"

3. No period at the end

   • ✅ "fix race condition in user updates"
   • ❌ "fix race condition in user updates."

4. Maximum 72 characters

   • Keep it concise and scannable

5. Be specific and descriptive

   • ✅ "prevent race condition in user updates"
   • ❌ "fix bug"

4. Add Body (When Needed)

Include a body when:

• The change requires explanation beyond the subject
• You need to explain the "why" not the "what"
• Multiple related changes need listing
• Context is important for future maintainers

Body formatting:

• Separate from subject with a blank line
• Wrap at 72 characters
• Use bullet points for multiple items
• Explain what and why, not how

5. Add Footer (When Appropriate)

Include footer for:

Issue references:

Fixes #123
Closes #456, #789
Refs #999

Breaking changes:

BREAKING CHANGE: The /auth/login endpoint now requires email
instead of username. Update all API clients accordingly.

Co-authors:

Co-authored-by: Name <email@example.com>

6. Construct the Complete Message

Format:

<emoji> <type>[optional scope]: <description>

[optional body]

[optional footer]

Examples

Simple Feature

✨ feat(backend): add Azure Blob Storage backend support

Implements Azure backend for remote state storage using
Azure Storage SDK. Supports authentication via environment
variables following Azure standard patterns.

Closes #42

Bug Fix

🐛 fix(state): prevent panic on malformed state files

Add validation for state format version before parsing.
Return proper error instead of panicking when state file
is corrupted or has unsupported version.

Fixes #156

Documentation

📚 docs: update quickstart with Azure backend example

Add step-by-step guide for configuring Azure backend
including required environment variables and permissions.

Refactoring

♻️ refactor(provider): extract port discovery to separate function

Move port printing logic into dedicated function for
better testability and separation of concerns.

Performance

🚀 perf(state): optimize output parsing with lazy evaluation

Defer parsing of nested module outputs until accessed.
Reduces memory usage by 60% for large state files.

Tests

✅ test(backend): add integration tests for local backend

Cover file reading, missing file handling, and workspace
selection. Tests use temporary directories for isolation.

Build/Dependencies

🔧 build(deps): upgrade go to 1.25

Update go.mod and CI workflows to use Go 1.25.
Required for new generics features in state parser.

CI Changes

👷 ci: add race detection to test workflow

Run all tests with -race flag to catch concurrency issues.
Increases test time but catches critical bugs.

Breaking Change

✨ feat(api): change GetOutput to return typed values

BREAKING CHANGE: GetOutput now returns Value message with
type information instead of raw strings. Clients must
handle new Value structure.

Migration: Replace response.value with response.value.string_value
for string outputs. See migration guide in docs/.

Closes #234

Multiple Issues

🐛 fix(provider): resolve gRPC error handling issues

- Return proper gRPC status codes for all error cases
- Add NotFound for missing outputs
- Use InvalidArgument for configuration errors

Fixes #123, #124, #125

Revert

⏪ revert: "feat(backend): add S3 backend support"

This reverts commit abc123def456.

S3 backend implementation caused memory leaks in
long-running processes. Needs redesign before merge.

Refs #999

Best Practices

Do's ✅

• Use emoji prefix for visual context
• Keep subject line under 72 characters
• Use imperative mood ("add" not "added")
• Reference related issues/PRs
• Group related changes in single commit when logical
• Write for future maintainers
• Capitalize proper nouns (OAuth, HTTP, API, gRPC)
• Be specific about what changed and why

Don'ts ❌

• Don't use vague messages ("fix bug", "update code")
• Don't commit multiple unrelated changes together
• Don't use past tense ("fixed", "added")
• Don't capitalize first letter of description
• Don't add period at end of subject
• Don't forget to reference issues
• Don't commit directly to main branch
• Don't include debugging code or commented code

Semantic Versioning Impact

Your commit type affects version bumps:

• feat → Minor version (0.1.0 → 0.2.0)
• fix → Patch version (0.1.0 → 0.1.1)
• BREAKING CHANGE → Major version (0.1.0 → 1.0.0)

Git Workflow

# Stage your changes
git add <files>

# Commit with proper message
git commit -m "✨ feat(provider): add Azure backend support"

# For messages with body and footer, use editor
git commit
# Then write full message following format

Validation

Check your commit message:

• Emoji and type are correct
• Scope is appropriate (if used)
• Description uses imperative mood
• Description is lowercase
• No period at end of subject
• Subject is under 72 characters
• Body explains "why" not "how" (if present)
• Issue references included (if applicable)
• Breaking changes documented (if applicable)

Enforcement

Use commitlint for automated validation:

# Install
npm install --save-dev @commitlint/{config-conventional,cli}

# Configure .commitlintrc.json
{
  "extends": ["@commitlint/config-conventional"],
  "rules": {
    "type-enum": [2, "always", [
      "feat", "fix", "docs", "style", "refactor",
      "perf", "test", "build", "ci", "chore", "revert"
    ]]
  }
}

# Add to husky pre-commit hook
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

Troubleshooting

Issue: Commit message too long Solution: Move details to body, keep subject focused and under 72 chars

Issue: Unsure which type to use Solution: Use "feat" for user-facing changes, "refactor" for internal improvements

Issue: Multiple unrelated changes Solution: Split into separate commits - one logical change per commit

Issue: Forgot issue number Solution: Use git commit --amend to update message

Resources

• Conventional Commits Specification
• Commit Message Standards
• Semantic Versioning
• Gitmoji Guide
• How to Write a Git Commit Message