---
name: bilal140202/commit
source: https://app.decimal.ai/s/bilal140202-commit@1/SKILL.md
source_sha256: d49f2b5016d1
---

# Commit

Follow the repo's existing convention, create the commit, verify, and push when requested.
Use the reference docs for detailed rules.

## Workflow

1. Identify the convention
   - Read agent guidance first: `AGENTS.md`, `CLAUDE.md`, etc.
   - Check repo guidance or templates if present: `CONTRIBUTING.md`, `README.md`, commit templates, etc.
   - Scan history: `git log -n 50 --pretty=%s`
   - Choose exactly one: Conventional Commits, Gitmoji, or Custom.
   - If ambiguous, pause and ask using the user input guidance below.
   - Never invent new commit types or emoji codes.

2. Pull if requested
   - If `--pull` is set, run `git pull` before reviewing changes.
   - If conflicts occur, try to resolve them. If you cannot, pause and ask using the user input guidance below.

3. Review changes
   - `git status -sb`
   - `git diff --stat`
   - `git diff` (or `git diff --staged`)
   - Split unrelated changes into separate commits.

4. Stage intentionally
   - Prefer `git add -p` or `git add <files>`
   - Do not stage secrets or large generated artifacts unless explicitly requested.

5. Run verify steps
   - If the repo has tests, lint, or format checks, run them before committing.
   - Only proceed if they pass, unless the user requests `--no-verify`.
   - If checks fail, try to resolve them. If you cannot, pause and ask using the user input guidance below.

6. Compose the message
   - If a convention is identified, you MUST open the matching reference and follow its rules before composing the message.
   - Conventional Commits: follow `references/conventional-commits.md`.
   - Gitmoji: follow `references/gitmoji.md`.
   - Custom template: follow the exact pattern from history or the template file.
   - Use a body and trailers when needed (blank line before body, wrap at 72 chars).

7. Commit, inspect, and push
   - ALWAYS run the commit through the guard script (do not use `git commit` directly):
     - Resolve `{baseDir}` (the installed skill root) before running:
       - Check project-scoped installs first: `./.claude/skills/commit`, `./.codex/skills/commit`, `./.opencode/skills/commit`
       - Then check user-scoped installs: `~/.claude/skills/commit`, `~/.codex/skills/commit`, `~/.opencode/skills/commit`
     - Use `{baseDir}/scripts/commit-guard.py`:
       - `python {baseDir}/scripts/commit-guard.py --convention <conventional|gitmoji|custom> --message "subject"`
       - `python {baseDir}/scripts/commit-guard.py --convention <conventional|gitmoji|custom> --file <path>`
     - If `{baseDir}` cannot be found, pause and ask the user for the exact skill install path.
   - `git log -1 --format="%h %s"`
   - `git show --stat`
   - If `--push` is set, push to the current branch after commit.
   - If push fails, pause and ask using the user input guidance below.

## Commit guard script

Use the guard script to validate and create commits.
Run `python {baseDir}/scripts/commit-guard.py --help` for full usage (after resolving `{baseDir}`).

- `--convention` (required): `conventional`, `gitmoji`, or `custom`
- `--message` (required unless `--file`): commit message string
- `--file` (required unless `--message`): path to commit message file
- `--dry-run` (optional): validate only; do not run git commit

## User input guidance

If you cannot proceed, pause and ask. Examples include: ambiguous convention, unresolved conflicts, failed checks, or a failed push.

- Summarize the current state and what you attempted.
- Offer a recommended option and why.
- List alternative options the user can choose.

## Options

These options can be expressed in natural language, not just the flag form.
Honor the user's explicit request even if it does not use `--flag` syntax.

- `--dry-run`: analyze changes and recommend a commit message, but do not commit or push
- `--no-verify`: skip tests, lint, and format checks even if they exist
- `--pull`: run `git pull` before reviewing changes; attempt conflict resolution
- `--push`: push to the current branch after commit

## Important Rules

- **ALWAYS** identify the repo convention and follow it over defaults.
- **ALWAYS** open the matching reference and follow its rules before composing the message.
- **ALWAYS** run verify steps if they exist, unless the user requests `--no-verify`.
- **ALWAYS** use `scripts/commit-guard.py` to create commits.
- **ALWAYS** summarize state and propose options when you need user input.
- **NEVER** invent new commit types or emoji codes.
- **NEVER** stage secrets or large generated artifacts unless explicitly requested.
- **NEVER** run `git commit` directly.
- **NEVER** push unless the user explicitly requests a push (via `--push` or natural language).
- **NEVER** compose a commit message without checking the matching reference.

## References

- `references/conventional-commits.md`
- `references/gitmoji.md`