name: github-issue description: Use `a gh issue-agent` to view, create, and edit GitHub Issues. Use this skill when working with GitHub Issues - viewing issue content, creating new issues, editing issue body/title/labels, or adding/editing comments. IMPORTANT - This skill MUST be used instead of running `gh issue create`, `gh issue edit`, or `gh issue comment` directly. Any GitHub Issue operation (create, view, edit, comment) must go through this skill.

GitHub Issue Management

Use a gh issue-agent to manage GitHub Issues as local files. This provides better diff visibility and safer editing compared to direct gh issue commands.

When to Use

Use this skill when:

Viewing GitHub Issue content (body, comments, metadata, timeline events)
Creating new GitHub Issues
Editing Issue body, title, or labels
Adding or editing comments on Issues

Commands

View (read-only)

a gh issue-agent view <issue-number> [-R <owner/repo>]

Use this when you only need to read the issue content. No local cache is created.

The view command displays:

Issue body and metadata
Comments
Timeline events (label changes, assignments, cross-references from other issues/PRs)

When to use view vs pull:

view: Just reading/viewing the issue (no editing needed)
pull: When you plan to edit the issue body, metadata, or comments

Pull (fetch issue locally)

a gh issue-agent pull <issue-number> [-R <owner/repo>]

This saves the issue to ~/.cache/gh-issue-agent/<owner>/<repo>/<issue-number>/:

issue.md - Issue body (editable)
metadata.json - Title, labels, assignees, sub-issues, parent issue (editable)
comments/ - Comment files (only your own comments are editable)

Sub-issues are automatically fetched via the GitHub Sub-issues REST API during pull.

Note: Fails if local changes exist. Use pull --force to discard and re-fetch.

Init (create boilerplate)

# Create new issue boilerplate
a gh issue-agent init issue [-R <owner/repo>]

# Use a specific issue template
a gh issue-agent init issue --template <template-name>

# List available issue templates
a gh issue-agent init issue --list-templates

# Skip templates and use default boilerplate
a gh issue-agent init issue --no-template

# Create new comment boilerplate for an existing issue
a gh issue-agent init comment <issue-number> [--name <name>] [-R <owner/repo>]

Issue template behavior:

If the repository has issue templates in .github/ISSUE_TEMPLATE/, they are automatically fetched
If only one template exists, it is auto-selected
If multiple templates exist, you must choose with --template <name> or --no-template
Use --list-templates to see available templates

The init issue command creates a boilerplate file at ~/.cache/gh-issue-agent/<owner>/<repo>/new/issue.md:

---
title: ''
labels: []
assignees: []
# parentIssue: owner/repo#1
# subIssues:
#   - owner/repo#2
---

Body

parentIssue / subIssues are commented out by default; uncomment and fill them to link the new issue on creation. See "Sub-issues and Parent Issue" below for details.

Review (approve before push)

a gh issue-agent review <file-path>

Opens a file in an editor (via tmux) for user review. The user must set submit: true in the frontmatter to approve. For files without YAML frontmatter (e.g., comment files with HTML comment metadata), a temporary submit: false frontmatter is prepended and stripped after review.

Run this in background (run_in_background: true). The command blocks until the user closes the editor. Exit code 0 means approved, exit code 1 means not approved (user closed without approving), exit code 2 means the editor is already open for this file.

The push command verifies .approve files exist for all changed files and rejects the push if any file is unapproved.

Diff (show changes)

a gh issue-agent diff <issue-number> [-R <owner/repo>]

Shows colored diff between local changes and remote state. Useful for reviewing changes before pushing.

Push (apply changes to GitHub)

# Update existing issue
a gh issue-agent push <issue-number>

# Create new issue (pass path instead of number)
a gh issue-agent push <path-to-new-issue-dir>

# Preview changes without applying
a gh issue-agent push <issue-number> --dry-run

# Force overwrite if remote has changed since pull
a gh issue-agent push <issue-number> --force

# Edit other users' comments
a gh issue-agent push <issue-number> --edit-others

# Allow deleting comments from GitHub
a gh issue-agent push <issue-number> --allow-delete

Sub-issues and Parent Issue

a gh issue-agent supports managing GitHub Sub-issues via the Sub-issues API. Sub-issues and parent issue relationships are expressed via frontmatter fields in issue.md.

Frontmatter fields

The keys are camelCase (NOT snake_case):

subIssues: array of issue references that are sub-issues of this issue
parentIssue: the parent issue reference if this issue is a sub-issue

Reference format: owner/repo#number (e.g., org/my-repo#42). Unknown frontmatter keys (e.g., parent_issue / sub_issues in snake_case, or typos like parentIssues) are rejected with an error on parse, so a typo will not silently lose the link.

Frontmatter lives in issue.md (YAML), not in metadata.json. A metadata.json file may also exist but is not the source of truth for these fields.

Example issue.md frontmatter with a parent issue:

---
title: Sub-task
labels: []
assignees: []
parentIssue: org/repo#5
---

Linking on creation

Both subIssues and parentIssue are honored when a gh issue-agent push <new-dir> creates a new issue. Add them directly to the init issue frontmatter:

---
title: Child Issue
labels: []
assignees: []
parentIssue: org/repo#1
subIssues:
    - org/repo#10
---

The issue is created first, then the Sub-issues API is called to apply the parent/child links in the same push. No separate "pull parent → add child → push" workaround is needed.

How it works

pull: Sub-issues are automatically fetched via REST API (GET /repos/{owner}/{repo}/issues/{number}/sub_issues). Parent issue is fetched via GraphQL (parent field).
push: Diffs are computed between local and remote state for subIssues / parentIssue. Changes are applied via the Sub-issues API:
- Adding a sub-issue: POST /repos/{owner}/{repo}/issues/{parent_number}/sub_issues with { "sub_issue_id": <id> }
- Removing a sub-issue: DELETE /repos/{owner}/{repo}/issues/{parent_number}/sub_issue with { "sub_issue_id": <id> }
- Changing parent issue: removes from old parent, adds to new parent (by manipulating the parent's sub-issue list)
The API uses internal issue IDs (not issue numbers). a gh issue-agent resolves issue numbers to IDs automatically via GET /repos/{owner}/{repo}/issues/{number}.

Verification

After pushing a parent/child link, verify it actually landed:

gh api "repos/<owner>/<repo>/issues/<parent-number>/sub_issues" --jq '.[] | {number, title, state}'

An empty result means the link was not created, even if push reported success.

Absolute Rules

These rules MUST NEVER be violated, regardless of context or convenience.

NEVER call a gh issue-agent push without first running a gh issue-agent review on every changed file and having the user approve each one (by setting submit: true in the frontmatter). The push command verifies .approve files exist for all changed files and will reject the push if any file is unapproved. No exceptions - not even when "continuing from a previous session", "the content was already reviewed", or "the changes are minor". If a gh issue-agent review was not run in the current conversation turn, the content has NOT been reviewed.
NEVER put flow information (investigation results, root cause analysis, data tables, timeline of events, action items, options/choices) in the issue body. The issue body is for static, structural content only: WHY (motivation, severity, risk) and WHAT (strategic intent, completion criteria). All flow information goes in comments.
NEVER push issue body changes and new comments in the same push command. Each must be reviewed (a gh issue-agent review with submit: true) and pushed separately. Edit the issue body first, get approval, push it, then create the comment, get approval, push it.
NEVER paraphrase, summarize, or edit external text provided by the user (e.g., support correspondence, Slack messages, email threads). Copy-paste the original text exactly as-is. The only acceptable changes are formatting adjustments for Markdown rendering (e.g., adding > for quotes). If the user provides text to include in a comment, use it verbatim.
NEVER duplicate content that already exists in the issue's other comments. Before writing a new comment, read all existing comments and exclude any information already present. For example, if a support inquiry was already posted in an earlier comment, only include subsequent replies in the new comment.
NEVER change the structure or formatting that the user has established. If the user edits a file via a gh issue-agent review and establishes a particular structure (e.g., separate <details> blocks for different parties, specific heading styles), preserve that exact structure in subsequent edits. Do not reorganize, merge, or rename sections.
NEVER use the Write tool on files managed by a gh issue-agent. Always use the Edit tool instead. a gh issue-agent review prepends a submit: false frontmatter to files that lack one (e.g., comment files). The Write tool overwrites the entire file, destroying this frontmatter. If the review editor is already open (exit code 2), the frontmatter is gone and cannot be re-added by running review again. Use Edit to modify only the content portion, preserving any frontmatter that a gh issue-agent review has added.
NEVER stop or kill a running a gh issue-agent review (or a ai draft) background process. These commands open an editor for the user to review and approve content. They are supposed to block until the user closes the editor. "Editor is already open" (exit code 2) means the user is still reviewing — wait patiently. Do NOT interpret a blocking editor process as a stuck/locked process that needs to be killed.

Issue Body vs Comment Decision Guide

Before writing anything, classify each piece of information:

Content type	Where it belongs	Examples
Static/structural	Issue body	Why this issue exists, what the goal is, completion criteria, severity/urgency
Flow/temporal	Comment	Investigation results, root cause findings, data analysis, proposed options, progress updates, decisions made

The test: "Will this content change as work progresses?" If yes → comment. If no → issue body.

Bad: Issue body contains ## 原因 or ## 調査結果 or ## 対応方針の選択肢
Good: Issue body contains only WHY + WHAT. Investigation results posted as a separate comment

Workflow: First Analyze, Then Act

CRITICAL: When editing an existing issue, ALWAYS start with view to understand the current state before deciding what to do.

Step 1: Analyze with `view`

a gh issue-agent view <issue-number> [-R <owner/repo>]

Read the output carefully and identify:

What content exists in the issue body?
What comments already exist and what do they contain?
Based on user's request, determine the action:
- Add content to issue body → Edit existing issue workflow
- Add content to an existing comment → Edit existing comment workflow
- Add a completely new comment → Add new comment workflow

DO NOT skip this step. Without understanding the current state, you cannot make the correct decision.

Step 2: Choose the correct workflow

Based on Step 1 analysis:

Workflow A: Viewing only (no edits)

If user only wants to read the issue, the view command output is sufficient. No further action needed.

Workflow B: Creating a new issue

Phase 1: Gather information before writing

Before writing anything, complete all necessary research. The goal is to write a high-quality draft on the first attempt, minimizing review rounds.

Extract from the user's description:
- The priority/emphasis the user places on each topic (reflect this in section ordering)
- Issue numbers or URLs the user explicitly mentions as related
- Facts the user states without linking to specific issues (do not invent links for these)
Research external services/tools mentioned in the issue:
- If the issue references features of an external service (e.g., a SaaS plan's capabilities), fetch the official documentation BEFORE writing the draft
- Include specific feature names, API endpoints, or capability descriptions from the docs
Verify related issues:
- For issues the user explicitly mentioned: confirm they exist with gh issue view
- Do NOT proactively search for and add issue links the user did not mention. If you believe an issue is relevant, ask the user first rather than including it in the draft
- If you do add an issue link, you MUST read the issue body (via view) to confirm it is actually relevant. Never link based on title alone
Check repository conventions: use view on a similar existing issue to match formatting

Phase 2: Create and review

Check available templates: a gh issue-agent init issue --list-templates [-R <owner/repo>]
Generate boilerplate with appropriate template:
- If templates exist, use: a gh issue-agent init issue --template <template-name>
- If no templates or user prefers blank: a gh issue-agent init issue --no-template
- IMPORTANT: Never assume --no-template without checking templates first
Edit the file at ~/.cache/gh-issue-agent/<owner>/<repo>/new/issue.md
Run a gh issue-agent review <file-path> in background (run_in_background: true) to open in terminal + Neovim for user review. This command blocks until the user closes the editor, so it will complete when the user finishes reviewing.
STOP and wait for the background command to complete. Do NOT proceed to push until the command finishes. When it completes, check the exit code: exit code 0 means the user approved the draft (set submit: true in frontmatter), exit code 1 means the user did not approve (closed without approving), exit code 2 means the editor is already open. If not approved, ask the user what to change. If already open (exit code 2), inform the user that the editor is already open and they can reload the file in their editor (e.g., :e in Neovim). Do NOT retry the command.
Create the issue: a gh issue-agent push ~/.cache/gh-issue-agent/<owner>/<repo>/new (the push command verifies .approve files exist for all changed files)
- On success, the directory is renamed to <issue-number>/

Workflow C: Editing issue body/metadata

Pull the issue: a gh issue-agent pull <issue-number>
Edit issue.md or metadata.json in ~/.cache/gh-issue-agent/<owner>/<repo>/<issue-number>/
Run a gh issue-agent review <file-path> in background (run_in_background: true) to open the edited file in terminal + Neovim for user review. This command blocks until the user closes the editor.
STOP and wait for the background command to complete. Do NOT proceed to push until the command finishes. When it completes, check the exit code: exit code 0 means the user approved, exit code 1 means not approved, exit code 2 means the editor is already open. If not approved, ask the user what to change. If already open (exit code 2), inform the user that the editor is already open and they can reload the file in their editor (e.g., :e in Neovim). Do NOT retry the command.
Apply changes: a gh issue-agent push <issue-number> (the push command verifies .approve files exist for all changed files)

Workflow D: Editing an EXISTING comment

Use this when the content should be added to or modified in an existing comment.

Pull the issue: a gh issue-agent pull <issue-number>
List comments: ls ~/.cache/gh-issue-agent/<owner>/<repo>/<issue-number>/comments/
Read the target comment file (identified from Step 1 analysis)
Edit the comment file directly
Run a gh issue-agent review <file-path> in background (run_in_background: true) for user review. This command blocks until the user closes the editor.
STOP and wait for the background command to complete. Do NOT proceed to push until the command finishes. When it completes, check the exit code: exit code 0 means approved, exit code 1 means not approved, exit code 2 means the editor is already open. If not approved, ask the user what to change. If already open (exit code 2), inform the user that the editor is already open and they can reload the file in their editor (e.g., :e in Neovim). Do NOT retry the command.
Push changes: a gh issue-agent push <issue-number> (the push command verifies .approve files exist)

Comment file format:

Named like 001_comment_<id>.md, 002_comment_<id>.md, etc.
Metadata headers show author, creation date
Only your own comments can be edited by default

Workflow E: Adding a NEW comment

Use this ONLY when a completely new, separate comment is needed. Do NOT use this when content should be added to an existing comment.

Pull the issue first (if not already): a gh issue-agent pull <issue-number>
Generate comment boilerplate: a gh issue-agent init comment <issue-number>
Edit the generated file in ~/.cache/gh-issue-agent/<owner>/<repo>/<issue-number>/comments/
Run a gh issue-agent review <file-path> in background (run_in_background: true) for user review. This command blocks until the user closes the editor.
STOP and wait for the background command to complete. Do NOT proceed to push until the command finishes. When it completes, check the exit code: exit code 0 means approved, exit code 1 means not approved, exit code 2 means the editor is already open. If not approved, ask the user what to change. If already open (exit code 2), inform the user that the editor is already open and they can reload the file in their editor (e.g., :e in Neovim). Do NOT retry the command.
Push changes: a gh issue-agent push <issue-number> (the push command verifies .approve files exist)

Editing Comments

Only your own comments can be edited by default
To edit other users' comments, use --edit-others flag
Comment files have metadata in HTML comments at the top (author, id, etc.)

Safety Features

pull fails if local changes exist (use --force to discard)
push uses field-level conflict detection: only fails if locally modified fields were also modified remotely
- e.g., adding a label remotely does NOT block body edits
- When a conflict occurs, pull --force to re-fetch the latest state, re-apply edits, and push again. NEVER use push --force
NEVER use push --force. push --force blindly overwrites remote changes without merging. If push fails due to a conflict, always resolve by pull --force → re-edit → push
push fails when editing other users' comments (use --edit-others to allow)
push fails when deleting comments (use --allow-delete to allow)
Before using --force on pull, use diff or push --dry-run to verify what local changes will be lost
Always use a gh issue-agent review <file-path> in background (run_in_background: true) to let user review edited content before pushing. The user approves by setting submit: true in the frontmatter within Neovim. The push command verifies .approve files exist for all changed files and rejects the push if any file is unapproved.
CRITICAL: After running a gh issue-agent review in background, STOP and wait for the background command to complete. Do NOT proceed to push until the command finishes. Exit code 0 means approved, exit code 1 means not approved, exit code 2 means the editor is already open.

Writing Style

まず ~/.claude/skills/github-issue/writing-guide.md を読み込むこと。 Issue 本文とコメントの書き方ルールが定義されている。

Notes

For other repos, use -R owner/repo option

Name	github-issue
Description	Use `a gh issue-agent` to view, create, and edit GitHub Issues. Use this skill when working with GitHub Issues - viewing issue content, creating new issues, editing issue body/title/labels, or adding/editing comments.

github-issue

SKILL.md