Preface¶

Using AI to assist with coding has become quite common, but commit messages are often still a mess: messages like update, fix stuff, and WIP are nearly impossible to search through during team collaboration, and automated Changelog generators cannot parse them either. The Conventional Commits specification turns commits into structured text that is “readable by humans and parsable by machines” using type prefixes, optional scopes, and body text. The problem is, getting AI agents to consistently follow this set of rules every time is not easy.

The writing-commit-messages Skill is designed specifically for this task: it writes the Conventional Commits format, type list, good and bad examples, and breaking change syntax into a SKILL.md file, so AI agents follow the same set of instructions when writing commit messages. This article introduces what it is, its core rules, how to install and enable it, and typical usage scenarios.

What It Is¶

The writing-commit-messages Skill comes from the GitHub repository spencerpauly/awesome-cursor-skills, located in the directory resources/writing-commit-messages/. The repository categorizes it under the Workflow category, and its official one-sentence description is: Write Conventional Commit messages with type prefixes, scopes, and meaningful descriptions.

The Skill itself is a reusable SKILL.md instruction file. Following the universal format for Agent Skills, it can be used in AI programming tools that support this standard, such as Cursor, Claude Code, and Codex CLI. The frontmatter declares:
- name: writing-commit-messages
- description: Write clear, conventional commit messages with proper type prefixes, scopes, and body content.
- user-invocable: true (supports active user invocation)

Its core problem it solves is very specific: constraining AI agents to generate clear, consistent, machine-parsable commit messages, rather than just saying “made some changes”.

Core Features and Specifications¶

The Skill requires commit messages to be useful to both humans and machines, and adopts the common Conventional Commits structure:

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

<optional body>

<optional footer>

Subject Line Rules¶

• Keep the subject under 50 characters
• Use imperative mood: write add feature, not added feature or adding feature
• Do not capitalize the first letter after the type prefix
• Do not add a period at the end of the subject line

Type¶

This aligns with the conventions of Conventional Commits 1.0.0: feat / fix correspond to SemVer’s MINOR / PATCH versions; a BREAKING CHANGE footer or a ! after the type corresponds to a MAJOR version bump.

Scope (Optional)¶

Use parentheses to mark the affected code area, for example:
- feat(auth): add OAuth2 login flow
- fix(api): handle null response from payments endpoint
- refactor(db): extract query builder into module

Body and Footer¶

Write the body only when needed, focusing on explaining why the change was made, rather than repeating what was changed which is already visible in the diff. The footer can include breaking change descriptions, linked issues, co-authors, etc., for example:

BREAKING CHANGE: rename `getUserById` to `findUser`

Closes #456
Co-authored-by: Name <email>

Breaking Changes¶

If this commit introduces breaking changes, the Skill requires:
1. Add a ! after the type, for example: feat(api)!: change auth token format
2. Write BREAKING CHANGE: in the footer with migration instructions

When to Commit¶

The Skill also constrains commit granularity:
- One commit corresponds to one logical change
- Do not mix refactoring and feature development in the same commit
- Do not commit half-finished work (use git stash instead)
- You can commit frequently on feature branches, and squash commits as needed before merging

Installation and Enablement¶

Method 1: Manual Placement (Cursor)¶

According to the awesome-cursor-skills repository instructions: Copy the SKILL.md file to the project’s .cursor/skills/ directory, and the AI agent will automatically discover it. You can place it in the following structure:

.cursor/skills/writing-commit-messages/SKILL.md

You can also place it in the user-level directory ~/.cursor/skills/ for sharing across multiple projects. The official Cursor documentation also states that it will load skills from .agents/skills/, ~/.agents/skills/, and for compatibility with Claude / Codex, it will also read paths like .claude/skills/ and .codex/skills/.

Original file address:
https://github.com/spencerpauly/awesome-cursor-skills/blob/main/resources/writing-commit-messages/SKILL.md

Method 2: Install via skills CLI¶

The vercel-labs/skills tool provides npx skills to install specified Skills from GitHub repositories. For this Skill, you can choose based on your target AI agent:

Install for Cursor:

npx skills add spencerpauly/awesome-cursor-skills --skill writing-commit-messages --agent cursor

Install for Claude Code:

npx skills add spencerpauly/awesome-cursor-skills --skill writing-commit-messages --agent claude-code

Add -g if you need a global installation. After installation, you can search for and call the Skill name in the Cursor Agent chat (for example, /writing-commit-messages), or let the AI agent automatically select it in relevant contexts.

Typical Usage Examples¶

After enabling, you can ask the AI agent to write a commit message based on the current changes. The Skill provides the following positive and negative examples.

Recommended writing style:

feat(dashboard): add real-time notification bell
fix: resolve race condition in WebSocket reconnect
refactor(api): consolidate error handling middleware
test: add integration tests for payment webhook
chore: upgrade TypeScript to 5.4

Fix example with body text:

fix(checkout): prevent duplicate order submissions

The submit button was not disabled after the first click,
allowing users to create multiple orders. This caused
duplicate charges in Stripe.

Avoided writing styles:

fixed stuff
WIP
update
changes
asdf

You can trigger it in an actual chat like this, for example:

Please write a Conventional Commit message based on the current staged changes and execute the commit.

Or explicitly invoke the Skill:

/writing-commit-messages
Please write a commit message for this payment callback fix.

The AI agent should select the appropriate type / scope per the Skill, use imperative mood for the subject line, and add body text or BREAKING CHANGE footer as needed.

Applicable Scenarios and Notes¶

It is suitable for these situations:
- Your team has adopted or plans to adopt Conventional Commits, and wants AI agents to output consistent messages with manual specifications
- You need to automatically generate Changelogs from commit history, or use tools like semantic-release for version bumping
- In multi-person collaboration and code review, you want commit history to be searchable and categorizable
- Pair with other Workflow Skills in the same repository, such as creating-pr, to keep PR titles and commit styles consistent

When using it, note that:
- The Skill only constrains message format and commit habits, and will not review whether your diff is correct; you should still confirm the scope of changes yourself before committing
- The type list is subject to the one listed in this Skill; if your team has additional conventions (such as using build), you need to supplement them in the project rules or modify the Skill locally
- “One logical change per commit” depends on the AI agent correctly splitting the staged content; if your working directory has mixed changes, you should first batch git add them yourself before asking the AI agent to write the commit message
- The specification itself cannot replace code review; fewer bad commit messages do not mean fewer bad code

Summary¶

The writing-commit-messages Skill固化s the structure, types, scopes, body/footer, and breaking change syntax of Conventional Commits into executable instructions for AI agents, making it one of the most basic Skills suitable for daily coding workflows. The installation cost is low: just copy a SKILL.md file, or use npx skills add with the --skill writing-commit-messages parameter.

Official address: https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/writing-commit-messages

You can refer to the original specification at: https://www.conventionalcommits.org/en/v1.0.0/