playbooks

home / skills / phrazzld / claude-config / commit

commit skill

/skills/commit

This skill analyzes workspace changes, tidies files, and creates semantic commits with conventional prefixes ready to push.

npx playbooks add skill phrazzld/claude-config --skill commit

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

Files (1)
SKILL.md
1.6 KB
---
name: commit
description: |
  Tidy workspace, create semantically meaningful commits, and push.
  Analyzes changes, categorizes files (commit/gitignore/delete/consolidate),
  groups into logical commits with conventional prefixes.
  Use when: ready to commit, cleaning workspace, pushing changes.
effort: medium
---

# /commit

Analyze changes, tidy up, create semantic commits, push.

## Role

Engineer maintaining a clean, readable git history.

## Objective

Transform working directory changes into well-organized, semantically meaningful commits. Push to remote.

## Latitude

- Delete cruft, add to `.gitignore`, consolidate files as needed
- Confirm before non-obvious deletions
- Split changes into logical commits (one change per commit)
- Skip quality gates if `--quick` flag or no package.json

## Workflow

1. **Analyze** — `git status --short && git diff --stat HEAD`
2. **Tidy** — Categorize files: commit, gitignore, delete, consolidate. Execute cleanup.
3. **Group** — Split into logical commits by type: `feat:`, `fix:`, `docs:`, `refactor:`, `perf:`, `test:`, `build:`, `ci:`, `chore:`
4. **Commit** — One commit per group. Subject: imperative, lowercase, no period, ~50 chars. Body: why not what.
5. **Quality** — Run available gates (`pnpm lint`, `typecheck`, `test`, `build`) unless `--quick`
6. **Push** — `git fetch origin && git push origin HEAD` (rebase if behind)

## Flags

- `--no-push` / `dry` — Commit but don't push
- `--quick` / `fast` — Skip quality gates
- `--amend` — Amend last commit (use carefully)

## Safety

Never force push. Never push to main without confirmation. Always fetch before push.

Overview

This skill tidies your workspace, creates semantically meaningful commits, and pushes them to the remote. It analyzes uncommitted changes, categorizes files, groups changes into logical commits with conventional prefixes, runs optional quality gates, and optionally pushes the result. Designed to produce a clean, navigable git history without manual bookkeeping.

How this skill works

The skill inspects the working tree and diffs to identify changed, untracked, and deleted files. It categorizes files into actions (commit, add to .gitignore, delete, consolidate), groups related changes into single-purpose commits using conventional prefixes (feat:, fix:, docs:, etc.), runs configured quality checks unless run in quick mode, and finally pushes to the remote after fetching. It will prompt before non-obvious deletions and avoids unsafe operations like force-pushing or pushing to main without confirmation.

When to use it

  • You have uncommitted changes and want a clean, logical commit history
  • Before opening a pull request or merging to ensure commits are well-scoped
  • After refactoring or many small edits that need consolidation
  • When preparing a workspace for teammates to review
  • When you want automated commit message prefixes and quality checks

Best practices

  • Keep each commit focused: one intent per commit (feature, fix, docs, etc.)
  • Write imperative, lowercase commit subjects around 50 characters, no trailing period
  • Use the commit body to explain why the change was made, not what was changed
  • Run without --quick to execute lint, typecheck, tests, and build gates when available
  • Confirm deletions and avoid pushing to main without explicit approval

Example use cases

  • Consolidate dozens of small edits into a small set of meaningful commits before pushing
  • Automatically add generated or temporary files to .gitignore and remove cruft
  • Split a mixed change set into separate feat:, fix:, and docs: commits for clarity
  • Quickly commit and push hotfixes using --quick when running full gates is unnecessary
  • Amend the previous commit to merge a follow-up fix without creating extra commits

FAQ

Will this skill ever force-push or overwrite remote history?

No. It never force-pushes and will prompt before any unsafe push. It fetches first and will prompt if a rebase or manual intervention is required.

What does --quick do?

--quick skips configured quality gates like lint, typecheck, tests, and build to speed up the commit-and-push flow.