# conventional-gitmoji

A portable [Agent Skills](https://agentskills.io/) 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

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

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

### OpenAI Codex

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

```bash
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](https://github.com/earendil-works/pi-coding-agent) —
install with the pi CLI:

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

```bash
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](https://www.conventionalcommits.org/en/v1.0.0/)
- [Gitmoji](https://github.com/carloscuesta/gitmoji)
- [Agent Skills spec](https://agentskills.io/specification)