Agent skill

gh-pr

Create or update GitHub Pull Requests with the gh CLI, including deciding whether to create a new PR or only push based on existing PR merge status. Use when the user asks to open/create/edit a PR, generate a PR body/template, or says 'PRを出して/PR作成/gh pr'. Defaults: base=develop, head=current branch (same-branch only; never create/switch branches).

View SKILL.md on GitHub Repository

Stars 5

Forks 2

Install this agent skill to your Project

npx add-skill https://github.com/akiojin/skills/tree/main/github/skills/gh-pr

SKILL.md

GH PR

Overview

Create or update GitHub Pull Requests with the gh CLI using a detailed body template and strict same-branch rules.

Decision rules (must follow)

Do not create or switch branches. Always use the current branch as the PR head.
Check local working tree state before push/PR operations.
- git status --porcelain
- If output is non-empty (tracked or untracked changes), pause and ask the user what to do.
- Present 3 options: continue as-is, abort, or manual cleanup then rerun.
- Do not run git stash, git commit, or git clean automatically unless explicitly requested.
Check for an existing PR for the current head branch.
- gh pr list --head <head> --state all --json number,state,mergedAt,updatedAt,url,title,mergeCommit
If no PR exists → create a new PR.
If any PR exists and is NOT merged (mergedAt is null) → push only and finish (do not create a new PR).
- This applies to OPEN or CLOSED (unmerged) PRs.
- Only update title/body/labels if the user explicitly requests changes.
If all PRs for the head are merged → check for post-merge commits (see below).
If multiple PRs exist for the head → use the most recently updated PR for reporting, but the create vs push decision is based on mergedAt.

Post-merge commit check (critical)

When all PRs for the head branch are merged, you must check whether there are new commits after the merge:

Get the merge commit SHA of the most recent merged PR.
Count commits after the merge: git rev-list --count <merge_commit>..HEAD
Decision:
- If new commits exist → create a new PR (these changes are not in the base branch)
- If no new commits → report "No changes since last merge" and finish (do not create an empty PR)

Why this matters

Scenario A: PR merged → user makes local changes → pushes → changes are NOT in the merged PR
- Without this check, the changes would be lost or require manual intervention
Scenario B: PR merged → user says "create PR" without new changes → would create empty/duplicate PR
- This check prevents unnecessary PR creation

PR title rules (must follow)

Format: <type>(<scope>): <subject> — Conventional Commits 形式に準拠する。
type: feat / fix / docs / chore / refactor / test / ci / perf のいずれか。
scope: 省略可。変更の影響範囲を端的に示す（例: gui, core, pty）。
subject: 70文字以内。命令形（imperative mood）で書く（例: "add …" / "fix …"）。先頭大文字禁止、末尾ピリオド禁止。
ブランチ名にプレフィックス（feat/, fix/ など）がある場合、タイトルの type と一致させる。

PR body rules (must follow)

Section classification

Section	Required	Notes
Summary	YES	1-3 bullet points。"what" と "why" を両方含める
Changes	YES	ファイル/モジュール単位で変更内容を列挙
Testing	YES	実行したコマンドまたは手動テスト手順を具体的に記載
Related Issues / Links	YES	Issue番号、spec、または "None" を明記
Checklist	YES	全項目を確認してチェック/N-A を付ける
Context	Conditional	3ファイル以上の変更、または非自明な変更理由がある場合は必須
Risk / Impact	Conditional	破壊的変更・パフォーマンス影響・ロールバック手順がある場合は必須
Screenshots	Conditional	UI 変更がある場合のみ必須
Deployment	Optional	デプロイ手順がある場合のみ記載
Notes	Optional	レビュアーへの補足がある場合のみ記載

Validation (agent must check before creating PR)

Required セクションに TODO が残っていたら PR を作成してはならない。
Conditional セクションが該当しない場合は、セクション自体を削除する（空の TODO を残さない）。
Summary の各 bullet は 1文で完結 させる。曖昧な表現（"いくつかの変更", "various fixes"）を禁止する。
Changes は 変更ファイルまたはモジュール名を含む 具体的な記述にする。
Testing は 再現可能な手順 を書く（"テスト済み" のような曖昧な記述を禁止）。
Checklist の未チェック項目には理由コメントを付ける（例: - [ ] Docs updated — N/A: no user-facing change）。
Related Issues は #123 形式または URL で記載する。該当なしの場合は "None" と明記する。

Issue/PR Comment Formatting (must follow)

Final comment text must not contain escaped newline literals such as \n.
Use real line breaks in comment bodies. Do not rely on escaped sequences for formatting.
Before posting, verify the final body does not accidentally include escaped control sequences (\n, \t).
If a raw escape sequence must be shown for explanation, include it only inside a fenced code block and clarify it is intentional.

Issue Progress Comment Template (required for issue-based work)

When work is tracked in GitHub Issues, progress updates must use this template:

markdown

Progress
- ...

Done
- ...

Next
- ...

Post updates at least when starting work, after meaningful progress, and when blocked/unblocked.
In Next, explicitly state blockers or the immediate next action.

Workflow (recommended)

Confirm repo + branches
- Repo root: git rev-parse --show-toplevel
- Current branch (head): git rev-parse --abbrev-ref HEAD
- Base branch defaults to develop unless user specifies.
Check local working tree state (preflight)
- Run git status --porcelain.
- If empty, continue.
- If non-empty, show detected files and ask the user to choose:
  - Continue as-is
  - Abort
  - Manual cleanup first (git commit / git stash / git clean) and rerun
- Proceed only when the user explicitly chooses continue.
Fetch latest remote state
- git fetch origin to ensure accurate comparison
Check existing PR for head branch
- Use decision rules above to pick action.
- Treat mergedAt as the source of truth for "merged".
If all PRs are merged, perform post-merge commit check
- Get merge commit: gh pr list --head <head> --state merged --json mergeCommit -q '.[0].mergeCommit.oid'
- Count new commits: git rev-list --count <merge_commit>..HEAD
- If 0 → finish with message "No new changes since merge"
- If >0 → proceed to create new PR
Ensure the head branch is pushed
- If no upstream: git push -u origin <head>
- Otherwise: git push
Collect PR inputs (for new PR or explicit update)
- Title, Summary, Context, Changes, Testing, Risk/Impact, Deployment, Screenshots, Related Links, Notes
- Optional: labels, reviewers, assignees, draft
Build PR body from template

Read the template from the gh-pr skill path (not the current project path):
- GH_PR_SKILL_DIR="${GH_PR_SKILL_DIR:-$HOME/.codex/skills/gh-pr}"
- PR_BODY_TEMPLATE="${GH_PR_SKILL_DIR}/references/pr-body-template.md"
Read ${PR_BODY_TEMPLATE} and fill all required placeholders.
Conditional セクションが該当しない場合はセクションごと削除する。
テンプレート内の  コメントは最終出力から削除する。
Required セクションに TODO が残っている場合は PR を作成せず、ユーザーに不足情報を確認する。

Create or update the PR
- Create: gh pr create -B <base> -H <head> --title "<title>" --body-file <file>
- Update (only if user asked): gh pr edit <number> --title "<title>" --body-file <file>
Return PR URL

gh pr view <number> --json url -q .url

Post-PR CI/merge check (automatic).

After PR creation or push, load github/skills/gh-fix-pr/SKILL.md and follow its workflow to inspect CI status, merge state, and review feedback.
If all CI checks are still pending, poll (30s interval) until complete.
If conflicts, review issues, or CI failures are detected, proceed with the gh-fix-pr workflow to diagnose and fix.

Command snippets (bash)

bash

head=$(git rev-parse --abbrev-ref HEAD)
base=develop
GH_PR_SKILL_DIR="${GH_PR_SKILL_DIR:-$HOME/.codex/skills/gh-pr}"
PR_BODY_TEMPLATE="${GH_PR_SKILL_DIR}/references/pr-body-template.md"

if [ ! -f "$PR_BODY_TEMPLATE" ]; then
  echo "PR template not found: $PR_BODY_TEMPLATE" >&2
  exit 1
fi

# Preflight: local working tree state
status_lines=$(git status --porcelain)
if [ -n "$status_lines" ] && [ "${ALLOW_DIRTY_WORKTREE:-0}" != "1" ]; then
  echo "Detected local uncommitted/untracked changes:" >&2
  echo "$status_lines" >&2
  echo "Choose one before continuing: continue as-is, abort, or manual cleanup then rerun." >&2
  echo "Set ALLOW_DIRTY_WORKTREE=1 only after explicit user confirmation to continue." >&2
  exit 1
fi

# Fetch latest remote state
git fetch origin

# Check existing PRs for the head branch
pr_json=$(gh pr list --head "$head" --state all --json number,state,mergedAt,mergeCommit)
pr_count=$(echo "$pr_json" | jq 'length')
unmerged_count=$(echo "$pr_json" | jq 'map(select(.mergedAt == null)) | length')

if [ "$pr_count" -eq 0 ]; then
  action=create
elif [ "$unmerged_count" -gt 0 ]; then
  action=push_only
else
  # All PRs are merged - check for post-merge commits
  merge_commit=$(echo "$pr_json" | jq -r 'sort_by(.mergedAt) | last | .mergeCommit.oid')

  if [ -n "$merge_commit" ] && [ "$merge_commit" != "null" ]; then
    new_commits=$(git rev-list --count "$merge_commit"..HEAD 2>/dev/null || echo "0")

    if [ "$new_commits" -gt 0 ]; then
      echo "Found $new_commits commit(s) after merge - creating new PR"
      action=create
    else
      echo "No new commits since merge - nothing to do"
      action=none
    fi
  else
    # Fallback: check against base branch
    new_commits=$(git rev-list --count "origin/$base"..HEAD 2>/dev/null || echo "0")

    if [ "$new_commits" -gt 0 ]; then
      action=create
    else
      action=none
    fi
  fi
fi

# Execute action
case "$action" in
  create)
    cp "$PR_BODY_TEMPLATE" /tmp/pr-body.md

    git push -u origin "$head"
    gh pr create -B "$base" -H "$head" --title "..." --body-file /tmp/pr-body.md
    ;;
  push_only)
    echo "Existing unmerged PR found - pushing changes only"
    git push
    gh pr list --head "$head" --state open --json url -q '.[0].url'
    ;;
  none)
    echo "No action needed - no new changes since last merge"
    ;;
esac

References

${GH_PR_SKILL_DIR}/references/pr-body-template.md: PR body template

Maintainer

akiojin Core maintainer

Source details

Full Name: akiojin/skills
Branch: main
Path in repo: github/skills/gh-pr
License: MIT License

Featured Tools

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

akiojin/skills

inkjs-design

Ink.js (React for CLI) design and implementation guide. Use when: (1) Creating or modifying Ink.js components (2) Implementing Ink-specific hooks (useInput, useApp, useFocus) (3) Handling emoji/icon width issues (string-width workarounds) (4) Building terminal-responsive layouts (5) Managing multi-screen navigation (6) Implementing animations (spinners, progress bars) (7) Optimizing performance (React.memo, useMemo) (8) Handling keyboard input and shortcuts (9) Testing CLI UI (ink-testing-library)

5 2

Explore

akiojin/skills

speckit-require

GitHub Spec Kit (https://github.com/github/spec-kit) を使って要件定義や仕様作成（仕様策定・仕様書作成・仕様設計を含む）を新規作成または既存仕様へ追記し、spec.md/plan.md/tasks.mdまで生成・更新する。要件定義、要件追加/変更、TDD前提の要件整理、仕様の明文化、Spec Kitのspecify/clarify/plan/tasksフロー実行が求められるときに使用。

5 2

Explore

akiojin/skills

speckit-update

GitHub Spec Kit (https://github.com/github/spec-kit) のベースバージョン更新やテンプレート/スクリプト同期を行うための手順。Spec Kitの更新、上流リリースとの差分適用、templates/commands/scriptsの取り込み、ローカル運用（日本語化・ブランチ非操作・SPEC-[UUID8桁]）の維持が必要なときに使用する。

5 2

Explore

akiojin/skills

gh-fix-ci

Backward-compatible wrapper skill. The current workflow is `gh-fix-pr`.

5 2

Explore

akiojin/skills

gh-pr-check

Check GitHub PR status with the gh CLI, including unmerged PR detection and post-merge new-commit detection for the current branch.

5 2

Explore

akiojin/skills

gh-fix-issue

Analyze a GitHub Issue to extract error context, stack traces, file references, and cross-references. Classify the issue, search the codebase for relevant files, produce a structured Issue Analysis Report, and propose a concrete fix plan. Post progress updates to the issue.

5 2

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

SKILL.md

GH PR

Overview

Decision rules (must follow)

Post-merge commit check (critical)

Why this matters

PR title rules (must follow)

PR body rules (must follow)

Section classification

Validation (agent must check before creating PR)

Issue/PR Comment Formatting (must follow)

Issue Progress Comment Template (required for issue-based work)

Workflow (recommended)

Command snippets (bash)

References

Recommended Agent Skills

inkjs-design

speckit-require

speckit-update

gh-fix-ci

gh-pr-check

gh-fix-issue