github-issue

fohte's avatarfrom fohte

Use gh-issue-agent to view and edit GitHub Issues. Use this skill when working with GitHub Issues - viewing issue content, editing issue body/title/labels, or adding/editing comments.

⭐1stars🔀0forks📁View on GitHub🕐Updated Jan 4, 2026

When & Why to Use This Skill

The GitHub Issue Management skill empowers Claude to interact seamlessly with GitHub Issues by treating them as local files. This approach enhances developer productivity by providing superior diff visibility, safer editing workflows, and the ability to manage issue titles, labels, and comments directly within an agentic environment, ensuring high-quality contributions to open-source or private repositories.

Use Cases

  • Streamlining project management by viewing and editing GitHub Issue bodies, titles, and labels as local markdown and JSON files.
  • Collaborating on technical discussions by drafting, editing, or deleting comments with built-in safety checks to prevent accidental overwrites.
  • Improving documentation and issue clarity by utilizing local editing tools to review changes and diffs before pushing updates to the remote repository.
  • Triaging repository feedback by efficiently refreshing local issue caches and synchronizing metadata across multiple GitHub issues.
namegithub-issue
descriptionUse `a gh issue-agent` to view and edit GitHub Issues. Use this skill when working with GitHub Issues - viewing issue content, editing issue body/title/labels, or adding/editing comments.

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)
  • 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.

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 (editable)
  • comments/ - Comment files (only your own comments are editable)

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

Refresh (discard local changes and re-fetch)

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

Use this when you want to discard local changes and get the latest from GitHub.

Push (apply changes to GitHub)

# Apply changes
a gh issue-agent push <issue-number>

# 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

Workflow

Viewing only (no edits)

a gh issue-agent view 123

Editing

  1. Pull the issue: a gh issue-agent pull 123
  2. Read/Edit files in ~/.cache/gh-issue-agent/<owner>/<repo>/123/
  3. Show the draft file path to user for review
  4. After user approval, apply changes: a gh issue-agent push 123

Note: Show the draft content to the user for review before pushing.

Editing Comments

  • Only your own comments can be edited by default
  • To edit other users' comments, use --edit-others flag
  • To add a new comment, create a file like comments/new_<name>.md
  • Comment files have metadata in HTML comments at the top (author, id, etc.)

Safety Features

  • pull fails if local changes exist (use refresh to discard)
  • push fails if remote has changed since pull (use --force to overwrite)
  • push fails when editing other users' comments (use --edit-others to allow)
  • push fails when deleting comments (use --allow-delete to allow)
  • Always show edited content to user for review before pushing

Writing Style

Follow these guidelines when writing issues or comments:

  • Avoid unnecessary bold formatting
  • Do not start list items with a summary followed by a colon. Write normal sentences instead
  • When linking to external resources (e.g., other issues), explain why the link is relevant

Notes

  • For other repos, use -R owner/repo option