---
name: commit-message
description: This skill should be used when the user asks to "create a commit", "generate commit message", "commit changes", "make a commit", mentions "conventional commits", or discusses commit message formatting. Provides guided workflow for creating properly formatted commit messages with line length validation and required trailers.
version: 0.2.0
---

# Conventional Commit Message Creation

Create properly formatted conventional commit messages following project standards with line length validation and required trailers.

## Purpose

Generate commit messages that:

- Follow conventional commits format (`type(scope): description`)
- Use component names or GitHub issue numbers as scope
- Respect line length limits (50 for subject, 72 for body)
- Include required trailers (Signed-off-by, Assisted-by)
- Match [Tekton commit message standards](https://github.com/tektoncd/community/blob/master/standards.md#commit-messages)

## Quick Workflow

1. **Analyze changes**: Run git status and git diff to understand modifications
2. **Determine scope**: Use component name from changed files, or GitHub issue number if available
3. **Generate message**: Create conventional commit message with proper formatting
4. **Add trailers**: Include Signed-off-by and Assisted-by trailers
5. **Confirm with user**: Display message and wait for approval before committing

**CRITICAL**: Never commit without explicit user confirmation.

## Conventional Commit Format

### Structure

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

[optional body]

Signed-off-by: <name> <email>
Assisted-by: <Model name> (via <Tool>)
```

### Type Selection

Choose the appropriate commit type based on changes:

| Type | Description | Example |
| ------ | ------------- | --------- |
| `feat` | New features | `feat(pipeline): add start --output flag` |
| `fix` | Bug fixes | `fix(taskrun): resolve log streaming race` |
| `docs` | Documentation | `docs(README): update installation steps` |
| `refactor` | Code refactoring | `refactor(actions): simplify CRUD helpers` |
| `test` | Test changes | `test(pipelinerun): add describe unit tests` |
| `chore` | Maintenance | `chore(deps): update go dependencies` |
| `build` | Build system | `build(Makefile): add vendor target` |
| `ci` | CI/CD changes | `ci(github): add golangci-lint action` |
| `perf` | Performance | `perf(log): optimize pod log streaming` |
| `style` | Code style | `style(format): run goimports formatter` |
| `revert` | Revert commit | `revert: undo breaking CLI flag change` |

For complete type reference, see `references/commit-types.md`.

### Scope Rules

#### Priority 1: Component from changed files

Analyze staged files to identify the primary component:

```bash
git diff --cached --name-only
```

| File pattern | Scope | Example commit |
| ------------ | ----- | -------------- |
| `pkg/cmd/pipeline/*` | `pipeline` | `feat(pipeline): add start --dry-run flag` |
| `pkg/cmd/task/*` | `task` | `fix(task): resolve list filtering` |
| `pkg/cmd/pipelinerun/*` | `pipelinerun` | `feat(pipelinerun): add cancel subcommand` |
| `pkg/cmd/taskrun/*` | `taskrun` | `fix(taskrun): correct log streaming` |
| `pkg/actions/*` | `actions` | `refactor(actions): simplify CRUD` |
| `pkg/formatted/*` | `formatted` | `feat(formatted): add JSON output` |
| `pkg/log/*` | `log` | `fix(log): handle container restart` |
| `pkg/pods/*` | `pods` | `fix(pods): resolve container lookup` |
| `pkg/cli/*` | `cli` | `refactor(cli): extract client setup` |
| `pkg/flags/*` | `flags` | `feat(flags): add --output flag` |
| `pkg/plugins/*` | `plugins` | `feat(plugins): add discovery logic` |
| `pkg/version/*` | `version` | `fix(version): correct server detection` |
| `docs/*` | `docs` or filename | `docs(README): update steps` |
| `test/*` | component being tested | `test(pipeline): add E2E tests` |
| `cmd/*` | command name | `feat(tkn): add new subcommand` |
| Root files | filename | `chore(Makefile): add target` |
| `AGENTS.md`, `CLAUDE.md` | `docs` | `docs(AGENTS.md): update conventions` |

#### Priority 2: GitHub issue number (optional)

If the work is tracked in a GitHub issue and the user provides one, it can be used as the scope:

```text
# Branch: fix-123-log-race
# Scope: #123 or component name
# Result: fix(log): resolve streaming race condition

Fixes #123
```

Add `Fixes #NNN` or `Closes #NNN` in the commit body (not the scope) — this is the standard GitHub convention for auto-closing issues.

#### Priority 3: Ask user

If changed files span multiple components or scope is unclear, ask the user which component is the primary focus.

## Line Length Requirements

### Subject Line

- **Target**: 50 characters maximum
- **Hard limit**: 72 characters
- **Format**: `type(scope): description` counts toward limit
- **Tips**: Use present tense, no period at end

```text
# Good (40 chars)
feat(pipeline): add start --dry-run

# Too long - exceeds 72 char hard limit
feat(pipeline): add comprehensive dry-run support with preview output for pipeline start command
```

### Body

- **Wrap at 72 characters per line**
- **Blank line** required between subject and body
- **Content**: Explain why, not what (code shows what)
- **Format**: Wrap manually or use heredoc in git commit

```text
feat(pipeline): add start --dry-run

Add dry-run flag to pipeline start command that previews the
PipelineRun YAML without creating it. Useful for validating
parameters and workspace bindings before submission.

Signed-off-by: Developer Name <developer@example.com>
Assisted-by: <Model name> (via <Tool>)
```

## Required Trailers

### Signed-off-by

**Always include**: `Signed-off-by: <name> <email>`

This certifies the Developer Certificate of Origin (DCO) — required by tektoncd upstream.

**Detection priority order**:

1. Environment variables: `$GIT_AUTHOR_NAME` and `$GIT_AUTHOR_EMAIL`
2. Git config: `git config user.name` and `git config user.email`
3. If neither configured, ask user to provide details

```bash
echo "$GIT_AUTHOR_NAME <$GIT_AUTHOR_EMAIL>"
git config user.name
git config user.email
```

If neither is configured, ask the user to provide their name and email.

### Assisted-by

**Always include**: `Assisted-by: <model-name> (via <Tool>)`

**Format examples**:

```text
Assisted-by: <Model name> (via <Tool>)
```

Use the actual model name (Claude Sonnet 4.5, Claude Opus 4.5, etc.).

## User Confirmation Requirement

**CRITICAL RULE**: Always ask for user confirmation before executing `git commit`.

### Confirmation Workflow

1. **Generate** the commit message following all rules above
2. **Display** the complete message to the user with separator
3. **Ask**: "Should I commit with this message? (y/n)"
4. **Wait** for user response
5. **Commit** only if user confirms (yes/y/affirmative)

### Example Interaction

```text
Generated commit message:
---
feat(pipeline): add JSON output support

Add --output=json flag to pipeline list and describe commands.
Uses the existing formatted package JSON helpers.

Signed-off-by: Developer Name <developer@example.com>
Assisted-by: <Model name> (via <Tool>)
---

Should I commit with this message? (y/n)
```

Wait for user response before proceeding.

## Commit Execution

Use heredoc format for proper multi-line handling:

```bash
git commit -m "$(cat <<'EOF'
feat(pipeline): add JSON output support

Add --output=json flag to pipeline list and describe commands.

Signed-off-by: Developer Name <developer@example.com>
Assisted-by: <Model name> (via <Tool>)
EOF
)"
```

**Never use**:

- `--no-verify` (skips pre-commit hooks)
- `--no-gpg-sign` (skips signing)
- `--amend` (unless explicitly requested and safe)

## Complete Examples

### Feature with component scope

```text
feat(pipeline): add start --dry-run

Add dry-run flag to pipeline start command that previews the
PipelineRun YAML without creating it on the cluster.

Signed-off-by: Developer Name <developer@example.com>
Assisted-by: <Model name> (via <Tool>)
```

### Bug fix closing a GitHub issue

```text
fix(log): resolve concurrent streaming panic

Prevent nil pointer dereference when multiple containers stream
logs simultaneously during a TaskRun.

Fixes #789

Signed-off-by: Developer Name <developer@example.com>
Assisted-by: <Model name> (via <Tool>)
```

### Documentation update

```text
docs(AGENTS.md): update architecture conventions

Add command tree structure and clarify golden-file testing
rules for contributors.

Signed-off-by: Developer Name <developer@example.com>
Assisted-by: <Model name> (via <Tool>)
```

### Breaking change

```text
feat(cli)!: remove deprecated --namespace flag

Remove the deprecated short-form --namespace flag from all
commands. Use -n instead. Deprecated since v0.30.

BREAKING CHANGE: Removed --namespace long flag from all
commands. Use -n or --ns instead.

Signed-off-by: Developer Name <developer@example.com>
Assisted-by: <Model name> (via <Tool>)
```

## Validation Rules

Every commit message must pass these checks:

1. **Subject line format**: Must match `type(scope): description` (conventional commits)
2. **Subject line length**: Target 50 chars, hard limit 72 chars
3. **No trailing punctuation**: Subject must not end with `.` `!` `?` `,` `:` `;` (exception: `!` for breaking changes like `feat!:`)
4. **No trailing whitespace**: On any line
5. **Blank line after subject**: Required before body text
6. **Body line length**: Wrap at 72 characters per line
7. **Valid commit type**: Must be one of: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `build`, `ci`, `perf`, `revert`
8. **Signed-off-by trailer**: Required — `Signed-off-by: Name <email>`
9. **Assisted-by trailer**: Required when AI assists — `Assisted-by: <Model name>`
10. **Trailer spacing**: Blank line before trailers, no blank lines between them, no trailing blank lines

## Format standards

Follow [Tekton commit message standards](https://github.com/tektoncd/community/blob/master/standards.md#commit-messages):

- Conventional commit format (`type(scope): description`)
- Subject line: target 50 characters, hard limit 72
- Body lines wrapped at 72 characters
- Required `Signed-off-by` trailer (DCO)
- No trailing punctuation on the subject

## Auto-Detection Summary

When generating commit messages:

1. Run `git status` (without -uall flag)
2. Run `git diff` for staged and unstaged changes
3. Identify primary component from staged file paths
4. If scope unclear, ask user
5. If user mentions a GitHub issue number, add `Fixes #NNN` to body
6. Analyze staged files to determine commit type
7. Generate appropriate scope and description
8. Detect author info from environment variables or git config
9. Ensure subject line is ≤50 characters (max 72)
10. Wrap body text at 72 characters per line
11. Add required trailers (Signed-off-by and Assisted-by)
12. Format according to conventional commits standard
13. **Display message and ask for user confirmation**
14. Only commit after receiving confirmation

## Additional Resources

For detailed information:

- **`references/commit-types.md`** - Complete commit type reference with descriptions
- **`references/trailer-detection.md`** - Author detection logic and priority order