# Gitmoji Skill

> 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.

- Skill: `retlehs/gitmoji-skill` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add retlehs/gitmoji-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/retlehs/gitmoji-skill/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: retlehs (https://skillmd.com/u/retlehs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/retlehs/gitmoji-skill

---


# 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:

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

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

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

Examples:

```text
🎉 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:

```bash
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:

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