Writes every git commit message in Conventional Commits v1.0.0 format with an ASD-STE100 Simplified Technical English subject line. Use before running any `git commit`, `git commit --amend`, or `gh pr merge --squash`, and whenever the user asks to "commit", "commit the changes", "write a commit message", "amend the commit", or mentions commit conventions, commit format, or commit message style. Applies in any git repository, Nexa project or not.
Compose the commit message before you run git commit. Never run git commit -m
with a message that has not passed the Verification checklist at the end of this
skill.
Format
<type>(<scope>)<!>: <description>
<body>
<footer>
type — required, lowercase, from the table below
scope — optional, in parentheses, no spaces
! — optional, before the colon, marks a breaking change
description — required, one line, imperative, no final period
body — optional, blank line before it, explains why, not what
footer — optional, blank line before it, BREAKING CHANGE: <reason> or
Refs: #42, Closes: #42
Types
Type
Use for
feat
A new capability for the user
fix
A correction of incorrect behaviour
docs
Documentation only
refactor
A change that does not add a capability or correct behaviour
perf
A change that improves speed or resource use
test
Tests only
build
Build system or dependencies
ci
CI configuration or pipelines
chore
Other work that changes no source behaviour
revert
Reverts an earlier commit; the body gives its hash
feat and fix map to MINOR and PATCH. A ! or a BREAKING CHANGE: footer
maps to MAJOR, with any type.
Scope
Derive the scope in this order. Use the first one that applies:
A Nexa work item — the ID of the specification you implement:
UC-XXX, TT-XXX, BUG-XXX, CR-XXX. See
${CLAUDE_PLUGIN_ROOT}/shared/tracking/TRACKING.md for the type-to-ID
mapping and examples. This rule has priority over all the rules below.
A plugin, package, or workspace name in a monorepo — nextjs, core.
A module or feature area that the diff touches — auth, checkout.
No scope, if the change is repository-wide.
Do not invent a scope. Read the diff and the branch name, and use a scope that
is already in the git log history of the repository.
Simplified Technical English
Write the description and the body in ASD-STE100 Simplified Technical English.
These are the STE rules that apply to a commit message:
Use the imperative.add the retry limit, not added or adds.
Use the active voice.the parser rejects empty rows, not empty rows are rejected.
Use the simple present tense. Do not use future, perfect, or progressive
tenses.
Give one instruction per sentence. Keep sentences to 20 words or fewer.
Use one word for one meaning. Keep the same word for the same thing in the
whole message. Do not use synonyms for variety.
Use the approved word for each action — remove, not get rid of; start,
not kick off; change, not tweak.
Do not use the -ing form as a verb.add caching is acceptable when
"caching" is the name of the thing; adding a cache is not.
Do not omit articles to shorten the line.fix the discount calculation is
correct. Drop an article only when the line stays unambiguous without it.
Use three nouns or fewer in a noun cluster. Break up
order total discount code validation.
Do not use slang, jargon, idioms, or humour.
Spell out an abbreviation unless it is a project identifier (UC-003), a
standard technical term (API, HTTP, SQL), or an identifier from the code.
Do not use a pronoun with an unclear antecedent. Name the thing.
Code identifiers, file paths, and commands keep their exact spelling. STE applies
to the prose around them.
DO NOT
The Verification checklist covers the format rules. These are the rules it cannot check:
Do not add a co-author, tool credit, or advertisement footer unless the user
asks for one.
Do not amend or force-push a commit that is already on a shared branch without
the user's confirmation.
Do not run git commit when the user asked only for a review or a diff.
Process
Run git status and git diff --staged. If nothing is staged, run
git diff and stage the files that belong to this one logical change.
Read the diff and name the effect on behaviour in one sentence.
Choose the type from the table. Correct behaviour → fix. New capability →
feat. No behaviour change → refactor, chore, docs, test, build, or ci.
Derive the scope with the priority list above.
Write the description in STE. Rewrite it once to remove every word that carries
no information.
Add a body only when the reason for the change is not clear from the
description. Explain why, not what.
Add ! and a BREAKING CHANGE: footer when a consumer must change their code.
Run the Verification checklist.
Commit with a heredoc so the message keeps its line breaks:
git commit -F - <<'EOF'
fix(BUG-003): apply the discount code to the order total
The total used the list price because the discount ran after the sum.
EOF
Examples
feat(UC-003): add the place order page and its API route
refactor(auth)!: replace the session cookie with a bearer token
BREAKING CHANGE: clients must send the Authorization header. The session
cookie is no longer read.
Rejected subjects and their corrections:
Rejected
Reason
Corrected
Fixed bug in checkout.
past tense, capital, period
fix(checkout): reject an empty cart
feat: adding user stuff
-ing form, slang, no effect stated
feat(users): add the user invite form
chore: updates
no information
chore(deps): raise vitest to 3.2.0
fix: the thing that broke the order total discount code check
3+ noun cluster, unclear pronoun
fix(orders): validate the discount code before the total
Verification
The message is ready only when every line below is true:
The first line matches <type>(<scope>)!?: <description> with a lowercase type
The type is in the table and matches the diff
The scope follows the priority list, or there is no scope
The description is imperative, lowercase, has no final period, and is 72
characters or fewer
The description states the effect on behaviour, not the list of edited files
Every sentence is 20 words or fewer, active voice, simple present
No slang, no idiom, no -ing verb, no unexplained abbreviation, no
unclear pronoun
A blank line separates the description, the body, and the footer
A breaking change has both ! and a BREAKING CHANGE: footer
The commit holds one logical change
If a box fails, rewrite the message. Do not commit a message that fails a box.
1---2name: conventional-commit3description: Writes every git commit message in Conventional Commits v1.0.0 format with an ASD-STE100 Simplified Technical English subject line. Use before running any `git commit`, `git commit --amend`, or `gh pr merge --squash`, and whenever the user asks to "commit", "commit the changes", "write a commit message", "amend the commit", or mentions commit conventions, commit format, or commit message style. Applies in any git repository, Nexa project or not.4---56# Conventional Commit78## Instructions910Compose the commit message before you run `git commit`. Never run `git commit -m`11with a message that has not passed the Verification checklist at the end of this12skill.1314## Format1516```17<type>(<scope>)<!>: <description>1819<body>2021<footer>22```2324- `type` — required, lowercase, from the table below25- `scope` — optional, in parentheses, no spaces26- `!` — optional, before the colon, marks a breaking change27- `description` — required, one line, imperative, no final period28- `body` — optional, blank line before it, explains **why**, not what29- `footer` — optional, blank line before it, `BREAKING CHANGE: <reason>` or30 `Refs: #42`, `Closes: #42`3132## Types3334| Type | Use for |35|---|---|36| `feat` | A new capability for the user |37| `fix` | A correction of incorrect behaviour |38| `docs` | Documentation only |39| `refactor` | A change that does not add a capability or correct behaviour |40| `perf` | A change that improves speed or resource use |41| `test` | Tests only |42| `build` | Build system or dependencies |43| `ci` | CI configuration or pipelines |44| `chore` | Other work that changes no source behaviour |45| `revert` | Reverts an earlier commit; the body gives its hash |4647`feat` and `fix` map to MINOR and PATCH. A `!` or a `BREAKING CHANGE:` footer48maps to MAJOR, with any type.4950## Scope5152Derive the scope in this order. Use the first one that applies:53541. **A Nexa work item** — the ID of the specification you implement:55 `UC-XXX`, `TT-XXX`, `BUG-XXX`, `CR-XXX`. See56 `${CLAUDE_PLUGIN_ROOT}/shared/tracking/TRACKING.md` for the type-to-ID57 mapping and examples. This rule has priority over all the rules below.582. **A plugin, package, or workspace name** in a monorepo — `nextjs`, `core`.593. **A module or feature area** that the diff touches — `auth`, `checkout`.604. **No scope**, if the change is repository-wide.6162Do not invent a scope. Read the diff and the branch name, and use a scope that63is already in the `git log` history of the repository.6465## Simplified Technical English6667Write the description and the body in ASD-STE100 Simplified Technical English.68These are the STE rules that apply to a commit message:6970- **Use the imperative.** `add the retry limit`, not `added` or `adds`.71- **Use the active voice.** `the parser rejects empty rows`, not `empty rows are72 rejected`.73- **Use the simple present tense.** Do not use future, perfect, or progressive74 tenses.75- **Give one instruction per sentence.** Keep sentences to 20 words or fewer.76- **Use one word for one meaning.** Keep the same word for the same thing in the77 whole message. Do not use synonyms for variety.78- **Use the approved word for each action** — `remove`, not `get rid of`; `start`,79 not `kick off`; `change`, not `tweak`.80- **Do not use the `-ing` form as a verb.** `add caching` is acceptable when81 "caching" is the name of the thing; `adding a cache` is not.82- **Do not omit articles to shorten the line.** `fix the discount calculation` is83 correct. Drop an article only when the line stays unambiguous without it.84- **Use three nouns or fewer in a noun cluster.** Break up85 `order total discount code validation`.86- **Do not use slang, jargon, idioms, or humour.**87- **Spell out an abbreviation** unless it is a project identifier (`UC-003`), a88 standard technical term (`API`, `HTTP`, `SQL`), or an identifier from the code.89- **Do not use a pronoun with an unclear antecedent.** Name the thing.9091Code identifiers, file paths, and commands keep their exact spelling. STE applies92to the prose around them.9394## DO NOT9596The Verification checklist covers the format rules. These are the rules it cannot check:9798- Do not add a co-author, tool credit, or advertisement footer unless the user99 asks for one.100- Do not amend or force-push a commit that is already on a shared branch without101 the user's confirmation.102- Do not run `git commit` when the user asked only for a review or a diff.103104## Process1051061. Run `git status` and `git diff --staged`. If nothing is staged, run107 `git diff` and stage the files that belong to this one logical change.1082. Read the diff and name the effect on behaviour in one sentence.1093. Choose the `type` from the table. Correct behaviour → `fix`. New capability →110 `feat`. No behaviour change → `refactor`, `chore`, `docs`, `test`, `build`, or `ci`.1114. Derive the `scope` with the priority list above.1125. Write the description in STE. Rewrite it once to remove every word that carries113 no information.1146. Add a body only when the reason for the change is not clear from the115 description. Explain why, not what.1167. Add `!` and a `BREAKING CHANGE:` footer when a consumer must change their code.1178. Run the Verification checklist.1189. Commit with a heredoc so the message keeps its line breaks:119120 ```bash121 git commit -F - <<'EOF'122 fix(BUG-003): apply the discount code to the order total123124 The total used the list price because the discount ran after the sum.125 EOF126 ```127128## Examples129130```131feat(UC-003): add the place order page and its API route132```133134```135refactor(auth)!: replace the session cookie with a bearer token136137BREAKING CHANGE: clients must send the Authorization header. The session138cookie is no longer read.139```140141Rejected subjects and their corrections:142143| Rejected | Reason | Corrected |144|---|---|---|145| `Fixed bug in checkout.` | past tense, capital, period | `fix(checkout): reject an empty cart` |146| `feat: adding user stuff` | `-ing` form, slang, no effect stated | `feat(users): add the user invite form` |147| `chore: updates` | no information | `chore(deps): raise vitest to 3.2.0` |148| `fix: the thing that broke the order total discount code check` | 3+ noun cluster, unclear pronoun | `fix(orders): validate the discount code before the total` |149150## Verification151152The message is ready only when every line below is true:153154- [ ] The first line matches `<type>(<scope>)!?: <description>` with a lowercase type155- [ ] The type is in the table and matches the diff156- [ ] The scope follows the priority list, or there is no scope157- [ ] The description is imperative, lowercase, has no final period, and is 72158 characters or fewer159- [ ] The description states the effect on behaviour, not the list of edited files160- [ ] Every sentence is 20 words or fewer, active voice, simple present161- [ ] No slang, no idiom, no `-ing` verb, no unexplained abbreviation, no162 unclear pronoun163- [ ] A blank line separates the description, the body, and the footer164- [ ] A breaking change has both `!` and a `BREAKING CHANGE:` footer165- [ ] The commit holds one logical change166167If a box fails, rewrite the message. Do not commit a message that fails a box.
Run npx skillmds@latest add nexadevapp/conventional-commit in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Writes every git commit message in Conventional Commits v1.0.0 format with an ASD-STE100 Simplified Technical English subject line. Use before running any `git commit`, `git commit --amend`, or `gh pr merge --squash`, and whenever the user asks to "commit", "commit the changes", "write a commit message", "amend the commit", or mentions commit conventions, commit format, or commit message style. Applies in any git repository, Nexa project or not. It is listed under Coding & Dev Tools on SkillMD.
This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
nexadevapp (@nexadevapp) published this skill. Their other Agent Skills are listed on their SkillMD profile.
nexadevapp