# Write Conventional Commit > Create Git commit messages that conform to Conventional Commits 1.0.0, including type/scope/description format, optional body, trailer-style footers, and explicit BREAKING CHANGE signaling. Use when users ask to draft commit messages, commit current changes, rewrite a commit message into conventional format, or enforce conventional commit standards in a repo. - Skill: `ragnarok22/write-conventional-commit` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add ragnarok22/write-conventional-commit` - Raw SKILL.md: https://api.skillmd.com/api/skills/ragnarok22/write-conventional-commit/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: ragnarok22 (https://skillmd.com/u/ragnarok22) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/ragnarok22/write-conventional-commit --- # Write Conventional Commit Generate and apply Conventional Commits that follow the 1.0.0 specification. ## Workflow ### Step 1: Inspect commit scope Run from repository root: ```bash git status --short git diff --staged --name-only git diff --name-only ``` Use staged changes when available. If nothing is staged and the user asked to commit now, stage intentionally relevant files first and state what was staged. ### Step 2: Classify intent into commit type Pick the best type from change intent, not from file extension. Common types: - `feat`: add a user-facing feature - `fix`: fix a bug - `refactor`: code change without new feature or bug fix - `perf`: improve performance - `docs`: documentation only - `test`: add/update tests - `build`: build/dependency tooling - `ci`: CI/CD configuration - `chore`: maintenance that does not fit above - `revert`: revert a previous commit If uncertain between `feat` and `fix`, prefer: - `fix` when correcting broken behavior - `feat` when adding new behavior ### Step 3: Choose optional scope Scope is optional and should be short and stable. Prefer one of: - top-level package/app (`api`, `billing`, `auth`) - subsystem (`migrations`, `deps`, `release`) - user-visible surface (`checkout`, `search`) Avoid broad scopes like `misc`. ### Step 4: Detect breaking changes Mark breaking changes when diff indicates incompatible API/contract behavior. Signals include: - removed/renamed public endpoints, fields, events, CLI flags - required inputs changed incompatibly - output schema changed incompatibly When breaking: 1. Add `!` after type or type+scope (`feat!:` or `feat(api)!:`) 2. Add footer: `BREAKING CHANGE: ` Use both when possible for clarity. ### Step 5: Compose message in spec format Use this structure exactly: ```text [optional scope][!]: [optional body] [optional footer(s)] ``` Formatting rules: - Header type must be lowercase noun. - Put a colon and single space after header prefix. - Keep description concise and specific. - Put one blank line between header and body. - Put one blank line between body and footers. - Footer tokens follow git trailer style (`Token: value`), except references may use `Token #value`. - Use `BREAKING CHANGE:` as the canonical breaking footer token. ### Step 6: Create commit (when requested) If user wants the commit executed, run non-interactively: ```bash git commit -m "

" -m "" -m "" -m "" ``` Only include `-m` blocks that are needed. For multiline body/footer with precise formatting, use: ```bash git commit -F /tmp/commit-msg.txt ``` Then report: - final commit header - commit hash - whether breaking change was marked ## Quality checks Before finalizing, verify: - Header matches `[scope][!]: description` - Type reflects intent correctly - Scope is helpful or omitted - Breaking changes are explicitly marked when applicable - Body explains why when context is not obvious - Footers are valid trailers and references are accurate ## Output behavior When user asks only for message suggestions, provide 1 recommended message and up to 2 alternatives. When user asks to commit directly, proceed with staging/commit commands and then return commit result. ## Reference Read [references/conventional-commits-1.0.0.md](references/conventional-commits-1.0.0.md) for the normative checklist and examples.