mitsuhiko/gh-issue-sync

Overview

This skill lets you manage GitHub issues as local Markdown files, enabling triage, search, edit, and creation workflows from your editor or terminal. It syncs issues into .issues/open/ and .issues/closed/, tracks new temporary issues, and propagates comments and ID changes on push.

How this skill works

It pulls issues from a repository and writes one Markdown file per issue with YAML frontmatter for metadata (title, labels, assignees, milestone, state, etc.). New issues use temporary T-prefixed filenames that are rewritten to real issue numbers on push; comment drafts are created as .comment.md files and posted when pushing. Commands support init, pull, push, list, new, close, reopen, status, and diff to manage local/remote synchronization.

When to use it

• You want to triage and edit GitHub issues entirely in your local editor or terminal.
• You need searchable, Git-friendly issue history stored with your repository.
• You prefer to draft comments or bulk-update labels and assignees before publishing.
• You want to operate offline and sync changes later.
• You need to automate issue updates or include issues in git-driven workflows.

Best practices

• Keep .issues/ committed to the repo or a separate branch to share triage state with teammates.
• Use temporary T-prefixed filenames for drafts and push when ready so IDs and references update correctly.
• Create .comment.md files next to an issue file to stage comments; they are deleted after push.
• Run gh-issue-sync pull before pushing to reduce conflicts; use --force only when you intend to overwrite local changes.
• Use consistent frontmatter (title, labels, assignees, milestone, state) to ensure predictable sync behavior.

Example use cases

• Triaging a backlog: pull open issues, add labels and assignees locally, then push changes.
• Drafting a new issue and comment: create a T-prefixed file and a .comment.md, then push to publish both.
• Bulk edits: script updates to frontmatter across multiple files and push as a single batch.
• Offline work: edit issue bodies and metadata without network access, then push when online.
• Reviewing changes: use status and diff to preview local vs remote differences before syncing.