gh-issue-sync Skill for Claude Code: What It Does and How to Install It

Teaches Claude to manage GitHub issues as local Markdown files: pull them, search and edit them, create new ones and push the changes back.

Installs: 25.2K; on skills.sh
Stars: 169; on GitHub
Files: 1; besides SKILL.md
Updated: Mar 2026; last repo commit

The skill documents the gh-issue-sync command line tool from the mitsuhiko/gh-issue-sync repo. Issues become Markdown files with YAML front matter in .issues/open/ and .issues/closed/. Claude edits the files, and gh-issue-sync push sends the changes to GitHub. New issues get temporary T IDs that become real numbers on push.

The skill is only the instructions. You need the gh-issue-sync tool and the GitHub CLI (gh) signed in with gh auth login. The README says the code is entirely LLM generated and that it is unclear whether it can be copyrighted.

Good for

Maintainers who triage many issues at once
Developers who want Claude to refine issues locally before anything reaches GitHub
Anyone who wants offline, editor-based access to their issues

Install gh-issue-sync

Claude Code

Copy this prompt.

Install the gh-issue-sync skill in Claude Code. Run this command:

curl -sSfL https://github.com/mitsuhiko/gh-issue-sync/releases/latest/download/install.sh | sh
gh-issue-sync write-skill --agent claude

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires gh signed in (gh auth login).

Install the gh-issue-sync tool first. The skill is only instructions, and it needs gh (GitHub CLI) signed in. gh-issue-sync write-skill puts the skill file in the right folder for your agent: the README table lists ~/.claude/skills/ for Claude Code and ~/.codex/skills/ for Codex. The skills CLI and folder routes install only the skill file. There is no Claude app upload route because the skill drives a local tool.

From the project README. Source.

What's in the skill

When it loads

Manage GitHub issues locally as Markdown files. Use for triaging, searching, editing, and creating issues without leaving your editor or terminal.

Sections in SKILL.md

Commands
File Format
Temporary Issues
Comments
Notes

Key facts

Author: mitsuhiko (repo owner; the tool and its skill ship in one repo)
Repo: mitsuhiko/gh-issue-sync
License: Apache-2.0 (LICENSE and README agree)
Installs on skills.sh: 25,169 (Nov 2, 2026)
GitHub stars: 169 for the whole repo (Nov 2, 2026)
Last repo commit: Mar 31, 2026
Audits on skills.sh: Gen Agent Trust Hub: pass, Socket: pass, Snyk: warn
What it includes: 2 files: SKILL.md and embed.go (Go file that embeds SKILL.md in the tool)
Needs: The gh-issue-sync tool and gh (GitHub CLI) installed and signed in

What it includes

Sets up .issues in a git repo, next to the .git folder.
Runs code · gh-issue-sync init
Fetches open issues as Markdown files; --all adds closed ones.
Conflicts with local edits are skipped unless you pass --force.
Try: “Pull my open issues and group them by label”
Runs code · gh-issue-sync pull
Sends local changes to GitHub; --dry-run previews them.
README: creates missing labels and milestones, and creates temporary-ID issues.
Runs code · gh-issue-sync push
Lists local issues with gh issue list style flags and a --search query.
The search supports is:, label:, no:, assignee:, milestone: and sort:.
Runs code · gh-issue-sync list
Creates a local issue with a temporary T ID; --label and --edit are available.
Runs code · gh-issue-sync new "Title"
Marks an issue closed (reason completed or not_planned) or open on next push.
Runs code · gh-issue-sync close and reopen
Shows local changes; diff --remote re-fetches from GitHub first.
Runs code · gh-issue-sync status and diff
A .comment.md file next to an issue is posted on push, then deleted.
Example: .issues/open/42-fix-login-bug.comment.md.
Delete · Comments
README command that pushes, then pulls.
SKILL.md does not list sync, edit or write-skill; the README does.
Runs code · gh-issue-sync sync
Writes the skill file for Codex, Pi, Claude Code, OpenCode, Amp or others.
Use --scope user or project, or --output for a custom folder.
Runs code · gh-issue-sync write-skill

From the official docs

Permissions

Medium risk

What it can do

Read your data
Create and change things
Delete things
Read-only modeHow to turn it on

Watch out for

Push changes GitHub in bulk
push creates issues, closes or reopens them, edits fields and posts comments for every changed file. Run gh-issue-sync push --dry-run first and review it. github.com
The installer downloads a binary
The README one-liner pipes an install script from GitHub Releases into sh. The script template downloads a prebuilt binary into a bin folder such as ~/.local/bin. The README also lists go install and a manual download. github.com
Project sync needs extra scopes
The README says Projects sync needs gh auth refresh -s project, which widens the token scopes. github.com
Conflicts are skipped, not overwritten
The README says a three-way comparison detects conflicts and skips them with a warning. --force on pull overwrites local files. github.com

Technical details

Turning on read-only	pull, list, status and diff do not push. push --dry-run previews changes without sending them.
Sign-in and keys	Uses the gh CLI login (gh auth login). The tool stores original copies of issues in .issues/.sync/originals/.
Scopes	Reads and writes issues in the GitHub repo that gh is signed in to Writes Markdown files under .issues/ in your project Posts comments from .comment.md files and deletes those files afterward Creates missing labels and milestones on push

Questions

What does the gh-issue-sync skill do?

It teaches Claude to use the gh-issue-sync tool so GitHub issues become local Markdown files. Claude can search, edit and create issues there, and push the changes to GitHub when you are ready.

How do I install it?

Use the install box at the top of this page. The skill is only instructions, so install the gh-issue-sync tool first. The README gives an install script, go install and a binary download, then gh-issue-sync write-skill to add the skill.

Does it need a GitHub login?

Yes. The README says gh must be installed and signed in with gh auth login. Projects sync needs the extra project scope.

Does it work in the Claude app?

The install box has no Claude app upload route. The skill drives a command line tool and local files on your machine.

Will it change my GitHub issues without asking?

Edits stay local until push. The README documents push --dry-run to preview. Our advice: ask Claude to run the dry run and show it to you before every push.

Is it safe?

push can create, edit and close many issues and post comments. The README also says the code is entirely LLM generated. Try it on a test repo first.

Is it different from gh-axi?

Yes. The gh-axi README describes it as a wrapper around the gh CLI for agents. gh-issue-sync keeps a local copy of issues so you can edit many in bulk and push once.

What if the same issue changed on GitHub and locally?

The README says that is a conflict. Pull and push skip it with a warning, and pull --force overwrites your local file.

Information

updated Nov 2, 2026

Repository: mitsuhiko/gh-issue-sync
Folder: skill

mitsuhiko/gh-issue-sync skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 4

gh-issue-sync README · github.com
gh-issue-sync SKILL.md · github.com
install.sh template · github.com
gh-axi README · github.com