gh_skill

Overview

This skill guides use of the GitHub CLI (gh) to manage pull requests, issues, releases, and automation from the terminal. It explains gh's mental model, primary commands, API access, and integration patterns with git and ork-like orchestration tools. Use this skill to translate common GitHub workflows into reliable, scriptable CLI operations.

How this skill works

The skill inspects user intent for gh-related tasks and maps that intent to three layers: high-level porcelain commands (gh pr, gh issue, gh repo, gh release), direct API access (gh api and graphql), and git integration (repo detection and branch context). It recommends loading the detailed reference for command syntax, workflow patterns, authentication, and advanced GraphQL use cases when needed.

When to use it

• User mentions gh commands, gh pr, gh issue, gh repo, or gh api
• Creating, viewing, checking out, reviewing, or merging pull requests from CLI
• Managing issues, labels, assignments, or triage via CLI
• Scripting automation, CI/CD flows, or batch operations that call GitHub APIs
• Setting up authentication, config, or multiple-account workflows
• Integrating gh with git worktrees, erk orchestration, or multi-repo tasks

Best practices

• Start with gh --version and gh auth status to confirm installation and auth
• Prefer porcelain commands for common workflows; use gh api/graphql when porcelain lacks functionality
• Use --json and --jq or --template to produce machine-friendly output for scripts
• Set defaults via gh config and use --repo explicitly in ambiguous multi-repo contexts
• Use GH_TOKEN in CI for non-interactive auth and check rate limits before bulk operations

Example use cases

• Daily PR workflow: gh pr create --fill, gh pr checkout 42, gh pr review --approve, gh pr merge
• Issue triage: gh issue list --label bug --assignee '@me' and gh issue edit 123 --add-label triage
• Release automation: gh release create v1.2.0 --target main --notes-file NOTES.md and gh release upload
• API scripting: gh api /repos/{owner}/{repo}/issues --jq '.[] | select(.state=="open")' for bulk processing
• Advanced queries: gh api graphql -f query='...' for Projects V2, discussions, or nested PR data