SKILL.md

name	gitmoji-skill
description	Prefixes commit messages and PR titles with an appropriate Gitmoji. Activate when writing or amending commit messages, drafting PR titles, or choosing a Gitmoji for a change.

Gitmoji Commits and PRs

When making a commit, start the commit subject with one Gitmoji that describes the primary intent of the change.

When creating or updating a pull request, start the PR title with one Gitmoji that describes the primary intent of the PR.

Use one of these forms:

<gitmoji> <message>
<gitmoji> (<scope>): <message>

If the repository uses Conventional Commits, the Gitmoji stays first:

<gitmoji> <type>: <message>
<gitmoji> <type>(<scope>): <message>
<gitmoji> <type>!: <message>   # breaking change

Examples:

🎉 Begin project
📝 Add Gitmoji skill docs
♻️ (parser): simplify token handling
🐛 Fix login redirect loop
✅ Add webhook parser tests
✨ feat(search): add invoice filters
💥 feat!: drop Node 18 support

Choosing a Gitmoji

First, check the repository's existing convention. Run:

git log --oneline -20

Also skim CONTRIBUTING.md, .gitmessage, or commit-lint config if present. If the project already has a Gitmoji style (Unicode vs shortcode, position, scope format), follow it exactly.

Otherwise, choose the most specific official Gitmoji for the primary change:

Change	Gitmoji
New feature	✨
Bug fix	🐛
Critical hotfix	🚑️
Documentation	📝
Tests	✅
Refactor	♻️
Improve structure or formatting	🎨
Performance	⚡️
Remove code or files	🔥
Configuration	🔧
Development scripts	🔨
CI build system	👷
Fix CI build	💚
Upgrade dependencies	⬆️
Downgrade dependencies	⬇️
Add dependency	➕
Remove dependency	➖
Lint or compiler warnings	🚨
Security or privacy	🔒
Accessibility	♿️
Types	🏷️
Move or rename resources	🚚
Work in progress	🚧
Breaking change	💥

🎨 vs ♻️: use 🎨 for code style and structural changes that don't alter behavior (formatting, import sorting, file organization); use ♻️ for behavior-preserving rework that changes implementation (extracting functions, renaming, simplifying logic).

🐛 vs 🚑️: use 🐛 for ordinary bug fixes; use 🚑️ only for critical hotfixes shipped urgently to address production breakage.

If no entry above fits, read references/gitmojis.md (the full official list of 75 Gitmojis) and pick the closest match. If still nothing fits, fall back to ✨ for additive work, 🐛 for fixes, or ♻️ for refactors. Do not invent decorative emoji when an official Gitmoji applies.

Skip 💩, 🍻, and 🥚 — these appear in the official list but are not appropriate for agent-authored commits.

Format Rules

• Default to Unicode emoji in commit and PR titles. Use shortcodes (:sparkles:) only if the repository's existing commits use them.
• Keep the subject concise and imperative after the Gitmoji.
• Use exactly one leading Gitmoji.
• Place the Gitmoji on the subject line only. Do not add Gitmojis to the commit body or trailers (e.g., Co-Authored-By:, Signed-off-by:).
• For mixed changes, choose the dominant intent or split the work into separate commits.
• If a repository convention conflicts with this skill, follow the repository.

Amends, Fixups, and Reverts

• git commit --amend: keep the original Gitmoji unless the amend changes the intent (e.g., a typo-fix amend that turns into a feature addition).
• git commit --fixup and git commit --squash: do not add a Gitmoji; Git generates the fixup!/squash! subject and it will be squashed away.
• Reverts: use ⏪️ for explicit reverts. Let git revert generate its default Revert "…" subject, then prepend ⏪️ if you edit it.
• Merges: let git merge generate its default subject; do not add a Gitmoji to auto-generated merge commits.

Pull Requests

Use the same selection rules for PR titles. For a PR with many commits, choose the Gitmoji that best describes the final user-visible or maintainer-visible outcome.

Gitmoji applies to PR titles and commit subjects only — PR descriptions and commit bodies use the repository's normal template without Gitmojis.

Examples:

✨ Add saved report filters
🐛 Fix OAuth callback validation
📝 Document deployment environment variables