github-cli

Original source / Raw SKILL.md

---
name: github-cli
description: GitHub CLI (gh) mastery for issues, PRs, Projects v2, and automation. Modern development workflow patterns for 2025.
version: 1.0.0
author: YG Starter AI Agent Hub
tags: [github, gh, cli, issues, pr, projects, automation, 2025]
---

# GitHub CLI Skill

## Overview

Master the GitHub CLI (`gh`) for comprehensive project management. This skill covers issue creation, PR workflows, Projects v2 integration, and automation patterns using modern best practices (December 2025).

**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)

```bash
# 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)

```bash
# 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

```bash
# 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

```bash
# 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 <[email protected]>
EOF
)" \
  --base main \
  --label "enhancement,backend,payment" \
  --reviewer @tech-lead
```

### PR Commit Message Format (Conventional Commits)

```bash
# 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:

```bash
# 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
| Label | Description | Color |
|-------|-------------|-------|
| `priority:critical` | Critical blocker, immediate attention | #d73a4a (Red) |
| `priority:high` | High priority, sprint critical | #ff9800 (Orange) |
| `priority:medium` | Medium priority | #ffeb3b (Yellow) |
| `priority:low` | Low priority, nice to have | #03a9f4 (Blue) |

### Domain Labels
| Label | Description | Color |
|-------|-------------|-------|
| `area:backend` | Backend (Python, FastAPI, PostgreSQL) | #0052cc (Blue) |
| `area:frontend` | Frontend (React, TypeScript, Vite) | #9c27b0 (Purple) |
| `area:database` | Database schema, migrations | #795548 (Brown) |
| `area:infrastructure` | DevOps, CI/CD, deployment | #607d8b (Blue Gray) |
| `area:api` | REST API, GraphQL | #00bcd4 (Cyan) |

### Type Labels
| Label | Description | Color |
|-------|-------------|-------|
| `type:feature` | New feature or enhancement | #a2eeef (Light Blue) |
| `type:bug` | Bug fix | #d73a4a (Red) |
| `type:refactor` | Code improvement, no behavior change | #fbca04 (Yellow) |
| `type:docs` | Documentation updates | #0075ca (Blue) |
| `type:test` | Test coverage improvements | #7057ff (Purple) |
| `type:security` | Security vulnerability or patch | #ee0701 (Dark Red) |

---

## Milestones Reference (Example SaaS App)

Example milestone structure for a SaaS application:

| Milestone | Due Date | Focus |
|-----------|----------|-------|
| v2.0 - Payment System | Q1 2026 | Stripe integration, subscriptions |
| v2.1 - User Management | Q2 2026 | SSO, RBAC, team management |
| v2.2 - Analytics Dashboard | Q2 2026 | Usage metrics, insights |
| v3.0 - Enterprise Features | Q3 2026 | Multi-tenancy, audit logs |
| v3.1 - Mobile App | Q4 2026 | iOS/Android native apps |

---

## 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