Git commit, PR creation, review, and merge skills following Conventional Commits

version
1.4.2
GitHub stars
72

Install

/plugin install github-workflow@dev-agent-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add fvadicamo/dev-agent-skills.

Contents

Discovered from source

Skills 4

Git commit

Creates git commits following Conventional Commits format.

Recent project commits

!git log --oneline -5 2>/dev/null

Quick start

# 1. Stage changes
git add <files>

# 2. Create commit
git commit -m "type(scope): subject"

Project conventions

  • Scope is required (kebab-case): validation, auth, cookie-service, api
  • Additional type beyond standard CC: security (vulnerability fixes or hardening)
  • HEREDOC for multi-line commits:
git commit -m "$(cat <<'EOF'
feat(validation): add URLValidator with domain whitelist

Implement URLValidator class supporting:
- Domain whitelist enforcement
- Dangerous scheme blocking

Addresses Requirement 31
Part of Task 5.1
EOF
)"

Important rules

  • ALWAYS check CLAUDE.md conventions first - use project format if it differs
  • ALWAYS include scope in parentheses
  • ALWAYS use present tense imperative verb for the subject
  • NEVER end subject with a period
  • NEVER exceed 50 chars in the subject line
  • NEVER use generic messages ("update code", "fix bug", "changes")
  • Group related changes into a single focused commit

References

  • references/commit_examples.md - Extended examples by type, good/bad comparisons

GitHub PR creation

Creates Pull Requests with task validation, test execution, and Conventional Commits formatting.

Current state

!git rev-parse --abbrev-ref HEAD 2>/dev/null !git log @{u}..HEAD --oneline 2>/dev/null || echo "(no upstream tracking)"

Core workflow

1. Confirm target branch

ALWAYS ask user before proceeding:

Creating PR from [current-branch] to [target-branch]. Correct?
Branch flowTypical target
feature/*develop
fix/*develop
hotfix/*main/master
developmain/master

2. Search for task documentation

Look for task/spec files that describe what this PR should accomplish. Common locations by tool:

Tool/ConventionPath
Spec2Ship (s2s).s2s/plans/*.md (look for active plan matching branch name or commits)
AWS Kiro.kiro/specs/*/tasks.md
Cursor.cursor/rules/*.md, .cursorrules
Trae.trae/rules/*.md
GitHub Issuesgh issue list --assignee @me --state open
Genericdocs/specs/, specs/, tasks.md, TODO.md

Extract task IDs, titles, descriptions, and requirements references when found.

3. Analyze commits

For each commit on this branch, identify type, scope, task references, and breaking changes. Map commits to documented tasks when task files exist.

4. Verify task completion

If task documentation exists:

  1. Identify main task from branch name (e.g., feature/task-2-* -> Task 2)
  2. Find all sub-tasks (e.g., Task 2.1, 2.2, 2.3)
  3. Check which sub-tasks are referenced in commits
  4. Report missing sub-tasks

If tasks incomplete, STOP and show status:

Task 2 INCOMPLETE: 1/3 sub-tasks missing
- Task 2.1: done
- Task 2.2: done
- Task 2.3: MISSING

Ask user whether to complete missing tasks or proceed anyway.

5. Run tests

Run the project test suite. Tests MUST pass before creating PR.

6. Determine PR type and generate title

Branch flowTitle prefix
feature/* -> developfeat(scope):
fix/* -> developfix(scope):
hotfix/* -> mainhotfix(scope):
develop -> mainrelease:
refactor/* -> developrefactor(scope):
chore/* -> developchore(scope):
ci/* -> developci(scope):
docs/* -> developdocs(scope):

Title format: <type>(<scope>): <description>

  • Type: dominant commit type from analysis (feat > fix > refactor > ci > chore)
  • Scope: most common scope from commits (kebab-case)
  • Description: imperative, lowercase, no period, max 50 chars

Breaking changes: if any commit contains BREAKING CHANGE: or ! after type:

  • Add breaking label if it exists in the project
  • Include a ## Breaking changes section in the PR body

7. Generate PR body

Use the appropriate template from references/pr_templates.md based on PR type and populate with gathered data.

8. Suggest labels

ALWAYS check available labels first:

gh label list

Match commit types to available project labels. The project may use different names than standard (e.g., "feature" instead of "enhancement").

Commit typeCommon label names
featfeature, enhancement
fixbug, bugfix
refactorrefactoring, tech-debt
docsdocumentation
cici/cd, infrastructure
securitysecurity
hotfixurgent, priority:high

If no matching label exists: suggest creating one. The user may have removed default labels, so offering to add relevant ones is appropriate.

9. Determine milestone

Check for open milestones:

gh api repos/$(gh repo view --json nameWithOwner -q '.nameWithOwner')/milestones \
  --jq '.[] | select(.state == "open") | "\(.number): \(.title)"'
  • If one active milestone exists: assign the PR to it (all work in progress belongs to the next release)
  • If multiple milestones exist: ask the user which one applies
  • If no milestones exist: skip (do not create one automatically)

10. Create PR

ALWAYS show title, body, labels, and milestone for user approval first.

gh pr create \
  --title "[title]" \
  --body "$(cat <<'EOF'
[body content]
EOF
)" \
  --base [base_branch] \
  --label "[label1]" --label "[label2]" \
  --milestone "[milestone-title]" \
  --reviewer "[username]"          # if teammates are known

Use --draft if the PR is not ready for merge review yet (work in progress, awaiting CI, or created only to trigger AI bot review on the branch).

Important rules

  • ALWAYS confirm target branch with user
  • ALWAYS run tests before creating PR
  • ALWAYS show PR content for approval before creating
  • ALWAYS check available labels with gh label list before suggesting
  • ALWAYS use HEREDOC for body to preserve formatting
  • ALWAYS add --label for each label separately (not comma-separated in one string)
  • ALWAYS check for open milestones and assign if one is active
  • NEVER create PR without user confirmation
  • NEVER modify repository files (read-only analysis)
  • NEVER create a milestone automatically - only assign existing ones
  • Use --draft for PRs not ready for merge review
  • Use --reviewer when teammates are known from team config or CODEOWNERS

References

  • references/pr_templates.md - PR body templates for all types (feature, release, bugfix, hotfix, refactoring, docs, CI/CD)

GitHub PR merge

Merges Pull Requests after validating pre-merge checklist and handling post-merge cleanup.

Current PR

!gh pr view --json number,title,state -q '"PR #\(.number): \(.title) (\(.state))"' 2>/dev/null

Core workflow

1. Check comments status

Verify all review comments have at least one reply:

REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
PR=$(gh pr view --json number -q '.number')

# Find unreplied comment IDs
gh api repos/$REPO/pulls/$PR/comments --jq '
  [.[] | select(.in_reply_to_id) | .in_reply_to_id] as $replied |
  [.[] | select(.in_reply_to_id == null) | select(.id | IN($replied[]) | not) | .id]
'

If unreplied comments exist:

  • STOP the merge process
  • Inform user: "Found unreplied comments: [IDs]. Run github-pr-review first."
  • NEVER reply to comments from this skill

2. Check milestone

gh pr view $PR --json milestone -q '.milestone.title // "none"'
  • If milestone is assigned: include it in the checklist summary (step 5)
  • If no milestone: check for open milestones and warn the user
gh api repos/$REPO/milestones --jq '[.[] | select(.state=="open")] | length'

If open milestones exist but the PR has none, surface a warning in the checklist: - Milestone: ⚠ not assigned (open milestones exist)

Do NOT block the merge for a missing milestone. It is a warning only.

3. Run validation

Run tests, linting, and verify CI checks. All MUST pass before proceeding.

gh pr checks $PR

4. Verify changelog completeness

Skip if the repo has no CHANGELOG.md. Otherwise make sure every commit this merge will publish is reflected in the changelog, so a release-promotion merge (develop → main) never leaves commits unlogged.

List the commits this PR brings into the base, and the changelog lines it adds:

BASE=$(gh pr view $PR --json baseRefName -q .baseRefName)
HEAD=$(gh pr view $PR --json headRefName -q .headRefName)
git log --oneline origin/$BASE..origin/$HEAD
git diff origin/$BASE...origin/$HEAD -- CHANGELOG.md
  • Every commit that changes shipped behavior (feat/fix/perf, behavior-affecting refactor) MUST have a matching changelog line; pure chore/docs/test commits that do not change shipped behavior may be omitted.
  • For a release-promotion merge, also confirm the version was bumped (the top ## [x.y.z] entry is new) and matches the manifest version(s).
  • If any behavior-changing commit is missing from the changelog: STOP. Report the unlogged commits and ask the user to update the changelog and version before merging. NEVER edit the changelog from this skill.

5. Confirm with user

ALWAYS show checklist summary and ask before merging:

Pre-merge checklist:
- Comments: all replied
- Tests: passing
- Lint: passing
- CI: green
- Milestone: v0.1.0 (or ⚠ not assigned)
- Changelog: complete (or n/a)

Ready to merge PR #X. Proceed?

6. Execute merge

First determine the merge direction. It decides whether the head branch may be deleted:

gh pr view $PR --json baseRefName,headRefName -q '"\(.headRefName) -> \(.baseRefName)"'

Branch deletion rule:

  • Topic branch → develop (head is a feature/fix/etc. branch): the branch is spent. Propose deleting it and merge with --delete-branch.
  • develop → main (or any long-lived branch as head): NEVER delete the head branch. develop and main are permanent. Omit --delete-branch and do not propose deletion.
# Add --delete-branch ONLY for a topic branch merging into develop.
gh pr merge $PR --merge --delete-branch --body "$(cat <<'EOF'
- Key change 1
- Key change 2
- Key change 3

Reviews: N/N addressed
Tests: X passed (Y% cov)
Refs: Task N, Req M
EOF
)"

For a develop → main merge, run the same command without --delete-branch.

Merge strategy: always --merge (merge commit), never squash or rebase.

7. Post-merge cleanup

Sync the branch that received the merge (the PR base), not always develop:

BASE=$(gh pr view $PR --json baseRefName -q .baseRefName)
git checkout "$BASE" && git pull origin "$BASE"

8. Check milestone completion

If the PR had a milestone, check whether all items are now closed:

MILESTONE=$(gh pr view $PR --json milestone -q '.milestone.number // empty')
if [ -n "$MILESTONE" ]; then
  gh api repos/$REPO/milestones/$MILESTONE \
    --jq '"Open: \(.open_issues) | Closed: \(.closed_issues) | \(.title)"'
fi
  • If open_issues == 0: inform the user and ask whether to close the milestone
gh api repos/$REPO/milestones/$MILESTONE --method PATCH --field state="closed"
  • If open_issues > 0: report remaining open items count. No action needed.
  • NEVER close a milestone automatically without explicit user confirmation.

Merge message format

Concise format for a clean git log:

- Key change 1 (what was added/fixed)
- Key change 2
- Key change 3

Reviews: 7/7 addressed (Gemini 5, Codex 2)
Tests: 628 passed (88% cov)
Refs: Task 8, Req 14-15
  • 3-5 bullet points max for changes
  • One line each for reviews summary, test results, and task references
  • No headers (##), no verbose sections
  • Total: ~10 lines max

Important rules

  • ALWAYS run tests, lint, and CI checks before merging
  • ALWAYS verify all review comments have replies
  • ALWAYS check milestone assignment before merging (warn if missing, do not block)
  • ALWAYS (repos with a CHANGELOG) verify it accounts for every behavior-changing commit this merge publishes; STOP and report any that are missing
  • ALWAYS confirm with user before executing merge
  • ALWAYS use merge commit (--merge), never squash/rebase
  • ALWAYS delete the head branch only when merging a topic branch (feature/fix/etc.) into develop
  • NEVER delete develop or main. On a develop → main merge, omit --delete-branch and never propose deletion
  • ALWAYS check milestone completion after merge and report open items count
  • NEVER merge with failing tests, lint, or CI checks
  • NEVER skip user confirmation
  • NEVER close a milestone without explicit user confirmation
  • NEVER reply to PR comments from this skill - use github-pr-review instead
  • STOP merge if unreplied comments exist and direct user to review skill

GitHub PR review

Resolves Pull Request review comments with severity-based prioritization, fix application, and thread replies.

Current PR

!gh pr view --json number,title,state,milestone -q '"PR #\(.number): \(.title) (\(.state)) | Milestone: \(.milestone.title // "none")"' 2>/dev/null

Core workflow

1. Fetch, filter, and classify comments

REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
PR=$(gh pr view --json number -q '.number')
LAST_PUSH=$(git log -1 --format=%cI HEAD)

# Inline review comments - filter out replies (keep only originals)
gh api repos/$REPO/pulls/$PR/comments?per_page=100 --jq '
  [.[] | select(.in_reply_to_id == null) |
   {id, path, user: .user.login, created_at, body: .body[0:200]}]
'

# PR-level reviews with non-empty body (CodeRabbit sections, Gemini, etc.)
gh api repos/$REPO/pulls/$PR/reviews?per_page=100 --jq '
  [.[] | select(.body | length > 0) |
   {id, user: .user.login, state, submitted_at, body: .body[0:500]}]
'

Cross-check review-attached comments: CodeRabbit's review body states "Actionable comments posted: N". If the general pulls/$PR/comments endpoint returns fewer than N new originals from that reviewer, some comments are only available via the review-specific endpoint. Fetch them and merge by comment ID:

# $REVIEW_ID from the reviews fetch above; $EXPECTED from parsing "Actionable comments posted: N"
gh api repos/$REPO/pulls/$PR/reviews/$REVIEW_ID/comments?per_page=100 --jq '
  [.[] | select(.in_reply_to_id == null) |
   {id, path, user: .user.login, created_at, body: .body[0:200]}]
'

Deduplicate by id before continuing. Comments found only via the review-specific endpoint are valid inline comments and should be treated identically (same classification, same in_reply_to reply mechanism).

Filter new vs already-seen: compare created_at/submitted_at with $LAST_PUSH. Comments posted after the last push are new. Mark older comments as "previous round" in the summary table.

Parse CodeRabbit review bodies: the initial fetch truncates bodies for classification. For reviews from CodeRabbit (user.login starts with coderabbitai), fetch the full body separately:

gh api repos/$REPO/pulls/$PR/reviews?per_page=100 --jq '
  [.[] | select(.user.login | startswith("coderabbitai")) |
   {id, submitted_at, body}]
'

CodeRabbit posts structured <details> blocks containing outside-diff, duplicate, and nitpick comments. Each block includes file path, line range, severity, and optionally a "Prompt for AI Agents" with pre-built context. See references/coderabbit_parsing.md for full parsing guide.

Use CodeRabbit AI prompts when available: if a comment (or the review body) contains a "Prompt for AI Agents" <details> block, use it to understand the issue and suggested approach. Always read the actual code before proposing a fix. If the review body contains a "Prompt for all review comments with AI agents" block, read it first for cross-comment context before processing individual comments.

Classify all comments by severity and process in order: CRITICAL > HIGH > MEDIUM > LOW.

SeverityIndicatorsAction
CRITICALcritical.svg, _🔒 Security_, _🚨 Critical_, _🔴 Critical_, "security", "vulnerability"Must fix
HIGHhigh-priority.svg, _⚠️ Potential issue_, _🐛 Bug_, _⚡ Performance_, _🟠 Major_, "High Severity"Should fix
MEDIUMmedium-priority.svg, _🛠️ Refactor suggestion_, _💡 Suggestion_, "Medium Severity"Recommended
LOWlow-priority.svg, _🧹 Nitpick_, _🔧 Optional_, _🟡 Minor_, _🔵 Trivial_, _⚪ Info_, "style", "nit"Optional

When a comment has both a type label and a secondary color badge (e.g., _💡 Suggestion_ | _🟠 Major_), the color badge is the binding severity and overrides the type-based default.

See references/severity_guide.md for full detection patterns (Gemini badges, CodeRabbit emoji, Cursor comments, keyword fallback, related comments heuristics).

2. Show review summary table

Before processing, display a structured overview of all comments:

| # | ID         | Severity | File:Line          | Type     | Status   | Summary            |
|---|------------|----------|--------------------|----------|----------|--------------------|
| 1 | 123456789  | CRITICAL | src/auth.py:45     | inline   | new      | SQL injection risk |
| 2 | 987654321  | HIGH     | src/db.py:346-350  | outside  | new      | Missing join cond  |
| 3 | 555555555  | HIGH     | src/chunk.py:188   | duplicate| previous | Stale metadata     |
| 4 | 444444444  | LOW      | tests/test_q.py:12 | nitpick  | previous | Naming convention  |
  • Type: inline, outside (outside diff), duplicate, minor, nitpick (from CodeRabbit sections), or review (generic PR-level)
  • Status: new (posted after last push) or previous (from earlier rounds)
  • Group related comments (same file, same root cause, "also applies to" ranges) and note clusters
  • Deduplicate: if the same issue appears both as an inline comment and in a CodeRabbit review body section (e.g., duplicate), keep one entry and note both sources

If there are more than 10 comments, suggest saving a review summary to Claude's memory for tracking across sessions. The summary should include: PR number, comment IDs, severity, status (new/addressed/deferred/won't fix), and brief description. This helps maintain continuity when new comments arrive after subsequent pushes.

3. Process each comment

For each comment, in severity order:

  1. Show context: comment ID, severity, file:line, quote
  2. Check for AI prompt: if CodeRabbit "Prompt for AI Agents" is available for this comment, use it to understand the issue and suggested approach
  3. Check for proposed fix: if CodeRabbit includes a "Proposed fix" or "Suggested fix" code block, use it as a starting point (but verify correctness)
  4. Read affected code and propose fix (always read the actual code, even when an AI prompt or proposed fix provides context)
  5. Handle "also applies to": if the comment references additional line ranges, include all locations in the fix
  6. Confirm with user before applying
  7. Apply fix if approved
  8. Verify ALL issues in the comment are addressed (multi-issue comments are common)

4. Commit changes

Use git-commit skill format. Functional fixes get separate commits, cosmetic fixes are batched:

Change typeStrategy
Functional (CRITICAL/HIGH)Separate commit per fix
Cosmetic (MEDIUM/LOW)Single batch style: commit

Reference the comment ID in the commit body.

5. Reply to threads

Inline comments

Important: use --input - with JSON. The -f in_reply_to=... syntax does NOT work.

COMMIT=$(git rev-parse --short HEAD)
gh api repos/$REPO/pulls/$PR/comments \
  --input - <<< '{"body": "Fixed in '"$COMMIT"'. Brief explanation.", "in_reply_to": 123456789}'
Non-inline comments (CodeRabbit review body)

Comments embedded in the review body (outside diff, duplicate, nitpick) do not have inline threads. The GitHub API does not support replying to a review body directly. Post a general PR comment referencing the specific issue:

gh pr comment $PR --body "Fixed in $COMMIT. Addresses outside-diff comment on file/path.py:346-350."

Reply templates (no emojis, minimal and professional):

SituationTemplate
FixedFixed in [hash]. [brief description of fix]
Won't fixWon't fix: [reason]
By designBy design: [explanation]
DeferredDeferred to [issue/task]. Will address in future iteration.
AcknowledgedAcknowledged. [brief note]

6. Run tests and push

Run the project test suite. All tests must pass before pushing. Push all fixes together to minimize review loops.

7. Submit review (optional)

After addressing all comments, formally submit a review:

  • gh pr review $PR --approve --body "..." - all comments addressed, PR is ready
  • gh pr review $PR --request-changes --body "..." - critical issues remain
  • gh pr review $PR --comment --body "..." - progress update, no decision yet

8. Verify milestone

gh pr view $PR --json milestone -q '.milestone.title // "none"'

If the PR has no milestone, check for open milestones:

REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
gh api repos/$REPO/milestones --jq '[.[] | select(.state=="open")] | .[] | "\(.number): \(.title)"'

If open milestones exist, inform the user and suggest assigning:

gh pr edit $PR --milestone "[milestone-title]"

Do not assign automatically. This is a reminder only.

Avoiding review loops

When bots (Gemini, Codex, etc.) review every push:

  1. Batch fixes: accumulate all fixes, push once
  2. Draft PR: convert to draft during fixes
  3. Commit keywords: some bots respect [skip ci] or [skip review]

Important rules

  • ALWAYS fetch both inline comments (pulls/$PR/comments) and review bodies (pulls/$PR/reviews)
  • ALWAYS cross-check "Actionable comments posted: N" against found originals; fetch pulls/$PR/reviews/$REVIEW_ID/comments when count mismatches
  • ALWAYS parse CodeRabbit review bodies for all section types (outside diff, duplicate, minor, nitpick)
  • ALWAYS use CodeRabbit "Prompt for AI Agents" as primary context when available
  • ALWAYS show the review summary table before processing
  • ALWAYS confirm before modifying files
  • ALWAYS verify ALL issues in multi-issue comments are fixed, including "also applies to" ranges
  • ALWAYS run tests before pushing
  • ALWAYS reply to resolved threads using standard templates
  • ALWAYS submit formal review (gh pr review) after addressing all comments
  • ALWAYS check milestone at the end and remind if missing
  • ALWAYS suggest saving a review summary to memory when there are more than 10 comments
  • NEVER use emojis in commit messages or thread replies
  • NEVER skip HIGH/CRITICAL comments without explicit user approval
  • NEVER assign milestone automatically - suggest only
  • Functional fixes -> separate commits (one per fix)
  • Cosmetic fixes -> batch into single style: commit
  • Duplicate comments -> treat as higher priority than their label (issue was already flagged before)
  • Related comments -> group and fix together when they share root cause or file context

References

  • references/severity_guide.md - Severity detection patterns (Gemini badges, CodeRabbit emoji, Cursor comments, keyword fallback, related comments heuristics)
  • references/coderabbit_parsing.md - CodeRabbit review body structure, section parsing, "Prompt for AI Agents" usage, duplicate and "also applies to" handling

Sponsors

Details

Marketplace
fvadicamo/dev-agent-skills
Source
plugins/github-workflow
Category
Community

More from fvadicamo/dev-agent-skills

All 5