This skill should be used when the user asks to "review this commit message", "validate my commit", "improve this commit message", "explain conventional commits", "teach me commit message best practices", "write a commit", or requests guidance on git commit formatting. Provides strict Conventional Commits formatting with Angular convention to produce concise, informative commit messages following industry best practices.
From git-lovelynpx claudepluginhub aaronbassett/agent-foundry --plugin git-lovelyThis skill uses the workspace's default tool permissions.
examples/good-bad-commits.mdreferences/breaking-changes.mdreferences/conventional-commits-spec.mdreferences/scopes.mdreferences/writing-guide.mdDispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Executes pre-written implementation plans: critically reviews, follows bite-sized steps exactly, runs verifications, tracks progress with checkpoints, uses git worktrees, stops on blockers.
Guides idea refinement into designs: explores context, asks questions one-by-one, proposes approaches, presents sections for approval, writes/review specs before coding.
Guide the creation of concise, conventional commit messages that follow the Conventional Commits specification with Angular convention. Enforce strict formatting rules to prevent verbose, unclear commit messages. Focus on communicating what changed and why it changed, not stylistic flourishes.
Follow this exact format:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Type (required): Describes the category of change Scope (optional): Specifies what part of the codebase changed Description (required): Brief summary of the change Body (optional): Detailed explanation of what and why Footer (optional): Breaking changes, issue references, git trailers
Use exactly these types, no others:
feat - New feature for the userfix - Bug fix for the userdocs - Documentation only changesstyle - Code style changes (formatting, missing semicolons, etc.) that don't affect code meaningrefactor - Code change that neither fixes a bug nor adds a featureperf - Code change that improves performancetest - Adding or correcting testsbuild - Changes to build system or external dependenciesci - Changes to CI configuration files and scriptschore - Other changes that don't modify src or test filesCharacter limit: Maximum 70 characters including type and scope
Mood: Use imperative mood (command form: "add", "fix", "update", not "added", "fixes", "updating")
Capitalization: Do not capitalize the first letter of description
Punctuation: Do not end with a period
Format: type(scope): description or type: description
Examples:
feat(auth): add JWT token refresh mechanism
fix: prevent race condition in event handlers
docs: update API documentation for v2 endpoints
Anti-patterns:
feat: Added new feature. ❌ Capitalized, ends with period
Fix bug ❌ Not lowercase type, missing colon
refactor: Refactored code ❌ Not imperative mood, capitalized
feat(Auth): adds feature ❌ Capitalized scope, present tense
Line wrapping: Wrap at 90 characters Maximum length: 700 characters total (excluding footers/git trailers) Capitalization: Do capitalize the first letter of sentences in body Blank line: Separate subject from body with one blank line Content: Explain what and why, not how Bullet points: Maximum 8 bullet points if using bullets Paragraph structure: Keep succinct, prefer bullets for lists
Purpose: Answer these questions:
Format: FOOTER-TOKEN: footer value or FOOTER-TOKEN #value
Common footers:
BREAKING CHANGE: description - For breaking changesRefs: #123 - Reference to issueCo-Authored-By: Name <email> - Co-authorsNot counted toward 700 character body limit
Use scopes sparingly and consistently:
Consistency: Once established, always use the same scope name
feat(auth):, fix(auth):, refactor(auth):feat(auth):, fix(authorization):, refactor(auths):Lowercase only: Scopes must be lowercase
feat(api):feat(API):Concept-focused: Use the concept/component name, not filenames
fix(auth):, feat(api):, refactor(ui):fix(auth-service.ts):, feat(api/v2/handlers):, refactor(components/button):Multiple scopes: Comma-separated if change affects multiple areas
refactor(core,api): consolidate error handlingOmit when unclear: If scope is unclear or change is global, omit it
chore: update dependenciesFor detailed scope patterns, see references/scopes.md
Always include breaking change notation unless explicitly told "this is prerelease, don't worry about breaking changes"
Format: Both are required
! after type/scope: feat!: or feat(api)!:BREAKING CHANGE: footer with descriptionExample:
feat(api)!: change authentication response format
Modify login endpoint to return token object instead of plain string.
This provides additional metadata (expiry, refresh token) for clients.
BREAKING CHANGE: AuthService.login() now returns {token: string,
expiresIn: number} instead of just the token string. Update all
clients to access response.token instead of using response directly.
For complete breaking change patterns, see references/breaking-changes.md
Never include:
./specs/**/*.md, SPECS-123, [#DOC-456]Refs: #123, Fixes #456Reasoning: Local spec IDs are internal context that won't be meaningful to future readers or other contributors
Don't assume the reader understands the context. They may not have access to the story or ticket.
Bad:
fix: add margin
Good:
fix: add margin to nav items to prevent overlapping the logo
Navigation items were rendering too close to the logo on smaller
screens, causing visual overlap. Add 16px margin to create proper
spacing.
What seems obvious now won't be obvious in 6 months. Explain the reasoning.
Bad:
refactor: update user component
Good:
refactor: extract user validation logic to separate service
Move validation logic from UserComponent to UserValidationService
to enable reuse across registration and profile edit flows. This
eliminates duplicated validation code and ensures consistent rules.
State the problem being solved, not just what was done.
Bad:
perf: add caching
Good:
perf: cache user preferences to reduce database queries
User preferences were being fetched on every page load, causing
unnecessary database queries. Implement in-memory cache with 5-minute
TTL to reduce database load by ~80%.
Headline (subject): Sum up what happened and what is important Details (body): Provide further details in organized fashion
Think: "If I'm debugging this in production at 2am, what would I need to know?"
If it's difficult to summarize the commit within 700 characters or 8 bullet points, the commit likely includes several logical changes and should be split.
Use git add -p to stage changes interactively and create multiple focused commits instead of one large commit.
feat(auth): add JWT token refresh mechanism
Implement automatic token refresh when tokens expire within 5 minutes
of API calls. This prevents users from being logged out during active
sessions. Refresh happens transparently in the background.
fix: prevent race condition in event handlers
Add mutex lock around event processing to ensure handlers execute
sequentially. Rapid events could trigger handlers out of order,
causing inconsistent state updates.
Fixes #234
docs: update authentication flow documentation
Add sequence diagrams for OAuth flow and clarify token refresh
behavior. Previous documentation was missing the refresh token
exchange step.
perf(api): optimize database queries for user dashboard
Replace N+1 query pattern with batch loading using dataloader.
Dashboard load time reduced from 2.3s to 0.4s for users with
many projects.
feat: Added new feature to the app.
Problems: Capitalized, ends with period, vague description, past tense
Fix bug in auth
Problems: Not lowercase type, missing colon, vague
refactor(Auth): Refactoring the authentication system to make it better and more secure and maintainable.
Problems: Capitalized scope, not imperative, capitalized description, too verbose without specifics
update user validation per SPECS-234
Problems: Missing type, references local spec file (prohibited)
For comprehensive guidance, consult:
references/scopes.md - Detailed scope usage patterns and consistency guidelinesreferences/breaking-changes.md - Complete breaking change notation and pre-release handlingreferences/conventional-commits-spec.md - Full Conventional Commits specificationreferences/writing-guide.md - Extended philosophy on writing meaningful commit messagesSee examples/good-bad-commits.md for real-world examples comparing good and bad commit messages across different scenarios.
When creating commits:
git diff --stagedApply these rules strictly to every commit message without exception.