GitHub CLI Skill

Overview

Master the GitHub CLI (

gh

When to use:

• Creating/managing GitHub issues and PRs
• Working with GitHub Projects v2 custom fields
• Automating bulk operations with

  gh

• Following modern branch and PR conventions
• Running GraphQL queries for complex operations

Quick Reference

Essential Commands (2025)

# Issue operations
gh issue create --title "feat: Add payment processing" --body "..." --label "enhancement" --milestone "v2.0"
gh issue list --state open --label "backend" --assignee @me --limit 20
gh issue edit 123 --add-label "priority:high" --milestone "v2.1"
gh issue close 123 --comment "Fixed in #456"

# PR operations
gh pr create --title "feat: Add Stripe integration" --body "..." --base main --reviewer @teammate
gh pr checks 456 --watch              # Watch CI status live
gh pr merge 456 --squash --delete-branch
gh pr merge 456 --auto --squash       # Auto-merge when CI passes + approved
gh pr review 456 --approve --body "LGTM!"

# Project operations (Projects v2)
gh project list --owner @me
gh project item-add 1 --owner @me --url https://github.com/org/repo/issues/123
gh project field-list 1 --owner @me

# API operations
gh api repos/:owner/:repo/issues --jq '.[].title'
gh api graphql -f query='query { viewer { login }}'
gh api --method POST repos/:owner/:repo/dispatches -f event_type=deploy

JSON Output + jq Patterns (2025)

# Get issue numbers matching criteria
gh issue list --json number,labels --jq '[.[] | select(.labels[].name == "bug")] | .[].number'

# PR summary with checks
gh pr list --json number,title,author,statusCheckRollup --jq '.[] | "\(.number): \(.title) - \(.statusCheckRollup)"'

# Count open PRs by author
gh pr list --json author --jq 'group_by(.author.login) | map({author: .[0].author.login, count: length})'

# List stale issues (no activity in 30 days)
gh issue list --json number,title,updatedAt --jq 'map(select(.updatedAt < (now - 2592000 | strftime("%Y-%m-%dT%H:%M:%SZ")))) | .[] | .number'

Modern Workflow (2025)

Branch Naming Convention

# For GitHub issues
issue/<number>-<brief-description>
# Examples:
issue/372-stripe-integration
issue/385-user-authentication

# For features without issues
feature/<description>
# Example:
feature/dark-mode

# For bug fixes
fix/<issue-number>-<description>
# Example:
fix/401-payment-timeout

# For hotfixes
hotfix/<description>
# Example:
hotfix/critical-security-patch

Complete Feature Workflow

# 1. Create issue (if not exists)
ISSUE_URL=$(gh issue create \
  --title "feat: Add Stripe payment processing" \
  --body "$(cat <<'EOF'
## Description
Implement Stripe payment processing for subscription billing.

## Acceptance Criteria
- [ ] Stripe SDK integration
- [ ] Payment intent creation endpoint
- [ ] Webhook handling for payment events
- [ ] Database schema for transactions

## Technical Notes
- Use Stripe API v2025-01-01
- Implement idempotency keys
- Add retry logic for webhook failures
EOF
)" \
  --label "enhancement,backend,payment" \
  --milestone "Q1 2026 - Payment System" \
  --json url --jq '.url')

ISSUE_NUM=$(echo "$ISSUE_URL" | grep -o '[0-9]*$')

# 2. Create feature branch
git checkout main && git pull origin main
git checkout -b "issue/${ISSUE_NUM}-stripe-integration"

# 3. Do work, commit with conventional commits
git add . && git commit -m "feat(#${ISSUE_NUM}): Add Stripe payment processing with webhook support"

# 4. Push and create PR
git push -u origin "issue/${ISSUE_NUM}-stripe-integration"

gh pr create \
  --title "feat(#${ISSUE_NUM}): Add Stripe payment processing" \
  --body "$(cat <<'EOF'
## Summary
- Integrated Stripe SDK v14.x
- Added payment intent creation endpoint
- Implemented webhook handling for payment.succeeded
- Added transaction schema and models

## Test Plan
- [x] Unit tests for payment service (95% coverage)
- [x] Integration tests with Stripe test mode
- [x] Webhook event replay testing
- [ ] Manual testing in staging environment

## Security Considerations
- Webhook signature verification enabled
- API keys stored in environment variables
- PCI DSS compliance checklist followed

Closes #${ISSUE_NUM}

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)" \
  --base main \
  --label "enhancement,backend,payment" \
  --reviewer @tech-lead

PR Commit Message Format (Conventional Commits)

# Format: type(#issue): description
feat(#372): Implement Stripe payment integration
fix(#345): Resolve checkout page rendering bug
docs(#336): Update API documentation for v2.0
refactor(#391): Extract payment service into separate module
test(#342): Add 95% coverage for payment webhooks
chore(#376): Upgrade dependencies to December 2025 versions
perf(#401): Optimize database queries for user dashboard

Project Board Integration (Projects v2)

Modern development teams use GitHub Projects v2 with custom fields. After creating an issue:

# Add issue to project
ITEM_ID=$(gh project item-add 1 --owner your-org \
  --url "https://github.com/your-org/your-repo/issues/${ISSUE_NUM}" \
  --format json | jq -r '.id')

# Set Status to "In Development" (requires GraphQL)
# See templates/project-config-example.json for field IDs
gh api graphql -f query='
mutation {
  updateProjectV2ItemFieldValue(input: {
    projectId: "PROJECT_ID"
    itemId: "'$ITEM_ID'"
    fieldId: "STATUS_FIELD_ID"
    value: {singleSelectOptionId: "IN_PROGRESS_OPTION_ID"}
  }) {
    projectV2Item {
      id
    }
  }
}'

Note: Setting custom fields requires GraphQL. See

references/projects-v2.md

.

Labels Reference (Example SaaS App)

Priority Labels

priority:critical

priority:high

priority:medium

priority:low

Domain Labels

area:backend

area:frontend

area:database

area:infrastructure

area:api

Type Labels

type:feature

type:bug

type:refactor

type:docs

type:test

type:security

Milestones Reference (Example SaaS App)

Example milestone structure for a SaaS application:

Detailed Guides

For specific capabilities, see:

• Issue Management:

  references/issue-management.md

  • Bulk operations, templates, parent/sub-issues

• PR Workflows:

  references/pr-workflows.md

  • Review workflow, merge strategies, auto-merge

• Projects v2:

  references/projects-v2.md

  • Custom fields, GraphQL mutations, this project field IDs

• GraphQL API:

  references/graphql-api.md

  • Complex queries, pagination, bulk operations

• Automation Patterns:

  references/automation-patterns.md

  • Aliases, error handling, rate limits, scripts

Best Practices

1. Always use

   --json

   for scripting - Parse with

   --jq

   for reliability
2. Non-interactive mode for automation - Use

   --title

   ,

   --body

   flags
3. Check rate limits before bulk operations -

   gh api rate_limit

4. Use heredocs for multi-line content -

   --body "$(cat <<'EOF'...EOF)"

5. Link issues in PRs -

   Closes #123

   ,

   Fixes #456

6. Add verification checklists - Track test plan completion
7. Never commit to dev/main directly - Always use feature branches + PRs