github-issue
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.
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.
| name | github-issue |
|---|---|
| description | Use `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
- Pull the issue:
a gh issue-agent pull 123 - Read/Edit files in
~/.cache/gh-issue-agent/<owner>/<repo>/123/ - Show the draft file path to user for review
- 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-othersflag - 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
pullfails if local changes exist (userefreshto discard)pushfails if remote has changed since pull (use--forceto overwrite)pushfails when editing other users' comments (use--edit-othersto allow)pushfails when deleting comments (use--allow-deleteto 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/repooption