| name | GitHub CLI Workflows |
| description | This skill should be used when the user asks to "use GitHub CLI", "use gh command", work with "pull requests", "create a PR", "merge pull request", "approve PR", "review PR comments", "check PR status", work with "issues", "triage issues", "list issues", "label issues", work with "GitHub Actions", "check CI status", "fix failing CI", "view workflow runs", "download workflow logs", "rerun workflow", or mentions "gh tool", "gh command", or GitHub automation tasks. Provides comprehensive guidance for autonomously creating and executing GitHub workflows using the official GitHub CLI. |
| version | 0.1.0 |
GitHub CLI Workflows
Purpose
Enable autonomous creation and execution of GitHub workflows using the official GitHub CLI (gh). This skill provides the knowledge and patterns needed to work with pull requests, issues, GitHub Actions, and the GitHub API through command-line operations.
Core Philosophy
Work autonomously within user-specified boundaries, respecting the current Claude Code mode (accept edits vs plan mode). Design multi-step workflows tailored to specific needs, handle errors intelligently, and always verify context before executing repository operations.
Prerequisites
Required Tools
GitHub CLI must be installed. Check with:
gh --version
If not installed, guide the user to https://cli.github.com/ for installation instructions (brew, apt, etc.).
Authentication Status
Do not proactively check authentication, but be prepared to recognize and diagnose authentication errors. When auth issues occur, guide the user to resolve them (see references/troubleshooting.md).
The Golden Rule: Use --help First
CRITICAL: Every gh command and subcommand supports --help to display comprehensive usage information, including:
- Available flags and options
- Argument formats
- Detailed examples
- Exit codes
- Related commands
When to use --help:
- Before constructing any complex command
- When uncertain about flag syntax
- When encountering errors (verify command structure)
- To discover available subcommands
- To check for new features or options
Examples:
gh --help
gh repo --help
gh repo create --help
gh pr create --help
gh api --help
Pattern: gh <command> <subcommand> --help works at every level. Always check help before guessing command syntax.
Repository Context
Before executing repo-specific commands, verify repository context:
gh repo view
This confirms:
- Current repository (owner/repo)
- Authentication works
- Proper permissions exist
When context is unclear, infer from the current directory unless explicitly specified otherwise. Use -R owner/repo flag to override when working across multiple repositories.
Core Capabilities
Pull Requests
Create, review, comment, merge, and manage pull requests programmatically.
Common operations:
- Create PR from current branch
- List open PRs with filters
- View PR details and checks
- Review and comment on PRs
- Merge PRs with various strategies
- Checkout PR branches locally
See references/pr-workflows.md for detailed patterns.
Issues
Triage, label, comment, and manage issues systematically.
Common operations:
- List new/open issues
- Create issues with templates
- Add/remove labels
- Comment and discuss
- Close with resolution notes
- Link to PRs
See references/issue-workflows.md for detailed patterns.
GitHub Actions
Monitor workflow runs, analyze failures, view logs, and trigger reruns.
Common operations:
- List workflow runs
- Check run status and conclusion
- Download and analyze logs
- Rerun failed workflows
- Cancel running workflows
- View workflow definitions
See references/actions-workflows.md for detailed patterns.
GitHub API
Execute custom operations not covered by core commands using gh api.
Common operations:
- GraphQL queries for complex data
- REST API operations
- Pagination handling with
--paginate
- JSON output parsing with
--jq
- Custom integrations
See references/api-usage.md for detailed patterns and examples.
Working with JSON Output
Many gh commands support --json for structured output and --jq for filtering.
When to use JSON:
- Parse results programmatically
- Extract specific fields
- Process multiple items
- Make decisions based on output
When to use human-readable:
- Show output directly to user
- Initial exploration
- Debugging
Pattern: Fetch with JSON, format for humans in responses:
gh pr list --json number,title,author,state
gh pr view 123 --json title,body --jq '.title'
Always show users formatted, readable output in responses, even when working with JSON internally.
Destructive Operations
Always ask user confirmation before executing operations that:
- Close issues or PRs
- Delete branches
- Merge pull requests
- Archive repositories
- Modify labels or milestones permanently
Offer dry-run option when available:
I can perform a dry-run first to show what would happen. Would you like me to:
1. Execute the operation now
2. Perform a dry-run and report the outcome
3. Show you the exact command to review first
Use --dry-run flags where supported (check --help for availability).
Error Handling Workflow
When a gh command fails, follow this sequence:
1. Review Command Output
Most errors have clear, actionable messages. Read the error carefully:
- Authentication required
- Permission denied
- Resource not found
- Invalid arguments
- Rate limit exceeded
2. Search Troubleshooting Documentation
Use grep/search tools to find relevant information in references/troubleshooting.md:
grep -i "authentication" references/troubleshooting.md
Avoid reading the entire troubleshooting file unless necessary.
3. Verify Command with --help
Check that command syntax matches the help documentation:
gh <command> <subcommand> --help
Common issues:
- Wrong flag names
- Missing required arguments
- Incorrect argument order
- Flag used with wrong command
4. Report to User
If the error persists after these steps, report detailed diagnostics:
- Exact command executed
- Complete error output
- Steps already attempted
- Relevant troubleshooting findings
- Suggested next actions
Ask for user guidance on how to proceed.
Autonomy and User Boundaries
Respect Current Mode
In accept-edits mode:
- Make changes directly
- Execute commands autonomously
- Commit and push as needed
In plan mode:
- Create detailed implementation plans
- Get user approval before execution
- Document each planned step
User-Specified Boundaries
Honor any constraints the user provides:
- Repository limits
- Branch protections
- Label conventions
- Review requirements
- Approval workflows
Workflow-Specific Autonomy
Fix Failing CI/CD:
View run → Download logs → Analyze errors → Suggest fixes → Implement → Push → (Rerun only if workflow won't auto-trigger)
Triage Issues:
Execute based on user-specified parameters (which labels to apply, what comments to add, etc.)
Implement PR Feedback:
Read comments → Make changes → Commit → Push (respecting current mode)
Create Pull Requests:
Verify branch → Push if needed → Create PR with description → Link issues (respecting current mode)
Be as autonomous as possible within established boundaries.
Common Patterns
For frequently-used patterns and workflows, see references/common-patterns.md:
- Authentication checks and recovery
- Multi-repository operations
- Batch processing issues/PRs
- CI/CD integration patterns
- Error recovery strategies
- Working with draft PRs
- Managing labels and milestones
- Using PR templates
Command Discovery
Discover available commands at any level:
gh --help
gh pr --help
gh issue --help
gh run --help
gh workflow --help
gh api --help
Each help page includes:
- Command descriptions
- Available subcommands
- Flags and options
- Usage examples
- Related commands
Output Visibility
Always show commands before execution so users understand what's running:
Checking repository context with:
$ gh repo view
Creating pull request with:
$ gh pr create --title "feat: Add user authentication" --body "..." --base main
This transparency helps users:
- Understand the workflow
- Learn
gh commands
- Verify correctness
- Reproduce manually if needed
Additional Resources
Reference Files
Detailed workflows and patterns are documented in references/:
references/pr-workflows.md - Pull request operations: create, review, merge, commentreferences/issue-workflows.md - Issue management: triage, label, comment, closereferences/actions-workflows.md - GitHub Actions: check runs, view logs, rerunreferences/api-usage.md - Direct API calls with gh api for custom operationsreferences/common-patterns.md - Reusable patterns: auth checks, error recovery, batch operationsreferences/troubleshooting.md - Common problems and solutions
Example Files
Real-world scenarios with expected outputs in examples/:
examples/fix-failing-ci.md - Complete workflow for diagnosing and fixing CI failuresexamples/triage-issues.md - Systematic issue triage with labeling and commentingexamples/pr-review-cycle.md - End-to-end PR creation, review, and merge process
Key Reminders
- Check
--help before guessing command syntax
- Verify repository context before repo-specific operations
- Ask confirmation for destructive operations
- Follow error handling workflow: output → troubleshooting → --help → report
- Respect user mode (accept-edits vs plan mode)
- Show commands before execution for transparency
- Format output for human readability in responses
- Be autonomous within user-specified boundaries
- Use JSON/jq for programmatic processing
- Reference detailed docs in references/ as needed
For comprehensive workflow details, consult the reference files. For working examples, see the examples directory. Always prioritize using --help to discover current command capabilities.
