conventional-gitmoji

A portable Agent Skills skill for any coding agent (Claude Code, OpenAI Codex, OpenCode, pi, and more). When you ask the agent to commit your work, it stages the relevant files and commits with a message that follows Conventional Commits, uses one of the extended (Angular) types, and is prefixed with a gitmoji:

✨ feat(auth): add token refresh endpoint
🐛 fix(parser): handle empty input instead of crashing
♻️ refactor(utils): extract slugify into shared helper

The skill is a single SKILL.md with YAML frontmatter (name, description), the standard every agent below reads natively — same folder, copy it anywhere.

What it enforces

• The 9 extended Conventional Commit types: feat, fix, docs, style, refactor, perf, test, build, ci.
• One gitmoji per type (✨ 🐛 📝 🎨 ♻️ ⚡️ ✅ 👷 💚), 💥 for breaking changes.
• Message shape gitmoji type(scope): subject with optional body/footers.
• It runs the commit; it doesn't just print a message.

Install

Create a directory named conventional-gitmoji and place SKILL.md inside it, then point that directory at one of the locations below.

Claude Code

mkdir -p ~/.claude/skills/conventional-gitmoji
cp SKILL.md ~/.claude/skills/conventional-gitmoji/

(Project-scoped alternative: .claude/skills/conventional-gitmoji/.)

OpenAI Codex

mkdir -p "$CODEX_HOME/skills/conventional-gitmoji"
cp SKILL.md "$CODEX_HOME/skills/conventional-gitmoji/"

($CODEX_HOME defaults to ~/.codex. Project-scoped alternative: .codex/skills/conventional-gitmoji/.)

OpenCode

mkdir -p ~/.config/opencode/skills/conventional-gitmoji
cp SKILL.md ~/.config/opencode/skills/conventional-gitmoji/

(Project-scoped alternative: .opencode/skills/conventional-gitmoji/. OpenCode also auto-discovers ~/.claude/skills/ and ~/.agents/skills/.)

pi

This repo is a pi package — install with the pi CLI:

pi install /path/to/conventional-gitmoji                       # local path
pi install git:github.com/mrizzben/conventional-gitmoji-skill  # from GitHub
pi install npm:@mrizzben/conventional-gitmoji                  # once published to npm

Or copy the skill manually: ~/.agents/skills/conventional-gitmoji/ (also works at ~/.pi/agent/skills/, or project-scoped .pi/skills/ / .agents/skills/).

Skills CLI (skills.sh)

If the repo supports it, install with the open ecosystem CLI:

npx skills add mrizzben/conventional-gitmoji-skill

Use

Just commit normally:

agent: commit this
agent: commit my staged changes
agent: write a commit for the parser fix and commit it

The skill auto-loads from its description. To force-load it per agent, use the harness's mechanism: /conventional-gitmoji (Claude Code / pi), /skill:conventional-gitmoji (pi), or skill tool (OpenCode).

Customizing

If your team wants different emoji or extra types, edit the Types → gitmoji table in SKILL.md. The rest of the workflow is unchanged.

References

• Conventional Commits
• Gitmoji
• Agent Skills spec