gh-issues_skill

Overview

This skill provides concise, practical guidance for managing GitHub Issues via the gh CLI, including creating, searching, bulk-editing, and integrating issue-based AI session context. It streamlines task workflows with label conventions, issue-to-PR patterns, and JSON/jq parsing for reliable automation. Use it to keep task state, hand off work, and resume progress with minimal friction.

How this skill works

The skill shows gh command patterns to create, view, edit, comment, and close issues, with examples that favor --json and --jq for machine-parsable output. It documents bulk operations (multi-arg edit/close and xargs pipelines), advanced search filters, and an issue-to-PR workflow that links commits and PRs back to issues. It also defines a simple AI-CONTEXT comment template and commands to read, create, and update context stored in issue comments.

When to use it

• Creating or updating issues from the CLI with labels, assignees, and body content
• Searching issues with date, label, assignee, or milestone filters and extracting IDs with --json/--jq
• Performing bulk edits or bulk-closing multiple issues in a single command
• Saving and loading AI session context into issue comments for handoff and resume
• Starting work on an issue, creating a branch tied to the issue, and following the issue-to-PR flow

Best practices

• Always use --json and --jq for parsing output to avoid brittle text scraping
• Use consistent labels (backlog, in-progress, blocked, review) to represent lifecycle state
• Update an existing AI-CONTEXT comment instead of appending duplicates to keep context authoritative
• Reference issue numbers in commits (e.g., commit message: fix: #123) so PRs auto-link and close issues
• Use multi-arg gh commands (gh issue edit 1 2 3) for efficient bulk operations instead of loops

Example use cases

• Start work: load AI context from an issue comment, add in-progress label, create branch with gh issue develop
• Pause and save work: write a .ai-context.md file and gh issue comment --body-file to persist session state
• Bulk tag triaged issues: gh issue list -l needs-triage --json number | jq -r '.[].number' | xargs gh issue edit --add-label reviewed
• Close issues from a release: gh issue close 10 15 20 -c 'Fixed in release v2.0'
• Search for recent activity: gh issue list --search "created:>=2026-01-01 created:<=2026-01-07" --json number,title