Claude Skill

commit

Imported from paulrberg/agent-skills/skills/commit.

LLM Mart · 0 points · 0 0 0

Virus-scanned Reviewed automatically before listing.

Full trust report

Download paulrberg-agent-skills-skills_commit-913232a.zip · 6 KB

paulrberg/agent-skills 94 7 forks MIT Updated 8h ago

Part of paulrberg/agent-skills — 42 skills

Install

skills CLI npx skills add https://github.com/PaulRBerg/agent-skills/tree/main/skills/commit

Claude Code

claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install paulrberg-agent-skills@llmmart

Git git clone https://github.com/PaulRBerg/agent-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole paulrberg/agent-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Git Commit

Compose the semantic commit message from immutable evidence. Let ai-commit own deterministic preparation, commit, index reconciliation, and push mechanics.

Run every command from the target repository cwd. Do not surround ai-commit with extra git status, git log, or git diff calls: preparation provides the complete evidence for this workflow. Use --porcelain only in deterministic automation that explicitly parses its stable TSV records; the normal skill flow consumes the human-readable sections.

1. Parse Arguments

Arguments: $ARGUMENTS

ai-commit selects the message format from repository config; pass --natural or --conventional only as an explicit one-off override, never to reproduce repository policy.
--all: capture all worktree and index changes. This intentionally risks including another agent's work.
--staged: capture exactly the current index; do not add session paths. It conflicts with --all.
--natural: force Natural Language Format for this commit.
--conventional: force Conventional Prefix Format for this commit.
--push: request a push after commit. Otherwise push only when standing instructions authorize it.
--close <issue_numbers>: append one Closes #N trailer per positive decimal issue number; accept comma- or space-separated input.
--finding <finding_ids>: append one Finding-ID: <id> trailer per ledger finding this commit fixes; accept comma- or space-separated input. Also infer a finding from context when this session's commit fixes a specific ledger finding. Never include or resolve findings the commit does not actually fix.
In Conventional Prefix Format, a positional type keyword overrides the inferred type. In Natural Language Format, a positional verb or category keyword overrides the inferred verb. Quoted positional text overrides the inferred description or subject.

If the requested operation is only to push a clean branch that is already ahead, skip preparation and run ai-commit push.

2. Prepare Once

Run one preparation command:

ai-commit prepare [--all | --staged] [--natural | --conventional] --diff full \
  [--exclude-baseline '<path>=<oid>']... [-- <session-modified-paths>...]

Read the full preparation output; never pipe it through tail, head, awk, grep, or similar. It carries both the printed transaction ID and the diff step 3 must analyze, and a truncating pipe discards the evidence along with the ID.
Before default-mode preparation, run the repository's formatter on this session's edited paths only, so a formatting pre-commit hook cannot modify the content after it is pinned.
Build the path list from this session's edited paths, never by parsing git status or git status --porcelain output, which can include another agent's untracked or modified files. Default mode requires every path edited in this session; for a rename, include both old and new names, including case-only file or directory renames.
Before default-mode preparation, run ai-coord touched when available and reconcile its output against the session path list: add missed session-edited paths, but ignore paths this session did not semantically change because touched paths are best-effort evidence, not authority. Skip this cross-check silently when the command is unavailable or the session is unrecognized.
--all accepts no explicit paths and captures all tracked, untracked, modified, deleted, and staged changes.
--staged accepts neither explicit paths nor baseline exclusions and captures the shared index exactly.
ai-commit prepare automatically applies this session's ai-coord stale-dirt baselines. Auto-applied exclusions appear in the preparation evidence and must be disclosed unchanged. Explicit --exclude-baseline remains available for overrides, and --no-auto-baseline disables discovery for deterministic automation. Never revert unrelated changes. If coordination re-entry records this session's completed edits as a baseline, compare its blob IDs with retained session or preparation evidence. Use --no-auto-baseline only when every selected file's entire delta is attributable to the authorized task; preserve exclusions for mixed ownership or uncertain attribution.

Preparation pins the exact tree and delta under the printed transaction ID without changing the shared index. Keep that ID. The later commit reuses the transaction instead of recomputing intended content from the mutable worktree or shared index. It applies that immutable delta to the locked current branch and fails safely if intervening branch movement conflicts. If preparation fails before issuing a transaction ID, correct the evidenced argument, attribution, or input problem and retry preparation within the authorized scope.

3. Analyze and Compose

Analyze the single prepared full diff. Do not replace a valid preparation merely to get different evidence. Oversized per-file sections arrive cut with a DIFF_TRUNCATED disclosure; their name-status and shortstat evidence still governs the message.

Use the printed message format and message-format rules. ai-commit is the source of those rules; do not load a separate Conventional or Natural reference.
Apply positional overrides, detect breaking changes, infer scope or context from the code, and include a body only when it adds material rationale.
Add Closes #N trailers from --close and from transcript issue references only when this commit actually resolves them. De-duplicate issue numbers.
Add one Finding-ID: <id> trailer per finding supplied by --finding or inferred from context that this commit actually fixes. De-duplicate finding IDs.
Append the exact Agent-Session: line from the preparation trailer section when present. ai-commit has already validated it; do not synthesize or repair a missing or malformed trailer.

Compose one subject paragraph, an optional body paragraph, and one final trailer paragraph containing all Closes, Finding-ID, and Agent-Session lines.

ai-commit receives every -m value verbatim and rejects a literal \\n; write real line breaks inside the quoted argument, as in the step 4 example.

4. Commit the Transaction

Run:

ai-commit commit <transaction-id> -m '<subject>' [-m '<body>'] [-m '<trailers>'] [--push]

For example, a two-item body is one -m argument containing a physical newline:

ai-commit commit <transaction-id> -m '<subject>' -m '- first material change
- second material change' [-m '<trailers>'] [--push]

Append --push when explicitly requested or authorized by standing instructions. The same command handles default, --all, and --staged transactions; never stage or commit them with direct Git commands.

Transactions are idempotent. After an interruption, lock race, or retryable exit, retry the same transaction ID and message arguments; do not prepare a replacement from newer mutable state. A replay recovers or returns the retained receipt without creating a duplicate commit. Never delete an index lock.

For a deterministic content failure proven to precede commit creation, correct the authorized work and supersede the uncommitted preparation using the recovery reference. This includes snapshot-check hook modified prepared content; an immutable retry cannot repair content pinned in a failed snapshot. Existing task authority covers this recovery.

Read references/failure-recovery.md before superseding a failed preparation or adding --no-verify or --no-gpg-sign. Bypass flags are explicit per-attempt recovery options, not first-attempt defaults.

After COMMITTED <transaction-id> <commit-oid> (the OID is a 12-character abbreviation; pass it as-is), resolve every included finding with ai-coord finding resolve '<id>' --as fixed --commit '<commit-oid>'.

5. Completion and Receipt

Keep the receipt compact and forward its outcome lines without decoration:

COMMITTED <transaction-id> <commit-oid> proves commit creation or idempotent recovery; without push authorization it is completion.
HOOK_ADDED <path> identifies content introduced by a hook outside the prepared path set. Disclose every such line.
PUSHED <branch> or PUSHED_NEW <branch> proves propagation and completes push-authorized or push-only work.
PUSHED <transaction-id> <commit-oid> is the retained proof returned when an already-pushed transaction is replayed.
BEHIND <branch> <count> is safe noncompletion, never completion: ai-commit fetched and refused to integrate or push. A preceding COMMITTED still proves the local commit. Run git fetch, then verify the branch is still behind its upstream, the working tree and index are clean, and no other Git operation (rebase, merge, cherry-pick, revert, bisect) is in progress. If all hold, run git pull --rebase --no-autostash and replay the same transaction command (or rerun ai-commit push for push-only work). On rebase conflicts, run git rebase --abort for only that rebase and ask the user before resolving. If the tree is dirty or another Git operation is in progress, stop and report. Never autostash.

Do not report unrelated tree state, ahead/behind counts not emitted by the command, staging narration, or successful hook activity. Add only a required one-line bypass disclosure from the recovery reference.

Files (agent-skills)

agents

openai.yaml 42 B

policy:
  allow_implicit_invocation: true

references

failure-recovery.md 5.5 KB

# Failure Recovery

Classify the failure before choosing recovery. Retry the existing immutable transaction for interruptions, lock races,
signing failures, receipt or reconciliation failures, and any uncertain commit outcome. An idempotent retry can recover
a commit created before the failure without duplicating it. A known content failure before commit creation instead
requires a corrected preparation; retrying the old snapshot cannot include its repair.

## Content Validation Failure

Use this recovery for deterministic validation failures requiring changes to authorized content, including a dependency
cycle where separately prepared units cannot pass or apply in a valid order. A timeout or transient tool failure alone
does not justify replacing a preparation.

1. Retain the failed transaction ID, its prepared path set, and the diagnostic proving which content needs correction.
   Inspect `ai-commit show <transaction-id>` and the failure receipt. Establish that no commit was created; absent or
   uncertain outcome evidence requires the same-transaction retry path instead. `PREPARED` in `show` alone does not
   prove this: the display may omit a pending commit.
2. Identify the smallest coherent correction and preserve unrelated or baseline-owned content. Existing authorization to
   fix and commit the task covers repairing its failed content and combining interdependent owned changes; a new
   permission request is needed only when the correction itself exceeds that authority.
3. Run `ai-commit discard <transaction-id>` only for the superseded, uncommitted preparation and require `DISCARDED`. If
   it refuses a pending or committed transaction, recover that same ID instead of preparing a replacement. Never rewrite
   a committed transaction or delete its retained receipt. For multiple dependent preparations, account for each ID and
   all intended changes before discarding them.
4. Apply the correction, run the relevant checks, then prepare once from the corrected owned paths. Review the full new
   evidence and compose its message around the final change. Retain the new ID and follow the normal commit workflow.

Do not bypass a validation failure caused by or plausibly affected by the prepared paths. Keep each new preparation
immutable; another evidenced content defect requires another explicit diagnosis, not an automatic reprepare loop.

## Prepared Snapshot Drift

The exact diagnostic prefix `snapshot-check hook modified prepared content` identifies a content failure before commit
creation: a verification hook tried to change the validation-only prepared snapshot. Running the repository's formatter
on session-edited paths before `prepare` (SKILL.md step 2) prevents most of this drift; use this recovery when it still
occurs.

1. Do not retry the transaction, add `--no-verify`, or make the shared worktree temporarily match the prepared index.
2. Record the repository-relative paths named by the diagnostic, then run `ai-commit discard <transaction-id>` and
   require `DISCARDED`; a pending or committed transaction still requires same-ID recovery.
3. Apply only the named deterministic formatter or generator change to session-owned content. Preserve every stale-dirt
   baseline byte; do not stage the whole physical file or restore excluded hunks temporarily.
4. Prepare once from the corrected worktree and continue with the new transaction.

If the hook-required change would alter baseline-owned bytes, stop and wait for or contact that baseline's owner instead
of discarding their work.

The legacy `partially staged files are unsafe in the shared worktree` diagnostic on a prepared path is a deterministic
compatibility failure, not index contention. Never respond with `--no-verify`, temporary hunk restoration, or a
sleep/retry loop; surface the incompatible `ai-commit`/hook path and update it before preparing another transaction.

- **Index lock:** wait and retry the same command only when the diagnostic names the default-index lock or `ai-commit`
  reports its lock refusal. Never delete a lock.
- **Hook failure:** a bare lint-staged `Failed to get staged files!` or `"lint-staged" exited with code 1` does not
  prove contention. Inspect the named hook output or lint-staged debug trace. Retry the same transaction with
  `--no-verify` only when that evidence and the immutable prepared diff conclusively prove an unrelated pre-existing
  failure. Never bypass a failure caused by, or plausibly affected by, the prepared paths. The flag bypasses pre-commit
  and commit-msg hooks for that attempt; it does not change repository configuration. After success disclose exactly one
  line: `Commit created with hooks bypassed — unrelated failure ("<short error>")`.
- **Signing failure:** when commit creation fails at signing after hooks passed, and the error names the configured
  signer rather than content or a hook, retry the same transaction once with `--no-gpg-sign`. Examples include an
  unreachable 1Password or YubiKey signer, `failed to fill whole buffer`, `ssh-agent`, `gpg failed to sign the data`, or
  `no such identity`. Never add the flag speculatively and never edit `commit.gpgsign`, `gpg.format`, or other Git
  configuration. After success disclose exactly one line:
  `Commit created unsigned — signer unavailable ("<short error>")`.

Once a genuine signer error establishes that the signer is unavailable for the session, later transactions may use
`--no-gpg-sign` on their first commit attempt. Keep the bypass per transaction and replace repeated disclosures in the
final receipt with: `N commits created unsigned — signer unavailable ("<short error>")`.

SKILL.md 9.7 KB

---
argument-hint:
  "[--all] [--staged] [--natural] [--conventional] [--push] [--close <issue_numbers>] [--finding <finding_ids>]"
compatibility: Requires Git and ai-commit with automatic ai-coord stale-dirt baseline discovery on PATH.
effort: medium
name: commit
description:
  "Commit staged or intended changes: compose a Conventional Prefix or Natural Language message, then use ai-commit —
  with --all, --staged, --close, --finding, or --push."
---

# Git Commit

Compose the semantic commit message from immutable evidence. Let `ai-commit` own deterministic preparation, commit,
index reconciliation, and push mechanics.

Run every command from the target repository cwd. Do not surround `ai-commit` with extra `git status`, `git log`, or
`git diff` calls: preparation provides the complete evidence for this workflow. Use `--porcelain` only in deterministic
automation that explicitly parses its stable TSV records; the normal skill flow consumes the human-readable sections.

## 1. Parse Arguments

Arguments: `$ARGUMENTS`

- `ai-commit` selects the message format from repository config; pass `--natural` or `--conventional` only as an
  explicit one-off override, never to reproduce repository policy.
- `--all`: capture all worktree and index changes. This intentionally risks including another agent's work.
- `--staged`: capture exactly the current index; do not add session paths. It conflicts with `--all`.
- `--natural`: force Natural Language Format for this commit.
- `--conventional`: force Conventional Prefix Format for this commit.
- `--push`: request a push after commit. Otherwise push only when standing instructions authorize it.
- `--close <issue_numbers>`: append one `Closes #N` trailer per positive decimal issue number; accept comma- or
  space-separated input.
- `--finding <finding_ids>`: append one `Finding-ID: <id>` trailer per ledger finding this commit fixes; accept comma-
  or space-separated input. Also infer a finding from context when this session's commit fixes a specific ledger
  finding. Never include or resolve findings the commit does not actually fix.
- In Conventional Prefix Format, a positional type keyword overrides the inferred type. In Natural Language Format, a
  positional verb or category keyword overrides the inferred verb. Quoted positional text overrides the inferred
  description or subject.

If the requested operation is only to push a clean branch that is already ahead, skip preparation and run
`ai-commit push`.

## 2. Prepare Once

Run one preparation command:

```bash
ai-commit prepare [--all | --staged] [--natural | --conventional] --diff full \
  [--exclude-baseline '<path>=<oid>']... [-- <session-modified-paths>...]
```

- Read the full preparation output; never pipe it through `tail`, `head`, `awk`, `grep`, or similar. It carries both the
  printed transaction ID and the diff step 3 must analyze, and a truncating pipe discards the evidence along with the
  ID.
- Before default-mode preparation, run the repository's formatter on this session's edited paths only, so a formatting
  pre-commit hook cannot modify the content after it is pinned.
- Build the path list from this session's edited paths, never by parsing `git status` or `git status --porcelain`
  output, which can include another agent's untracked or modified files. Default mode requires every path edited in this
  session; for a rename, include both old and new names, including case-only file or directory renames.
- Before default-mode preparation, run `ai-coord touched` when available and reconcile its output against the session
  path list: add missed session-edited paths, but ignore paths this session did not semantically change because touched
  paths are best-effort evidence, not authority. Skip this cross-check silently when the command is unavailable or the
  session is unrecognized.
- `--all` accepts no explicit paths and captures all tracked, untracked, modified, deleted, and staged changes.
- `--staged` accepts neither explicit paths nor baseline exclusions and captures the shared index exactly.
- `ai-commit prepare` automatically applies this session's ai-coord stale-dirt baselines. Auto-applied exclusions appear
  in the preparation evidence and must be disclosed unchanged. Explicit `--exclude-baseline` remains available for
  overrides, and `--no-auto-baseline` disables discovery for deterministic automation. Never revert unrelated changes.
  If coordination re-entry records this session's completed edits as a baseline, compare its blob IDs with retained
  session or preparation evidence. Use `--no-auto-baseline` only when every selected file's entire delta is attributable
  to the authorized task; preserve exclusions for mixed ownership or uncertain attribution.

Preparation pins the exact tree and delta under the printed transaction ID without changing the shared index. Keep that
ID. The later commit reuses the transaction instead of recomputing intended content from the mutable worktree or shared
index. It applies that immutable delta to the locked current branch and fails safely if intervening branch movement
conflicts. If preparation fails before issuing a transaction ID, correct the evidenced argument, attribution, or input
problem and retry preparation within the authorized scope.

## 3. Analyze and Compose

Analyze the single prepared full diff. Do not replace a valid preparation merely to get different evidence. Oversized
per-file sections arrive cut with a `DIFF_TRUNCATED` disclosure; their name-status and shortstat evidence still governs
the message.

- Use the printed message format and message-format rules. `ai-commit` is the source of those rules; do not load a
  separate Conventional or Natural reference.
- Apply positional overrides, detect breaking changes, infer scope or context from the code, and include a body only
  when it adds material rationale.
- Add `Closes #N` trailers from `--close` and from transcript issue references only when this commit actually resolves
  them. De-duplicate issue numbers.
- Add one `Finding-ID: <id>` trailer per finding supplied by `--finding` or inferred from context that this commit
  actually fixes. De-duplicate finding IDs.
- Append the exact `Agent-Session:` line from the preparation trailer section when present. `ai-commit` has already
  validated it; do not synthesize or repair a missing or malformed trailer.

Compose one subject paragraph, an optional body paragraph, and one final trailer paragraph containing all `Closes`,
`Finding-ID`, and `Agent-Session` lines.

`ai-commit` receives every `-m` value verbatim and rejects a literal `\\n`; write real line breaks inside the quoted
argument, as in the step 4 example.

## 4. Commit the Transaction

Run:

```bash
ai-commit commit <transaction-id> -m '<subject>' [-m '<body>'] [-m '<trailers>'] [--push]
```

For example, a two-item body is one `-m` argument containing a physical newline:

```bash
ai-commit commit <transaction-id> -m '<subject>' -m '- first material change
- second material change' [-m '<trailers>'] [--push]
```

Append `--push` when explicitly requested or authorized by standing instructions. The same command handles default,
`--all`, and `--staged` transactions; never stage or commit them with direct Git commands.

Transactions are idempotent. After an interruption, lock race, or retryable exit, retry the same transaction ID and
message arguments; do not prepare a replacement from newer mutable state. A replay recovers or returns the retained
receipt without creating a duplicate commit. Never delete an index lock.

For a deterministic content failure proven to precede commit creation, correct the authorized work and supersede the
uncommitted preparation using the recovery reference. This includes `snapshot-check hook modified prepared content`; an
immutable retry cannot repair content pinned in a failed snapshot. Existing task authority covers this recovery.

Read [references/failure-recovery.md](references/failure-recovery.md) before superseding a failed preparation or adding
`--no-verify` or `--no-gpg-sign`. Bypass flags are explicit per-attempt recovery options, not first-attempt defaults.

After `COMMITTED <transaction-id> <commit-oid>` (the OID is a 12-character abbreviation; pass it as-is), resolve every
included finding with `ai-coord finding resolve '<id>' --as fixed --commit '<commit-oid>'`.

## 5. Completion and Receipt

Keep the receipt compact and forward its outcome lines without decoration:

- `COMMITTED <transaction-id> <commit-oid>` proves commit creation or idempotent recovery; without push authorization it
  is completion.
- `HOOK_ADDED <path>` identifies content introduced by a hook outside the prepared path set. Disclose every such line.
- `PUSHED <branch>` or `PUSHED_NEW <branch>` proves propagation and completes push-authorized or push-only work.
- `PUSHED <transaction-id> <commit-oid>` is the retained proof returned when an already-pushed transaction is replayed.
- `BEHIND <branch> <count>` is safe noncompletion, never completion: `ai-commit` fetched and refused to integrate or
  push. A preceding `COMMITTED` still proves the local commit. Run `git fetch`, then verify the branch is still behind
  its upstream, the working tree and index are clean, and no other Git operation (rebase, merge, cherry-pick, revert,
  bisect) is in progress. If all hold, run `git pull --rebase --no-autostash` and replay the same transaction command
  (or rerun `ai-commit push` for push-only work). On rebase conflicts, run `git rebase --abort` for only that rebase and
  ask the user before resolving. If the tree is dirty or another Git operation is in progress, stop and report. Never
  autostash.

Do not report unrelated tree state, ahead/behind counts not emitted by the command, staging narration, or successful
hook activity. Add only a required one-line bypass disclosure from the recovery reference.