playbooks

home / skills / yonatangross / orchestkit / commit

commit skill

/plugins/ork/skills/commit

This skill creates validated conventional commits locally, ensuring branch safety, linting, and concise messages before pushing.

npx playbooks add skill yonatangross/orchestkit --skill commit

Review the files below or copy the command above to add this skill to your agents.

Files (11)
SKILL.md
3.4 KB
---
name: commit
license: MIT
compatibility: "Claude Code 2.1.34+."
description: "Creates commits with conventional format and validation. Use when committing changes or generating commit messages."
argument-hint: "[message]"
context: inherit
agent: git-operations-engineer
version: 1.0.0
author: OrchestKit
tags: [git, commit, version-control, conventional-commits]
user-invocable: true
allowed-tools: [Bash]
skills: [git-recovery]
complexity: low
metadata:
  category: workflow-automation
---

# Smart Commit

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

## Quick Start

```bash
/commit
```

## Workflow

### 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 4: Stage and Commit

```bash
# Stage files
git add <files>
# Or all: git add .

# Commit with conventional format
git commit -m "<type>(#<issue>): <brief description>

- [Change 1]
- [Change 2]

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

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

## Commit Types

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

## 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]>"
```

## Related Skills
- create-pr: Create pull requests from commits
- review-pr: Review changes before committing
- fix-issue: Fix issues and commit the fixes
- 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 |
| 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 |
| Issue Reference | `rules/issue-reference-required.md` | HIGH | Reference issue `#N` in commits on issue branches |

**Total: 4 rules across 4 categories**

## References

- [Conventional Commits](references/conventional-commits.md)
- [Recovery](references/recovery.md)

Overview

This skill creates validated, conventional-format Git commits and enforces local safety checks before committing. It guides you through pre-commit branch validation, running the same lint/type tests as CI, reviewing diffs, and composing a conventional commit message. The goal is small, focused, and traceable commits that match project rules.

How this skill works

The skill runs a pre-commit safety check to prevent committing directly to protected branches (dev/main/master) and instructs you to create a feature branch. It then runs local validation commands (format, lint, type checks) for backend and frontend stacks, prompts you to review staged and unstaged diffs, and helps assemble a conventional commit message with issue reference and co-author metadata. It enforces rules like single logical change per commit and subject line length limits.

When to use it

  • When preparing any change for version control to ensure it meets CI-quality checks locally.
  • Before pushing changes that must reference an open issue (use #N format).
  • When you need to produce a conventional commit message for changelogs and automation.
  • For trivial fixes or typos that still require a validated, traceable commit.
  • When enforcing team rules about branch protection and atomic commits.

Best practices

  • Never commit directly to dev/main/master; create an issue-scoped feature branch.
  • Run all local validations (format, lint, type checks) and fix failures before committing.
  • Keep commits atomic: one logical change per commit and keep subject < 72 chars.
  • Reference the related issue in the subject using #<number> and include Co-Authored-By when applicable.
  • Use interactive staging (git add -p) to split unrelated changes into separate commits.

Example use cases

  • Making a bug fix: run validations, stage the fix, and commit as fix(#123): Correct null handling.
  • Adding a small feature: create feature branch, validate, then commit as feat(#456): Add user settings endpoint.
  • Fixing a typo: git add . && git commit -m "fix(#789): Fix typo in error message" for a quick validated commit.
  • Refactoring a module: split into multiple atomic commits and use refactor(#321): Improve auth middleware.
  • Preparing production release: ensure all commits follow conventional format for automated changelog generation.

FAQ

What if validation fails locally?

Fix the reported issues (format, lint, or type errors) before committing. The skill requires parity with CI to avoid breaking builds.

Can I commit to main for urgent fixes?

The policy blocks commits to dev/main/master. Create a hotfix branch (e.g., issue/123-hotfix) and follow the same validation and commit flow.