/ork:commit

Conventional commits with branch safety, validation, and co-authorship in one command.

The /ork:commit command replaces the manual cycle of staging, linting, formatting, writing a commit message, and remembering to add a co-author trailer. It runs every check that CI would run, prevents commits to protected branches, and produces conventional commit messages tied to issue numbers. This page walks through how the skill works, why it exists, and the patterns that make it most effective.

Why This Skill

Most failed CI runs trace back to something that could have been caught locally: a lint error, a type mismatch, a commit to main instead of a feature branch. The /ork:commit skill front-loads those checks so that by the time your code reaches CI, it has already passed.

It is the lowest-complexity command skill in OrchestKit (complexity: low) and one of the most frequently used. Unlike /ork:implement or /ork:review-pr, it does not spawn agents -- it runs checks directly and generates a commit message from the staged diff.

Quick Start

/ork:commit

That is the entire invocation. OrchestKit reads the staged diff, runs validation, and proposes a commit message. You approve or edit the message, and the commit is created.

How It Works

Step 1: Branch Safety Check

Before anything else, the skill checks the current branch name:

BRANCH=$(git branch --show-current)

If the branch is main, master, or dev, the skill stops immediately and tells you to create a feature branch. This prevents accidental direct commits to protected branches -- a mistake that is easy to make in the flow of development and painful to clean up.

Step 2: Run Validation Locally

The skill runs the same linters and type checkers that CI runs:

# Python projects
poetry run ruff format --check app/
poetry run ruff check app/
poetry run mypy app/

# Node.js projects
npm run format:check
npm run lint
npm run typecheck

If any check fails, the skill stops and shows you the errors. You fix them before committing, rather than discovering them 3 minutes later in a failing CI pipeline.

Step 3: Review Changes

The skill examines both staged and unstaged changes:

git status
git diff --staged
git diff

This gives Claude full context about what will be committed and what will be left behind, so the commit message accurately reflects the staged changes -- not the full working tree.

Step 4: Generate and Create the Commit

Based on the staged diff, Claude generates a conventional commit message:

feat(#123): add cursor-based pagination to user list endpoint

- Replace offset pagination with cursor-based approach
- Add `after` and `before` query parameters
- Update OpenAPI spec with new pagination schema

Co-Authored-By: Claude <noreply@anthropic.com>

The message follows the type(scope): description format. The Co-Authored-By trailer is always appended, crediting Claude as a collaborator.

Common Patterns

Pattern 1: Fix-and-Commit Cycle

The most common workflow is fixing something and immediately committing:

# Fix the bug
# ...editing files...

# Stage and commit in one step
git add src/auth/middleware.py
/ork:commit

The skill detects that only one file is staged and generates a focused commit message for that file.

Pattern 2: Commit After `/ork:implement`

After a large implementation, you typically have many changed files. Stage them selectively:

git add src/api/ src/models/ tests/
/ork:commit

The skill reads the full diff across all staged files and generates a message that summarizes the feature, not individual file changes.

Pattern 3: Quick Commit for Trivial Changes

For typos, single-line fixes, or documentation edits, the skill generates a minimal commit:

fix(#456): correct typo in error message

Co-Authored-By: Claude <noreply@anthropic.com>

No agents are spawned. No tests are run beyond the standard lint checks. The commit is created in seconds.

Pattern 4: Referencing Issues

The skill automatically includes issue references when it detects them from context. If you have been working on issue #123 (via /ork:fix-issue 123 or conversation context), the commit message includes the issue number in the scope.

Tips and Tricks

One logical change per commit. The skill works best when your staged changes represent a single logical change. If you have mixed changes (a bug fix and a refactor), stage them separately and run /ork:commit twice. This keeps your git history readable and makes reverts surgical.

Subject line stays under 72 characters. The skill enforces this automatically. If the generated subject is too long, it shortens it and moves detail into the body. This ensures commit messages render cleanly in git log --oneline and GitHub's commit list.

Validation runs every time. Even for a one-line typo fix, the skill runs lint and type checks. This catches cases where a "trivial" change accidentally breaks something. If you need to bypass this for a genuine emergency, use git commit directly -- but you lose the conventional message formatting and branch safety.

The skill does not push. After committing, your changes are local. Use /ork:create-pr when you are ready to push and open a pull request. This separation lets you make multiple commits before pushing.

Commit Types Reference

Type	When to Use	Example
`feat`	New feature or capability	`feat(#12): add email notifications`
`fix`	Bug fix	`fix(#34): handle null session token`
`refactor`	Code improvement, no behavior change	`refactor: extract pagination helper`
`docs`	Documentation only	`docs: update API endpoint table`
`test`	Tests only	`test: add regression test for #56`
`chore`	Build, deps, CI, tooling	`chore: upgrade ruff to 0.8.0`

/ork:create-pr -- Push and open a pull request after committing
/ork:review-pr -- Review changes before or after committing
/ork:verify -- Run comprehensive verification before committing
Command Skills Reference -- All 23 command skills

/ork:commit

On this page