Agent skill

gh-issues

Use when creating, searching, updating, or managing GitHub issues via CLI. Triggers: "issue", "create issue", "gh issue", "task tracking", "context", "handoff", "resume task", "session context", "save progress", "active tasks", "in-progress", "my tasks", "open issues". Covers: gh commands, bulk operations, JSON/jq, search filters, issue-to-PR workflow, AI session context storage, task workflow with labels.

View SKILL.md on GitHub Repository
Stars 136
Forks 14

Install this agent skill to your Project

npx add-skill https://github.com/serejaris/ris-claude-code/tree/main/skills/gh-issues

SKILL.md

GitHub Issues CLI

Efficient GitHub Issues management via gh CLI with AI session context storage.

Table of Contents

  1. Quick Reference
  2. JSON Output
  3. Search Filters
  4. Bulk Operations
  5. Issue to PR Workflow
  6. Milestones
  7. AI Session Context
  8. Task Workflow
  9. Examples
  10. Common Mistakes

Quick Reference

Task Command
Create issue gh issue create -t "Title" -b "Body" -l bug -a @me
Active tasks gh issue list -l in-progress -s open
List open bugs gh issue list -l bug -s open
View as JSON gh issue view 123 --json number,title,body,labels,state
Close with comment gh issue close 123 -c "Fixed in #456"
Edit labels gh issue edit 123 --add-label priority:high
Start work gh issue edit 45 --add-label in-progress
Create branch gh issue develop 123 --checkout
Load context gh issue view 45 --json comments --jq '.comments[] | select(.body | contains("AI-CONTEXT"))'

JSON Output Patterns

Always use --json for parsing. Fields: number, title, body, state, labels, assignees, milestone, author, createdAt, updatedAt, comments, url.

bash
gh issue view 123 --json number,title,labels,state
gh issue list --json number,title,labels --jq '.[] | select(.labels[].name == "bug")'
gh issue list -l bug --json number --jq '.[].number'

Advanced Search Filters

bash
gh issue list --search "is:open author:username"
gh issue list --search "created:>=2026-01-01 created:<=2026-01-07"
gh issue list --search "label:bug label:priority:high"
gh issue list --search "is:open -label:wontfix"
gh issue list --search "milestone:v2.0"

Bulk Operations

bash
gh issue edit 10 15 20 --add-label "priority:high"
gh issue close 10 15 20 -c "Duplicate of #5"
gh issue list -l needs-triage --json number --jq '.[].number' | \
  xargs -I{} gh issue edit {} --add-label reviewed

Issue to PR Workflow

bash
gh issue develop 123 --checkout          # Create branch from issue
git add . && git commit -m "fix: #123"   # Commit with reference
gh pr create --fill                       # Create PR (auto-links)
gh issue close 123 -c "Fixed in PR #456" # Close when merged

Milestones via API

bash
gh api repos/:owner/:repo/milestones --jq '.[].title'
gh issue edit 123 -m "v2.0"

AI Session Context

Store session context in GitHub issues for seamless task handoff.

Read Context

bash
# Get AI context from issue comments
gh issue view 45 --json comments --jq '
  .comments[] | select(.body | contains("AI-CONTEXT:START")) | .body
'

# Get comment ID for updates
gh issue view 45 --json comments --jq '
  .comments[] | select(.body | contains("AI-CONTEXT:START")) | .id
'

Save Context

bash
# Create new context comment
gh issue comment 45 --body-file .ai-context.md

# Update existing (replace COMMENT_ID)
gh api repos/:owner/:repo/issues/comments/COMMENT_ID \
  --method PATCH -f body="$(cat .ai-context.md)"

Context Template

See references/context-template.md for full template. Minimal version:

markdown
<!-- AI-CONTEXT:START -->
## Context | IN_PROGRESS
**Files:** `file.py:45`, `other.py:120`
**Done:** task1, task2
**Next:** next task
**Resume:** One-line summary for cold start
<!-- AI-CONTEXT:END -->

Workflow

  1. Start work — load context from issue
  2. Work on task — track progress mentally
  3. Pause/Stop — save context to issue comment
  4. Resume later — load context, continue

Task Workflow

Manage issue lifecycle with labels.

Labels

Label Meaning
backlog In queue
in-progress Active work
blocked Blocked
review Needs review

View Active Tasks

bash
# My active issues
gh issue list -l in-progress -s open

# All my assigned issues
gh issue list --assignee @me -s open

# Issues with context
gh issue list -s open --json number,title,labels --jq '
  .[] | select(.labels[].name == "in-progress") | "#\(.number): \(.title)"
'

Start Working

bash
# Mark as in-progress
gh issue edit 45 --add-label in-progress --remove-label backlog

# View issue + load context
gh issue view 45 --json number,title,body,comments --jq '{
  number, title, body,
  context: (.comments[] | select(.body | contains("AI-CONTEXT")) | .body) // "No context"
}'

Pause/Block

bash
# Mark as blocked
gh issue edit 45 --add-label blocked --remove-label in-progress

# Add blocking comment
gh issue comment 45 --body "Blocked: waiting for API access"

Complete

bash
# Close with comment
gh issue close 45 -c "Done in commit abc123"

# Or close via PR (auto-closes if PR body contains "Fixes #45")

Examples

Create Issue for Task

bash
gh issue create -t "Simplify bot flow" -b "## Problem
Bot stopped converting. Current flow is complex.

## Reference
Simple flow example from competitor.

## Tasks
- [ ] Analyze current flow
- [ ] Create new diagram
- [ ] Implement"

Start Working on Issue

bash
# 1. View issue with context
gh issue view 45 --json number,title,body,comments --jq '{
  number, title, body,
  context: (.comments[] | select(.body | contains("AI-CONTEXT")) | .body) // "No context"
}'

# 2. Create branch
gh issue develop 45 --checkout

# 3. Work...

Save Progress Before Stopping

bash
# Create context file
cat > .ai-context.md << 'EOF'
<!-- AI-CONTEXT:START -->
## AI Session Context
_Last updated: 2026-01-07 16:00_

### Status
**IN_PROGRESS**

### Progress
- [x] Analyzed current flow
- [ ] Create new diagram

### Key Files
- `handlers/start.py:45-78` — start handler
- `data/courses.yaml` — config

### Next Steps
1. Draw simplified flow
2. Implement changes

### Resume Context
Simplifying bot flow. Analyzed current state. Next: create diagram.
<!-- AI-CONTEXT:END -->
EOF

# Save to issue
gh issue comment 45 --body-file .ai-context.md

Resume Work

bash
# Load context
CONTEXT=$(gh issue view 45 --json comments --jq '
  .comments[] | select(.body | contains("AI-CONTEXT")) | .body
' 2>/dev/null)

echo "$CONTEXT"
# Continue from where you left off...

Common Mistakes

Mistake Fix
Missing --json Always --json field1,field2
Loop instead of multi-arg gh issue edit 1 2 3
Using grep on output Use --jq
Forgot -s all for closed Default is open only
{owner}/{repo} in API Use :owner/:repo
Duplicate context comments Update existing, don't create new

Didn't find tool you were looking for?

Be as detailed as possible for better results