gh-issue-sync
将GitHub Issues同步到本地Markdown文件进行离线编辑和批量管理。
安装使用
复制下面这段提示词发给你的 AI（Claude / Cursor / TRAE / Codex / WorkBuddy 等），它会自动帮你完成安装：
帮我安装这个 AI Skill：gh-issue-sync。 它的用途是：将GitHub Issues同步到本地Markdown文件进行离线编辑和批量管理。 完整的 Skill 内容见：https://321skill.com/skills/gh-issue-sync/raw/index.md 请读取该页面内容，如果是 SKILL.md 格式直接安装，如果是 README 提炼核心 prompt 后安装。
提示词包含完整的 Skill 内容链接，AI 读取后即可完成安装。你也可以 查看完整内容 确认无误。
使用示例
“请帮我使用gh-issue-sync拉取当前项目的所有open issue到本地，并整理成一份待办清单。”，它会执行初始化、拉取命令，并读取本地Markdown文件生成清晰的Issue列表。或者
对AI说：“我本地修改了几个issue的描述，请帮我把这些更改推送到GitHub。”，它会执行 `gh-issue-sync push` 命令完成同步。
介绍
gh-issue-sync 是一款命令行工具，旨在解决在GitHub上批量编辑和管理大量Issue时操作繁琐、效率低下的痛点。它通过将GitHub仓库中的Issue拉取到本地的 .issues/ 目录，并以Markdown文件（包含YAML元数据）的形式保存，让用户可以在本地使用熟悉的编辑器进行离线编辑、批量修改或利用AI智能体进行迭代优化。
使用方式非常直接：在项目根目录初始化后，通过 pull 命令拉取Issue，在本地 .issues/open/ 目录下找到对应的Markdown文件进行编辑，完成后使用 push 命令将更改同步回GitHub。它还支持创建本地新Issue（使用临时ID），并在推送时自动转换为GitHub上的真实Issue编号。
该工具特别适合需要频繁处理大量Issue的开发者、项目经理或使用Claude Code等AI编码助手进行代码和需求迭代的团队。它让Issue管理脱离了网页界面的限制，回归到高效的本地工作流中。
需要注意的是，使用前需确保已安装并认证GitHub CLI (gh)。对于使用Projects功能的用户，可能需要刷新授权范围。此外，通过环境变量 GH_ISSUE_SYNC_DIR 可以灵活指定Issue存储目录，方便多仓库或共享场景下的使用。
核心特点
与仅能查看或简单导出Issue的工具不同，gh-issue-sync 实现了完整的双向同步，支持离线编辑后批量推送，并深度集成了对AI编码代理（Agent）工作流的支持，允许智能体在本地直接处理Issue直到满意再统一提交。
注意事项
不适合仅需在GitHub网页端进行简单、零散Issue操作的用户。
常见问题
如何让我的AI编码助手（如Claude Code）使用这个工具？
运行 `gh-issue-sync write-skill --agent claude` 等命令，为对应的Agent生成并安装技能文件，Agent就能理解如何使用该工具了。
可以在项目子目录下运行命令吗？
可以，工具会从当前目录向上搜索，直到找到 `.issues` 目录或 `.git` 根目录。
给 AI 助手的安装指引
如果你的 AI 编程助手（Claude Code、Cursor、TRAE 等）能看到这个页面，把下面这段发给它即可自动完成安装：
请访问 https://321skill.com/skills/gh-issue-sync/raw/index.md 读取 gh-issue-sync 的原始 Skill 定义（Markdown 格式），按其中说明在我的环境里完成安装和配置。
AI 可直接读取的原始 Markdown 地址：/skills/gh-issue-sync/raw/index.md（查看排版版本）