agentleFS
fnayoufnayou/dotfiles/.claude/skills/ship-change/SKILL.md

ship-change

Skill2 starsChanged 5 months agoMITView on GitHub

Ships an already-reviewed change: sync main, branch, stage, commit, push, open a PR, and confirm CI is green. This is the repeatable "release" flow used after the Builder/Reviewer steps are done. Do not use this to bypass review — the change must already be reviewed (see review-change). - Reviewer verdicts are all PASS (safety, privacy, documentation). - If the change added/removed/first-stowed a Stow package, both status blocks (AGENTS.md §2 and CLAUDE.md) are already updated in the same set of changes…

  • Commits and pushes

5 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

11 rules. 0 are common, 5 are distinctive, and 6 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Do not use this to bypass review — the change must already be reviewed (see review-change).

    line 12
  2. Very specific:

    If the change added/removed/first-stowed a Stow package, both status blocks (AGENTS.md §2 and CLAUDE.md) are already updated in the same …

    line 17
  3. Distinctive:

    No secrets in the diff (privacy rule) — re-audit staged diff before committing.

    line 19
  4. Very specific:

    If main is behind, fast-forward it (git switch main && git pull --ff-only) before branching.

    line 28
  5. Very specific:

    If it reports stale files, run task brand:generate, review git diff --stat brand/generated/, and stage the images with the change.

    line 42
  6. Very specific:

    Do not end the PR body with the Claude Code generated-by line — the same user rule that bans the Co-Authored-By trailer bans that footer.

    line 69
  7. Distinctive:

    Always write the message to a file and pass it by path:

    line 120
  8. Distinctive:

    Run git commit as the only thing in its Bash call.

    line 151
  9. Very specific:

    Read-only chains (git add ….

    line 153
  10. Distinctive:

    If a commit call does stall, do not retry it verbatim — check git log -1 and git status --short first.

    line 155
  11. Distinctive:

    Never force-push or rewrite shared history without explicit user approval.

    line 187

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Skill: ship-change

Ships an already-reviewed change: sync main, branch, stage, commit, push, open a PR, and confirm CI is green. This is the repeatable "release" flow used after the Builder/Reviewer steps are done.

When to use

  • The change is implemented and has passed review (Reviewer verdicts PASS).
  • The working tree holds the finished change on main (or a feature branch already exists).
  • The user asks to "commit and open a PR", "ship it", "as usual", or similar.

Do not use this to bypass review — the change must already be reviewed (see review-change).

Preconditions

  • Reviewer verdicts are all PASS (safety, privacy, documentation).
  • If the change added/removed/first-stowed a Stow package, both status blocks (AGENTS.md §2 and CLAUDE.md) are already updated in the same set of changes (see status-sync rule).
  • No secrets in the diff (privacy rule) — re-audit staged diff before committing.

Steps

  1. Sync main with remote
    git fetch origin --prune
    git rev-list --left-right --count main...origin/main   # expect "0  0"
    If main is behind, fast-forward it (git switch main && git pull --ff-only) before branching.
  2. Create a feature branch
    git switch -c <type>/<short-slug>      # e.g. feat/btop-package, docs/site-refresh
  3. Check the generated art, then stage the change

    A change to a package, task, ADR, guide, CI step, install list or the release heading can make the committed banner and social preview stale (CI fails the pull request on stale generated assets). Check first:

    task brand:check

    If it reports stale files, run task brand:generate, review git diff --stat brand/generated/, and stage the images with the change. A reminder for this also appears before git commit, git push and gh pr create when it is due (see docs/guides/art-setup.md).

    git add -A
    git diff --staged --stat
  4. Audit the staged diff (privacy) — must return nothing real:
    git diff --staged | grep -iE "password|token|api[_-]?key|secret|BEGIN.*PRIVATE|/Users/|/home/"
    git diff --staged --name-only | grep -i ds_store    # no .DS_Store
  5. Commit — message follows type(scope): description, explains intent, and never carries a Co-Authored-By trailer (user's global rule). Write the message to a file and pass it as -F <file> — never -F -. See "Environment gotchas" below.
  6. Push
    git push -u origin <branch>
  7. Open the PR with gh, body from a file:
    gh pr create --base main --head <branch> --title "<same as commit subject>" --body-file <file>
    Do not end the PR body with the Claude Code generated-by line — the same user rule that bans the Co-Authored-By trailer bans that footer. PRs are authored as the user only.
  8. Confirm CI passes (green, no blocking issues):
    gh pr checks <N>
    gh pr view <N> --json statusCheckRollup -q '.statusCheckRollup[] | "\(.name): \(.status)/\(.conclusion)"'
    gh pr view <N> --json mergeable,mergeStateStatus -q '"mergeable=\(.mergeable) state=\(.mergeStateStatus)"'
    Poll until every check is COMPLETED/SUCCESS and mergeStateStatus is CLEAN. Report failures with their log output; do not claim green while checks are still pending.
  9. Report the PR link back to the user.

Environment gotchas

A silent stall is a pending permission prompt, not a hang

Symptom: a Bash call produces no output, never exits, and the ref never moves. ps shows the shell wrapper parked in sigsuspend with no git child process — the command never started.

That is the signature of a permission prompt waiting on the user, not a crash or a deadlock. Wait for the user, or re-run the command in a form that the allow-list already covers. It is not a git editor/hook/GPG problem (verify: no core.hooksPath, no commit.gpgsign).

rtk wrapper — let the rewrite happen

A PreToolUse hook transparently rewrites git … to rtk git …. That rewrite is what makes git work smoothly here, because .claude/settings.local.json allows Bash(rtk git *) — every rewritten git command auto-approves.

So prefer plain git. Do not reach for /usr/bin/git: the absolute path is not rewritten, so it matches no allow-list entry and queues a permission prompt instead.

Measured on rtk 0.44.1 — rtk is not a source of hangs:

CheckResult
rtk hook claude fed a git commit payloadreturns in 0s, rewrites to rtk git commit
rtk git commit -q -m …0s, commit created
plain git add && git commit, direct Bash callcompletes normally

That last row held when it was measured, but it is not reliable — a later session hit the full timeout on exactly that shape. Prefer the split form in the next section. rtk is still not the culprit either way.

Never use git commit -F -

Passing the message on stdin via a heredoc does hang: the hook rewrites the command string, the heredoc does not survive intact, and git waits forever on a stdin that never arrives.

Always write the message to a file and pass it by path:

git commit -q -F "$MSG_FILE"

Give git commit a Bash call of its own

-F - is not the only shape that stalls. Two more were measured on 2026-08-04, both of which parked for the full timeout and left the change staged but uncommitted:

ShapeResult
heredoc writing $MSG_FILE, then git commit -F "$MSG_FILE" — same callstalled at 2m, commit never ran
git add -A + git commit -F … + git push — chained with ; in one callstalled at 3m, commit never ran
git commit -q -F <abs-path> </dev/null — alone in its own callsucceeded immediately
git push -u origin <branch> — alone in its own callsucceeded immediately

The first case extends the -F - rule: the problem is a heredoc anywhere in the same command as the commit, not just one feeding stdin. The second involves no heredoc at all, so quoting is not the common factor.

Both are consistent with the permission-prompt signature above. .claude/settings.local.json allows Bash(rtk git *) — a prefix matcher against the visible command string. A compound string still holds ; and later commands after the rewritten prefix, so it does not match the entry that auto-approves plain git, and it queues a prompt instead. That also explains the symptom: the stall lands on the first git call in the chain, so nothing after it runs.

So:

  • Build the commit message with the Write tool, not a heredoc. Pass it by absolute path.
  • Run git commit as the only thing in its Bash call.
  • Run git push as the only thing in its Bash call.
  • Read-only chains (git add …; git diff --staged --stat) are fine and stay convenient.

If a commit call does stall, do not retry it verbatim — check git log -1 and git status --short first. In both measured cases the tree was still staged and re-running the split form worked with no cleanup needed.

Script files, and what they actually do

Putting a sequence in a shell script file and running bash /path/script.sh is useful for multi-step flows (stage → audit → commit → push) and keeps quoting sane. It also sidesteps permission prompts, because the matcher inspects the visible command (bash …) and not the script's contents.

It is therefore the sanctioned way to keep a multi-step flow in one call despite the rule above — the compound string lives inside the file, where nothing matches it. What it does not excuse is chaining git calls inline; that is the shape that stalls.

cat > "$SCRATCH/do-commit.sh" <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
cd <repo>
export GIT_EDITOR=true GIT_TERMINAL_PROMPT=0
git add <paths>
git diff --staged --stat
git commit -q -F "$MSG_FILE" </dev/null
git rev-parse --short HEAD
EOF
bash "$SCRATCH/do-commit.sh"

Notes

  • One focused commit is preferred over batching unrelated work.
  • Status-block changes must travel in the same commit as the package change (status-sync rule).
  • Never force-push or rewrite shared history without explicit user approval.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.