agentleFS
hiteshbandhuhiteshbandhu/skills-i-use/skills/raise-pr/SKILL.md

raise-pr

Skill1 starsChanged 5 months agoMITView on GitHub

Take a ready change from working tree to merged PR — branch, commit, push, open PR with a body drafted from the diff, watch CI, and squash-merge when green. General and portable: follows each repo's own commit/branch convention rather than imposing one. Never commits, pushes, or merges without explicit confirmation. Triggers on "raise a PR", "open a PR", "pr this", "push and pr", "ship this PR", "merge when green", "commit and open a pr".

  • Reads credentials
  • Commits and pushes

7 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. 0 are common, 8 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 7 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Only when the repo gives no clear signal, fall back to these sensible defaults:

    line 39
  2. Distinctive:

    Ask which to follow instead of imposing a default.

    line 64
  3. Distinctive:

    Ask once, batch related questions, and proceed on the answer — don't re-litigate.

    line 73
  4. Distinctive:

    Don't open a PR on a known-broken tree.

    line 84
  5. Distinctive:

    If on it, Step 1 creates a branch.

    line 86
  6. Distinctive:

    Read git log --oneline -8 to learn the repo's actual commit/branch convention.

    line 95
  7. Very specific:

    If on the default branch, create type/kebab-descriptive where type matches the change and the slug summarizes it …

    line 96
  8. Distinctive:

    If already on a feature branch, reuse it.

    line 98
  9. Very specific:

    Start gh pr checks <n> --watch (background it for long runs).

    line 128
  10. Very specific:

    If branch protection blocks (required review / pending check): surface exactly why.

    line 137
  11. Very specific:

    Only use --admin when the user owns the repo and explicitly approves bypassing.

    line 138
  12. Very specific:

    After merge: git checkout <default> && git pull --ff-only.

    line 139
  13. Distinctive:

    If anything was skipped (e.g.

    line 146

“Common” is measured: kept by at least 6 in 10 of the 7 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

Raise PR — change → merged PR, cleanly

Drives the whole path from a ready working tree to a squash-merged PR, following each repo's own conventions. General and portable — no project-specific assumptions. Optionally pairs with ship-check for the pre-PR quality gate when a repo has it set up; this skill owns the git/GitHub mechanics either way.

This skill performs outward-facing actions (push, open PR, merge). Confirm before each: committing, pushing/opening the PR, and merging. Never merge on red or unverified CI.

Works with any coding agent that has git + gh (GitHub CLI, authenticated).

Supporting files:

  • pr-body-template.md — the PR description structure

Output: {SKILL_OUTPUT_DIR}/raise-pr/ (optional run log) — see ../OUTPUT.md


Conventions — detect per repo, then match

This is a general, portable skill — it works on any repo and must not impose a personal style. First read the repo's recent git log --oneline -15 (and a merged PR or two) and follow whatever convention it already uses: commit format, scope style, trailer presence, branch naming, merge strategy. The repo's own history wins.

Only when the repo gives no clear signal, fall back to these sensible defaults:

ThingFallback (used only if the repo has no clear convention)
Commit formatConventional + scoped — type(scope): summary (feat, fix, chore, refactor, docs, test)
SubjectSpecific; multiple changes → comma-separated, never "various fixes"
BodyWhat + why, plain prose, 1–3 sentences
Co-author trailerMatch the repo — include one only if its history already uses one
Branchtype/kebab-descriptive, derived from the change
MergeSquash, delete branch, gated on green CI

Ask the user when unsure — don't guess

Confirmations before commit / push / merge are always required. Beyond those, stop and ask (a short, specific question — offer a recommended default) whenever:

  • Scope is mixed — the diff spans unrelated concerns. Ask whether to split into separate commits/PRs, and which to include now.
  • Type/scope is genuinely ambiguous — e.g. feat vs fix, or no obvious scope. Propose your best guess and confirm rather than silently picking.
  • Base branch isn't obvious — repo uses develop/release branches, or the default isn't clearly the right target. Ask which base to PR against.
  • No clear repo convention and it matters (commit style, trailer, squash vs merge). Ask which to follow instead of imposing a default.
  • Merge intent is unstated — "raise a PR" doesn't say whether to merge. Default to opening and holding; ask before merging unless they said "merge when green."
  • CI is red — ask whether to fix now, hold, or abandon. Never merge around it.
  • Branch protection blocks the merge — never --admin-bypass without asking; confirm the user owns the repo and wants the policy overridden.
  • Anything destructive or irreversible — force-push, history rewrite, deleting a shared branch.

Ask once, batch related questions, and proceed on the answer — don't re-litigate.


Step 0 — Preconditions (hard gates)

Refuse to proceed and explain if any fail:

  1. Quality gate — the repo's tests/lint/typecheck should be green before opening a PR. Run them however this repo does it. (ship-check is one repo-aware way to run that gate if it's set up here — but it's optional, not a dependency of this skill.) Don't open a PR on a known-broken tree.
  2. Not on the default branch — never commit straight to main/master. If on it, Step 1 creates a branch.
  3. Clean of artifacts — no screenshots, skill-outputs/, build output, .env, or stray binaries staged. If present, offer to gitignore them; do not commit them.
  4. gh authenticated — gh auth status succeeds; remote is GitHub.

Step 1 — Branch

  • Read git log --oneline -8 to learn the repo's actual commit/branch convention.
  • If on the default branch, create type/kebab-descriptive where type matches the change and the slug summarizes it (fix/task-dropdowns-doc-edits).
  • If already on a feature branch, reuse it.

Step 2 — Commit

  1. Derive type + scope from the diff:
    • type: feat (new capability), fix (bug), refactor, docs, test, chore.
    • scope: the dominant top-level area touched (e.g. tasks, matters, mcp). Multiple areas → slash-joined (tasks/mcp/docs) or the umbrella scope.
  2. Subject: imperative, specific. If the change does several things, list them comma-separated rather than going vague.
  3. Body: 1–3 sentences — what changed and why. Add a co-author trailer only if the repo's history uses one.
  4. Show the proposed message and the git status and confirm before committing.

Step 3 — Push + open PR

  1. Push the branch (git push -u origin <branch>).
  2. Draft the PR body from pr-body-template.md, filled from the actual diff and the verification you ran (test counts, Playwright, etc.) — not boilerplate. Title = the commit subject (or an umbrella summary for multi-commit).
  3. gh pr create --base <default> --head <branch>. Show the URL.

Step 4 — Watch CI

  • Start gh pr checks <n> --watch (background it for long runs).
  • On red: stop, surface the failing job + log link, do not merge. Offer to fix.
  • On green: confirm gh pr view <n> --json mergeStateStatus is CLEAN before Step 5.

Step 5 — Merge (only on explicit go + green CI)

  • Squash-merge + delete branch: gh pr merge <n> --squash --delete-branch.
  • If branch protection blocks (required review / pending check): surface exactly why. Only use --admin when the user owns the repo and explicitly approves bypassing.
  • After merge: git checkout <default> && git pull --ff-only; report the squash commit.

Step 6 — Report

PR URL · CI result · squash commit on default · branch deleted · default synced. If anything was skipped (e.g. merge held for review), say so plainly.


Why this beats the ad-hoc flow

  • No direct-to-main, no artifact commits, no red merges — they're hard gates, not vibes.
  • Conventional scope + branch name derived from the diff — consistent history without thinking about it.
  • PR body written from the real diff + verification — reviewers get signal, not a template.
  • CI-gated squash-merge — one clean commit per PR on main, every time.

Edge cases

  • No gh — do branch + commit + push; print the PR "create" URL for the user to open manually.
  • Multiple logical changes — suggest splitting into separate commits/PRs; don't bundle unrelated work.
  • Already-open PR for this branch — update it (push), don't open a duplicate.
  • Non-GitHub remote — handle commit/push; PR/merge steps are GitHub-specific, note the limitation.
  • User says "just commit, don't PR" — stop after Step 2.

Invocation examples

raise a PR for this
@raise-pr — squash-merge when CI is green
commit and open a pr, then merge once green
pr this but hold the merge for me

Pair with

  • ship-check — run first for the lint/typecheck/test/secret-scan gate.
  • ui-ux — for UI changes, verify before raising the PR.

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.