Skip to main content
skill CX Codex

commit · yonatangross — Claude Code skill: what it does, how to install

Creates Conventional Commits with scope detection, Co-Authored-By trailers and pre-commit checks; blocks secrets and generated files. Runs on commit or “save my changes”.

MIT 210 installs ★ 305 updated 2026-11-07

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add yonatangross/orchestkit --skill commit -a claude-code
Open on GitHub

What commit does

The skill verifies the branch is not main or dev, runs local linters (ruff, mypy, npm run lint) before committing, and formats the message per Conventional Commits. If .claude/agents/activity/{branch}.jsonl has agent entries since the last commit, it adds an “Agents Involved:” section and Co-Authored-By: ork:{agent} trailers.

Pass a message directly (commit fix typo in auth module) or let the skill generate one from staged changes. Default mode is a new commit; in Claude Code 2.1.91+ you can pick a mode via AskUserQuestion: new commit, --amend (local commits only), new commit with git push, or commit after git stash for unrelated changes. If Bash is unavailable, the skill returns message text only, with no branch or linter checks.

What it helps with

  • check repository state before committing
  • generate a Conventional Commit with scope detection
  • add agent authorship trailers from activity ledger
  • run linters and type checkers before git commit
  • block commits to protected branches

Example prompts for the agent

  • Save my changes in a new commit
  • Commit the auth module fix with message “fix typo in auth”
  • Run checks and create a commit for files in app/

How to install commit

1Skills CLI (Vercel)

npx skills add yonatangross/orchestkit --skill commit -a claude-code

2Manually: put the files in place

~/.claude/skills/commit/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/commit/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about commit

How to install commit in Claude Code?

Run npx skills add yonatangross/orchestkit --skill commit -a claude-code. The skill will be installed to ~/.claude/skills/commit/SKILL.md.

What does the commit skill do?

Creates Conventional Commits, checks the branch is not protected, runs linters before committing, and adds Co-Authored-By trailers for agents from the activity ledger. Blocks commits with secrets or generated files.

What does commit require to work?

A git repository and Bash. If Bash is unavailable or it is not a repository, the skill returns message text only, with no branch or linter checks.

Source text

SKILL.md · MIT
---
name: commit
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "Creates Conventional Commits with scope detection, co-author lines and hook compliance; blocks secrets and generated-only files. Use when asked to commit, save progress or write a commit message, not for incidental commits."
argument-hint: "[message]"
context: inherit
user-invocable: true
disable-model-invocation: false
allowed-tools: "Bash Read Write AskUserQuestion"
skills: [chain-patterns]
effort: low
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "${CLAUDE_PLUGIN_ROOT}/hooks/bin/run-hook.mjs skill/commit-convention-loader"
          once: true
metadata:
  category: workflow-automation
  version: "1.2.0"
  author: "OrchestKit"
  complexity: "low"
  tags: "git, commit, version-control, conventional-commits"
triggers:
  keywords: [commit, comit, "commit message", "stage and commit", "save progress", "save my progress", "wrap it up", "conventional commit"]
  examples:
    - "commit my changes"
    - "create a conventional commit for these files"
    - "stage and commit the new tests"
  anti-triggers: [push, pr, "pull request", review, rebase, merge]
invocation_hooks:
  - "git rev-parse --is-inside-work-tree >/dev/null 2>&1 || echo 'Warning: not inside a git repository'"
---

# Smart Commit

Host-neutral workflow. Invoke by skill name (`commit`). Claude Code slash routing, YAML hook loaders, and `.claude/chain` live in `references/claude-code.md`.

Simple, validated commit creation. Run checks locally, no agents needed for standard commits.

> **Note:** If `disableSkillShellExecution` is enabled (CC 2.1.91), the git repository check won't run. This skill requires a git repository.

## Quick Start

```bash
commit
commit fix typo in auth module
```

## Argument Resolution

```python
COMMIT_MSG = "$ARGUMENTS"  # Optional commit message, e.g., "fix typo in auth module"
# If provided, use as commit message. If empty, generate from staged changes.
# $ARGUMENTS[0] is the first token (CC 2.1.59 indexed access)
```

## STEP 0: Choose Commit Mode (AskUserQuestion — M118 #1465)

Default is "new commit", but voice-flow needs explicit choice when amend / push / stash is wanted:

```python
# Skip when a flag in the invocation makes the mode unambiguous:
#   commit --amend  → skip, mode=amend
#   commit --push   → skip, mode=new+push
#   commit --stash  → skip, mode=stash-first
#   ORK_COMMIT_DEFAULT_MODE=new (or amend|push|stash) → skip, use env value
#
# Otherwise, ask:
AskUserQuestion(questions=[{
  "question": "How should this commit land?",
  "header": "Commit mode",
  "options": [
    {"label": "New commit (default)", "description": "Create a new commit, leave HEAD intact"},
    {"label": "Amend HEAD", "description": "Fold staged changes into the last commit (LOCAL ONLY — refuses if HEAD is published)"},
    {"label": "New commit + push", "description": "Commit then `git push` (refuses on protected branches)"},
    {"label": "Stash first", "description": "Stash unrelated working-tree changes, then commit only what was already staged"}
  ]
}])
```

**Mode-specific guards:**

- **Amend HEAD** — verify HEAD is not on origin (`git rev-list HEAD..origin/<branch>` empty); if it is published, refuse and recommend "New commit" instead.
- **New commit + push** — re-check the protected-branch rule from Phase 1 before pushing; if HEAD's branch is `main`/`master`/`dev`, abort.
- **Stash first** — `git stash push -k -m "ork:commit autostash"` (keep-index), commit, then `git stash pop` after push success.

## Workflow

### Phase 0: Confirm there is a repository to act on

Before any guard, run `git rev-parse --is-inside-work-tree`. If it fails, or
if the Bash tool is not available in this session, say so in one sentence and
produce the commit message text only. Skip Phases 1 to 3 entirely.

Never print a branch guard, a validation status, or any other repository fact
you did not observe. Measured with `claude plugin eval` on 2026-09-12: in a
sandbox with no repository and no Bash, this skill rendered a "pre-commit
guard" box claiming the branch was `main` and protected. Nothing had been
checked. A message-only answer that says "I could not verify branch or lint
state" is correct; an invented guard is a defect.

### Phase 1: Pre-Commit Safety Check

```bash
# CRITICAL: Verify we're not on dev/main
BRANCH=$(git branch --show-current)
if [[ "$BRANCH" == "dev" || "$BRANCH" == "main" || "$BRANCH" == "master" ]]; then
  echo "STOP! Cannot commit directly to $BRANCH"
  echo "Create a feature branch: git checkout -b issue/<number>-<description>"
  exit 1
fi
```

### Phase 2: Run Validation Locally

Run every check that CI runs:

```bash
# Backend (Python)
poetry run ruff format --check app/
poetry run ruff check app/
poetry run mypy app/

# Frontend (Node.js)
npm run format:check
npm run lint
npm run typecheck
```

Fix any failures before proceeding.

### Phase 3: Review Changes

```bash
git status
git diff --staged   # What will be committed
git diff            # Unstaged changes
```

### Phase 3b: Agent Attribution (automatic)

Before committing, check for the branch activity ledger at `.claude/agents/activity/{branch}.jsonl`.
If it exists and has entries since the last commit, include them in the commit message:

1. Read `.claude/agents/activity/{branch}.jsonl` (one JSON object per line)
2. Filter entries where `ts` is after the last commit timestamp (`git log -1 --format=%cI`)
3. Skip agents with `duration_ms < 5000` (advisory-only agents go in PR, not commits)
4. Add an **"Agents Involved:"** section between the commit body and the Co-Authored-By trailer
5. Add per-agent `Co-Authored-By` trailers: `Co-Authored-By: ork:{agent} <[email protected]>`

If the ledger doesn't exist or is empty, skip this step — commit normally.

### Phase 4: Stage and Commit

> **CC 2.1.113 idiom:** Multi-line Bash with leading `# intent:` comments now shows the full command in the transcript — prefix complex scripts with a one-line intent comment so future readers (and `/recap` scans) can grep the transcript for what happened without re-reading the diff.

```bash
# intent: stage the hook change + its test + built artifacts
# Stage files
git add <files>
# Or all: git add .

# Commit with conventional format (with agent attribution if ledger exists)
git commit -m "<type>(#<issue>): <brief description>

- [Change 1]
- [Change 2]

Agents Involved:
  backend-system-architect — API design + data models (2m14s)
  security-auditor — Dependency audit (0m42s)

Co-Authored-By: Claude <[email protected]>
Co-Authored-By: ork:backend-system-architect <[email protected]>
Co-Authored-By: ork:security-auditor <[email protected]>"

# Verify
git log -1 --stat
```

> **CC 2.1.183 — `attribution.sessionUrl`:** In web and Remote Control sessions, CC appends a claude.ai session link to commit/PR attribution. Set `attribution.sessionUrl: false` (`/config attribution.sessionUrl=false`) to omit it — useful for public repos where the session link should not leak. The `Co-Authored-By` trailers above are unaffected.

### Handoff File

After successful commit, write handoff:

```python
Write(".claude/chain/committed.json", JSON.stringify({
  "phase": "commit", "sha": "<commit-sha>",
  "message": "<commit-message>", "branch": "<branch>",
  "files": [<staged-files>]
}))
```

## Commit Types

| Type | Use For |
|------|---------|
| `feat` | New feature |
| `fix` | Bug fix |
| `refactor` | Code improvement |
| `docs` | Documentation |
| `test` | Tests only |
| `chore` | Build/deps/CI |

## Quick Rules

1. **Run validation locally** - Don't spawn agents to run lint/test
2. **NO file creation** - Don't create MD files or documentation
3. **One logical change per commit** - Keep commits focused
4. **Reference issues** - Use `#123` format in commit message
5. **Subject line < 72 chars** - Keep it concise

## Quick Commit

For trivial changes (typos, single-line fixes):

```bash
git add . && git commit -m "fix(#123): Fix typo in error message

Co-Authored-By: Claude <[email protected]>"
```

## Verification Gate

Before committing, apply the 5-step gate: `Read("../../shared/rules/verification-gate.md")`. Run tests fresh. Read the output. Only commit if tests pass. "Should be fine" is not evidence.

## Quality Bar

Done means all of these hold:
- Commit landed on a feature branch, never dev/main/master (Phase 1 guard held)
- Subject uses a conventional type (feat/fix/docs/refactor/test/chore) matching the diff content, <=72 chars
- Issue reference (#N) present in the message whenever HEAD is on an issue branch
- Local validation for the touched stack (lint/type/test) ran and passed before the commit
- `Co-Authored-By: Claude` trailer present; per-agent trailers added only when the activity ledger has post-last-commit entries
- `git log -1 --stat` shows exactly the intended files, no secrets and no generated-only-noise commit

## Related Skills
- `ork:create-pr`: Create pull requests from commits
- `ork:review-pr`: Review changes before committing
- `ork:fix-issue`: Fix issues and commit the fixes
- `ork:issue-progress-tracking`: Auto-updates GitHub issues with commit progress

## Rules

Each category has individual rule files in `rules/` loaded on-demand:

| Category | Rule | Impact | Key Pattern |
|----------|------|--------|-------------|
| Atomic Commits | `rules/atomic-commit.md` | CRITICAL | One logical change per commit, atomicity test |
| Branch Protection | `rules/branch-protection.md` | CRITICAL | Protected branches, required PR workflow |
| Commit Splitting | `rules/commit-splitting.md` | HIGH | `git add -p`, interactive staging, separation strategies |
| Conventional Format | `rules/conventional-format.md` | HIGH | type(scope): description, breaking changes |
| History Hygiene | `rules/history-hygiene.md` | HIGH | Squash WIP, fixup commits, clean history |
| Issue Reference | `rules/issue-reference-required.md` | HIGH | Reference issue `#N` in commits on issue branches |
| Merge Strategy | `rules/merge-strategy.md` | HIGH | Rebase-first, conflict resolution, force-with-lease |
| Stacked PRs | `rules/stacked-pr-workflow.md` | HIGH | Stack planning, PR creation, dependency tracking |
| Stacked PRs | `rules/stacked-pr-rebase.md` | HIGH | Rebase management, force-with-lease, retargeting |

**Total: 9 rules across 8 categories**

## References

Load on demand with `Read("references/<file>")`:
| File | Content |
|------|---------|
| `references/conventional-commits.md` | Conventional commits specification |
| `references/recovery.md` | Recovery procedures |

© OrchestKit · MIT · yonatangross/orchestkit

Similar skills

All skills for Git and GitHub →

commit by other authors comes first.

commit getsentry Drafts Sentry-style conventional commits with issue references and blocks direct commits to main. CX Codex +1 4,900installs commit NeoLabHQ Automates Git commits using conventional commit messages and matching emojis. It checks the active branch, runs pre-commit linters, and suggests splitting complex diffs into atomic commits. CX Codex +1 1,300installs commit parcadei This skill turns session changes into git commits, shows you the plan first, and keeps Claude's name out of the messages. Handy when an agent has piled up edits. CX Codex +1 505installs commit FradSer This skill creates atomic conventional commits through git-agent. Use it when a short intent should become a focused Git commit. CX Codex +1 121installs commit PaulRBerg Composes the commit message from prepared evidence and hands the commit, index reconciliation and push to ai-commit. CX Codex +1 347installs git-commit official github A GitHub Copilot skill that turns a working diff into a commit: it reads the changes, stages the related files, writes a Conventional Commits message and runs git commit. CX Codex +1 47,165installs ce-commit EveryInc ce-commit is a Claude Code skill that automatically creates git commits with meaningful messages. It splits staged or unstaged changes into logical groups without pushing. CX Codex +1 3,600installs conventional-commit marcelorodrigo Makes AI coding agents write commits to the Conventional Commits spec: type, scope, imperative subject. CX Codex +1 964installs git-commit-helper davila7 Reads git diff --staged and drafts a commit message following Conventional Commits. It fires after every Bash tool call and appends a line to ~/.claude/git-commit-helper.log. CX Codex +1 7,093installs commit-message herdodp commit-message is a Claude Code skill that enforces structured commit formatting. Activates when asking the agent to commit changes or draft a commit note. CX Codex +1 ★ 325repo stars commit-pr ZaxbyHub commit-pr — a portable skill that verifies your code before push, writes conventional commits, and fills in a PR body. Guards against accidentally committing generated files or secrets. CX Codex +1 ★ 539repo stars

From the same set86

The whole set →
task-dependency-patterns task-dependency-patterns is a Claude Code skill for splitting complex work into linked tasks. It covers status tracking and coordination across parallel work. CX Codex +1 214installs api-design api-design establishes design standards for REST, GraphQL, and gRPC contracts when editing endpoints or OpenAPI files. Triggers on route definitions and schema changes. CX Codex +1 211installs assess The assess skill rates code or design decisions 0-10 across seven dimensions: correctness, readability, complexity, performance, security, maintainability and compliance. CX Codex +1 211installs verify verify is a skill that checks whether work is ready to merge by running tests, security and type checks, then assigns a 0–10 score. CX Codex +1 210installs analytics analytics queries local Claude Code logs to report agent usage, hook latency, and token expenses. Runs whenever you inspect session costs or runtime bottlenecks. CX Codex +1 210installs create-pr create-pr — a skill that opens a GitHub pull request after running tests, linter, types, and security checks. Triggers on explicit invocation; plain gh pr create stays a command. CX Codex +1 209installs audit-full audit-full audits an entire codebase for security, architecture, and dependency issues in one pass, then ranks findings by severity. It fits release checks and security reviews. CX Codex +1 208installs implement The implement skill builds a new feature in parallel: backend, frontend, tests and security checks in separate worktrees. Triggered by implement [description] — designs the architecture, splits work across subagents, runs tests. CX Codex +1 206installs

Project sponsors

Companies that keep this analytics open