holocron/plugins/git/.apm/skills/git-commits/SKILL.md

name, description, metadata, allowed-tools

name	description	metadata	allowed-tools
git-commits	Use when creating, amending, squashing, or cherry-picking commits. Generates well-formatted commit messages following Conventional Commits spec (type, scope, description, body, footers). Validates against commitlint config-conventional constraints (header max 100 chars, lowercase subject, no trailing periods, type must be one of 11 standard types). Communicates SemVer impact (MAJOR for breaking changes, MINOR for features, PATCH for fixes). Handles confirmation gates for history-altering operations (amend, rebase, squash). Provides interactive guidance for humans, structured JSON output for agents. Do not use for: inspecting git history, branch management, or repository state inspection — those are separate skills.	version category source_keys 0.1.2 git conventional-commits-spec commitlint-config-conventional org-commit-conventions context7-git-htmldocs	Bash

Gotchas

• Type must be one of 11 standard types — feat, fix, perf, revert, docs, style, refactor, test, build, ci, chore. Non-standard types will fail commitlint validation. Note: the Conventional Commits spec itself only mandates feat/fix — the 11-type set is a commitlint/Angular convention this skill validates against, not a spec requirement.
• Scope is optional but should be used — helps identify which part of the system changed. Examples: api, db, cli, config.
• Header max 100 characters — type + scope + colon + description must fit. If longer, move detail to body.
• BREAKING CHANGE notation — use ! before the colon (feat!: drop Node 6) for visibility in git log --oneline. Footer notation (BREAKING CHANGE: ...) is machine-readable but hidden in log.
• SemVer mapping is not optional — agents must communicate: feat → MINOR bump, fix/perf/revert → PATCH, any with breaking change → MAJOR.
• Confirmation gates are mandatory for destructive operations — amend, rebase, squash require explicit user/agent approval before execution.
• Never skip hooks with --no-verify — hooks are the automated QA gate; bypassing them breaks the pipeline. Do not add this flag to any commit command unless the user explicitly demands it, and warn them if they do.
• Never force-push main/master — even after an amend or interactive rebase, refuse to force-push a protected branch (main, master) and explain why; force-push is only safe on branches no one else has based work on.
• Command examples use the rtk git wrapper — this org's convention routes all git invocations through rtk git <subcommand> instead of bare git <subcommand>. Follow this prefix in any command you actually run.
• Never commit secrets, credentials, or environment-specific config — if staged changes contain what looks like an API key, token, password, or connection string, stop and flag it before committing rather than committing it.
• Commits must be atomic and leave the repo working — each commit should be one logical, independently reviewable and reversible change, and should leave the repository in a buildable/testable state. If staged changes bundle unrelated work, suggest splitting before committing.
• Commit messages explain why, not what — the diff already shows what changed; the message's job is to capture context the diff can't (motivation, root cause, tradeoffs). See references/commit-template.md for the structure this maps to.

Workflow

For creating a new commit:

1. Gather context — what changed and why? (from staged changes, PR description, issue context). Verify the staged diff is one logical, atomic change and that the repo would still build/test at this commit — if not, suggest splitting before proceeding.
2. Check for secrets — scan the staged diff for anything that looks like a credential, API key, token, or environment-specific config. Stop and flag it rather than committing.
3. Determine type — is this a feature (feat), bug fix (fix), or other? Default: check the change itself.
4. Determine scope — which system/module? Use scope from plugin config if set, otherwise infer from files changed.
5. Write description — imperative mood, no period. Neither source spec sets a length target below the 100-char header max, but convention favors keeping it to ~50 characters where possible for git log --oneline readability. Examples: "add user authentication", "fix race condition in cache".
6. Add body if needed — explain why (not what). Blank line before body, wrap at 100 chars. For non-trivial changes, follow the Why / Implementation Notes / Impact structure in references/commit-template.md.
7. Add footers if needed — Fixes: #123, Refs: #123, ADR: 0012, RFC: 0003, Design: <link>, Reviewed-by: Name, Co-authored-by: Name <email>, Signed-off-by: Name <email>, BREAKING CHANGE: description. See references/commit-template.md for the full trailer list.
8. Validate — check header length, type correctness, no trailing periods, lowercase.
9. Confirm and execute — for agents, require explicit approval; for humans, show preview and ask. Never add --no-verify to skip hooks.

For amending a commit:

1. Stage new changes (or changes to undo)
2. Run amend operation — executes rtk git commit --amend [--no-edit] based on user intent
3. Offer message edit — if user wants to change commit message, show current message and prompt for new one
4. Confirm before force-push — amending is only safe on non-shared branches; if the current branch is main/master, refuse to force-push and explain why rather than warning and proceeding

For squashing commits (interactive rebase):

1. Identify commits to squash — typically the last N commits on current branch
2. Confirm operation — squashing rewrites history; get explicit approval
3. Execute rebase — rtk git rebase -i HEAD~N, mark older commits as squash or fixup
4. Handle merge conflicts — if rebase halts, offer conflict resolution options or abort; do not resolve automatically without confirmation
5. Offer message composition — if squashing interactive, allow message editing

For squashing commits (autosquash — preferred when tagging at commit time):

Prefer this over manual interactive rebase when a commit is written to be folded into an earlier one, since it removes the manual "mark as squash/fixup" step and the risk of reordering the wrong line:

1. Create the fixup/squash commit — rtk git commit --fixup=<commit> (keeps target's message) or rtk git commit --squash=<commit> (lets you edit the combined message later). Both prefix the message with fixup!/squash! and target <commit>.
2. Confirm operation — rewriting history still requires explicit approval before the rebase runs.
3. Execute — rtk git rebase --autosquash HEAD~N (or -i --autosquash to review the plan first); git reorders and marks the fixup!/squash! commits against their targets automatically.
4. Handle merge conflicts — same as manual rebase: offer resolution or abort, never resolve automatically without confirmation.

For cherry-picking:

1. Identify source commit(s) — hash or branch reference
2. Confirm destination branch — cherry-pick will replay commits on current branch
3. Execute cherry-pick — rtk git cherry-pick <commit-hash>
4. Handle conflicts — offer conflict resolution or abort
5. Report outcome — successful replays, conflicts, or rejected commits

Output format (for agent consumption)

Return structured JSON:

{
  "operation": "create|amend|squash|cherry-pick",
  "status": "success|conflict|rejected",
  "message": "Commit message or error description",
  "commit_hash": "abc1234",
  "semver_impact": "MAJOR|MINOR|PATCH|none",
  "breaking_change": true|false,
  "confirmation_required": true|false,
  "details": {
    "type": "feat",
    "scope": "api",
    "description": "add user authentication",
    "body": "optional body text",
    "footers": ["Fixes: #123", "Refs: #456", "ADR: 0012", "Reviewed-by: Alice", "Co-authored-by: Bob <bob@example.com>", "Signed-off-by: Alice <alice@example.com>"]
  }
}

For interactive human use, format as readable prose with clear prompts and previews.

Reference

If a footer or type/scope edge case isn't covered above, read references/conventional-commits-spec.md for the full specification.

For the Why / Implementation Notes / Impact body structure and the full trailer list, read references/commit-template.md.