commit
npx machina-cli add skill bcastelino/agent-skills-kit/commit --openclawSentry Commit Messages
Follow these conventions when creating commits for Sentry projects.
When to Use This Skill
Use this skill when:
- Committing code changes
- Writing commit messages
- Formatting git history
- Following Sentry commit conventions
- Referencing Sentry issues in commits
Prerequisites
Before committing, ensure you're working on a feature branch, not the main branch.
# Check current branch
git branch --show-current
If you're on main or master, create a new branch first:
# Create and switch to a new branch
git checkout -b <type>/<short-description>
Branch naming should follow the pattern: <type>/<short-description> where type matches the commit type (e.g., feat/add-user-auth, fix/null-pointer-error, ref/extract-validation).
Format
<type>(<scope>): <subject>
<body>
<footer>
The header is required. Scope is optional. All lines must stay under 100 characters.
Commit Types
| Type | Purpose |
|---|---|
feat | New feature |
fix | Bug fix |
ref | Refactoring (no behavior change) |
perf | Performance improvement |
docs | Documentation only |
test | Test additions or corrections |
build | Build system or dependencies |
ci | CI configuration |
chore | Maintenance tasks |
style | Code formatting (no logic change) |
meta | Repository metadata |
license | License changes |
Subject Line Rules
- Use imperative, present tense: "Add feature" not "Added feature"
- Capitalize the first letter
- No period at the end
- Maximum 70 characters
Body Guidelines
- Explain what and why, not how
- Use imperative mood and present tense
- Include motivation for the change
- Contrast with previous behavior when relevant
Footer: Issue References
Reference issues in the footer using these patterns:
Fixes GH-1234
Fixes #1234
Fixes SENTRY-1234
Refs LINEAR-ABC-123
Fixescloses the issue when mergedRefslinks without closing
AI-Generated Changes
When changes were primarily generated by a coding agent (like Claude Code), include the Co-Authored-By attribution in the commit footer:
Co-Authored-By: Claude <noreply@anthropic.com>
This is the only indicator of AI involvement that should appear in commits. Do not add phrases like "Generated by AI", "Written with Claude", or similar markers in the subject, body, or anywhere else in the commit message.
Examples
Simple fix
fix(api): Handle null response in user endpoint
The user API could return null for deleted accounts, causing a crash
in the dashboard. Add null check before accessing user properties.
Fixes SENTRY-5678
Co-Authored-By: Claude <noreply@anthropic.com>
Feature with scope
feat(alerts): Add Slack thread replies for alert updates
When an alert is updated or resolved, post a reply to the original
Slack thread instead of creating a new message. This keeps related
notifications grouped together.
Refs GH-1234
Refactor
ref: Extract common validation logic to shared module
Move duplicate validation code from three endpoints into a shared
validator class. No behavior change.
Breaking change
feat(api)!: Remove deprecated v1 endpoints
Remove all v1 API endpoints that were deprecated in version 23.1.
Clients should migrate to v2 endpoints.
BREAKING CHANGE: v1 endpoints no longer available
Fixes SENTRY-9999
Revert Format
revert: feat(api): Add new endpoint
This reverts commit abc123def456.
Reason: Caused performance regression in production.
Principles
- Each commit should be a single, stable change
- Commits should be independently reviewable
- The repository should be in a working state after each commit
References
Source
git clone https://github.com/bcastelino/agent-skills-kit/blob/main/skills/commit/SKILL.mdView on GitHub Overview
This skill helps you craft commits that follow Conventional Commits with Sentry-specific references. It covers header formatting, body rationale, and footer issue references, plus guidance for AI-generated changes attribution. It also enforces branch naming and best practices to keep history clean and traceable.
How This Skill Works
You create commits using a header in the form <type>(<scope>): <subject>, followed by an optional body and footer. The subject must be imperative and <= 70 characters, with all lines under 100 characters. The footer references issues using patterns like Fixes or Refs and, if the commit was AI-generated, includes a Co-Authored-By line in the footer to attribute authorship.
When to Use It
- Committing code changes on a feature branch following the repository conventions
- Writing a commit message that references Sentry issues in the footer (Fixes/Refs)
- Formatting git history to keep commits independent and readable
- Handling breaking changes with explicit notes in the header/body/footer
- Creating a revert or updating history after an accidental change
Quick Start
- Step 1: Start on a feature branch: git checkout -b <type>/<short-description>
- Step 2: Write the header: <type>(<scope>): <subject> where subject is concise (<= 70 chars)
- Step 3: Add a body that explains what and why, then add a footer with issue references and Co-Authored-By if applicable
Best Practices
- Use imperative mood and present tense in the subject
- Keep the subject line under 70 characters and the header properly formatted
- Explain what and why in the body, not how the change was implemented
- Reference related issues in the footer using patterns like Fixes SENTRY-1234 or Refs GH-1234
- If AI-generated changes were involved, add Co-Authored-By in the footer and avoid AI markers in the body or subject
Example Use Cases
- fix(api): Handle null response in user endpoint (Fixes SENTRY-5678; Co-Authored-By: Claude <noreply@anthropic.com>)
- feat(alerts): Add Slack thread replies for alert updates (Refs GH-1234)
- ref: Extract common validation logic to shared module (No behavior change)
- feat(api)!: Remove deprecated v1 endpoints (BREAKING CHANGE; Fixes SENTRY-9999)
- revert: feat(api): Add new endpoint (This reverts commit abc123; Reason: performance regression in prod)
