issue-reader

name	issue-reader
description	Retrieve GitHub issue information using the GitHub CLI (gh). USE FOR: viewing a specific issue by number, searching issues by topic or keyword, listing open/closed issues, and summarizing issue details. DO NOT USE FOR: creating issues (use issue-writer), commenting on issues, or closing issues.
compatibility	Requires GitHub CLI (gh) authenticated to the target repository. Works on Windows (PowerShell), macOS, and Linux (bash/zsh).

Issue Reader — Retrieve GitHub Issue Information via GitHub CLI

Trigger On

• user asks to look up, find, or show a GitHub issue
• user provides an issue number and wants its details
• user describes a topic and wants to search for matching issues
• user asks to list open or closed issues
• user wants a summary of what a specific issue is about

Prerequisites

Verify gh is available and authenticated:

gh auth status

If not authenticated, instruct the user to run:

gh auth login

Determine the Repository

Always use the repository of the current workspace. Detect it automatically from the Git remote before running any gh command and store it for reuse:

git remote get-url origin

If the command exits with a non-zero code or returns no output, stop and tell the user: "No Git remote named origin was found in this workspace. Please run this skill from inside the repository you want to query."

Do not ask the user to provide or override the repository. All gh commands in this skill must use the detected owner/repo via --repo owner/repo so they always target the current workspace repository regardless of the shell's working directory.

---

Workflow

1. Identify the retrieval mode

Determine what the user wants based on their input:

User provides	Mode
An issue number (e.g., #42 or 42)	View by number
A keyword, topic, or description	Search by topic
No specific issue — wants an overview	List issues

---

2a. View a specific issue by number

Fetch the full details of a single issue:

gh issue view 42 --repo owner/repo

To get machine-readable JSON (useful for further processing):

gh issue view 42 --repo owner/repo --json number,title,body,state,labels,assignees,milestone,createdAt,updatedAt,url

Show the issue in the browser:

gh issue view 42 --repo owner/repo --web

Output summary to present to the user:

Field	Description
number	Issue number
title	Issue title
state	OPEN or CLOSED
labels	Assigned labels
assignees	Assigned users
milestone	Associated milestone
body	Full issue description
url	Direct link

---

2b. Search for issues by topic or keyword

Use --search to filter issues by keyword, label, assignee, or state. The search query supports GitHub search syntax. All commands target the current workspace repository.

Search by keyword:

gh issue list --repo owner/repo --search "<keyword>"

Search open issues only (default):

gh issue list --repo owner/repo --state open --search "<keyword>"

Search closed issues:

gh issue list --repo owner/repo --state closed --search "<keyword>"

Search by label:

gh issue list --repo owner/repo --label "bug" --search "<keyword>"

Limit results (default is 30):

gh issue list --repo owner/repo --search "<keyword>" --limit 10

Output as JSON for structured processing:

gh issue list --repo owner/repo --search "<keyword>" \
  --json number,title,state,labels,assignees,url

---

2c. List issues (no specific search term)

All commands target the current workspace repository.

All open issues:

gh issue list --repo owner/repo

All issues (open and closed):

gh issue list --repo owner/repo --state all

Issues assigned to a specific user:

gh issue list --repo owner/repo --assignee "username"

Issues with a specific label:

gh issue list --repo owner/repo --label "enhancement"

Issues for a specific milestone:

gh issue list --repo owner/repo --milestone "v1.0"

---

3. Present results to the user

For a single issue (view mode): Present the key fields in a readable summary. Include the direct URL at the end.

For a list or search result: Present as a markdown table with columns: #, Title, State, Labels, URL. Limit to the most relevant results. If the list is long, ask the user if they want to narrow the search.

---

Useful Field Reference for JSON Output

When using --json, available fields include:

Field	Type	Description
number	int	Issue number
title	string	Issue title
body	string	Issue description (markdown)
state	string	OPEN or CLOSED
labels	array	Label names
assignees	array	GitHub usernames
milestone	object	Milestone title and due date
author	object	Issue author login
comments	array	Issue comments
createdAt	string	ISO 8601 creation date
updatedAt	string	ISO 8601 last update date
closedAt	string	ISO 8601 close date (if closed)
url	string	HTML URL of the issue

---

Error Handling

Error	Fix
gh: command not found	Install GitHub CLI: https://cli.github.com
You are not logged into any GitHub hosts	Run gh auth login
Could not resolve to an issue	Verify the issue number exists; run gh issue list to confirm
Repository not found	Ask the user to verify the owner/repo slug and re-run with --repo "<corrected-owner/repo>"
Permission denied	Ensure the authenticated user has read access to the repository
No results from --search	Broaden the query, remove filters, or try --state all