需要创建、查询或管理 GitHub Issues 时：用…

在 GitHub 仓库中进行 issue 创建、更新、查询、评论、子 issue、标签、里程碑、类型、依赖和 Projects 管理时使用。

适用场景

解决思路

1. 先判断动作：创建、更新还是查询 issue。
2. 收集上下文：获取仓库信息、已有 labels、milestones 等必要信息。
3. 组织内容：按 issue 类型选择 references/templates.md 中的模板：Bug、error、broken、not working 用 Bug Report；Feature、enhancement、add、new 用 Feature Request；Task、chore、refactor、update 用 Task。
4. 执行：读操作用 MCP 工具，写操作用 gh api。
5. 完成后向用户报告 issue URL。
6. 读取 issue 详情、子 issue、评论、labels 用 mcp__github__issue_read（方法：get、get_comments、get_sub_issues、get_labels）。
7. 按 state、labels、date 列出或筛选仓库 issue 用 mcp__github__list_issues。
8. 跨仓库搜索 issue 用 mcp__github__search_issues，使用 GitHub 搜索语法。
9. 列出 projects、project fields、project items、status updates 用 mcp__github__projects_list。
10. 获取 project、field、item、status update 详情用 mcp__github__projects_get。
11. 添加、更新或删除 project items、创建 status updates 用 mcp__github__projects_write。
12. 创建或更新 issue 可用 mcp__github__issue_write（方法 create、update），支持 title、body、type、labels、assignees、milestone 和 issue fields。
13. 给 issue 添加评论或 reaction 用 mcp__github__add_issue_comment。
14. 添加、移除或调整子 issue 优先级用 mcp__github__sub_issue_write。
15. 当 MCP server 未连接，或需要 MCP 未暴露的 REST 字段时，写操作改用 gh api。
16. 创建 issue：gh api repos/{owner}/{repo}/issues -X POST -f title=... -f body=...。
17. 更新 issue：gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f title=... -f state=...。
18. 添加评论：gh api repos/{owner}/{repo}/issues/{number}/comments -X POST -f body=...。
19. 关闭 issue：gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f state=closed。
20. 设置 issue type：在创建调用中加 -f type=Bug（仅 REST API；gh issue create CLI 不支持 --type）。注意 gh issue create 可用于基础创建，但不能设置 type；需要 type 时用 gh api。
21. 创建 issue 的完整示例命令：gh api repos/{owner}/{repo}/issues -X POST -f title="Issue title" -f body="Issue body in markdown" -f type="Bug" --jq '{number, html_url}'。
22. 可选参数：-f type="Bug" 设置类型；-f 'labels[]=bug' 设置标签（可重复）；-f 'assignees[]=username' 设置负责人（可重复）；-f milestone=1 设置里程碑编号。
23. 参数含 name[]=value 时整个键值对要加引号，例如 -f 'labels[]=bug'；否则 zsh（macOS 默认 shell）会把 [] 当 glob 导致 no matches found。
24. 发现可用 issue types：gh api graphql -f query='{ organization(login: "ORG") { issueTypes(first: 10) { nodes { name } } } }' --jq '.data.organization.issueTypes.nodes[].name'。
25. 分类优先使用 issue types 而不是 labels：当组织配置了 Bug、Feature、Task 等类型时，用 type 参数，而不是再打 bug/enhancement 等等价标签；只有组织未配置 issue types 时才回退到 labels。
26. 标题指南：具体且可执行；不超过 72 字符；已设置 issue type 时不要加 [Bug] 这类冗余前缀。示例：Login fails with SSO enabled（type=Bug）、Add dark mode support（type=Feature）、Add unit tests for auth module（type=Task）。
27. 正文结构：总是使用 references/templates.md 中的模板，并按 issue 类型选择 Bug Report、Feature Request 或 Task。
28. 更新 issue：用 gh api repos/{owner}/{repo}/issues/{number} -X PATCH ...；只包含要修改的字段。可用字段：title、body、state（open/closed）、labels、assignees、milestone。
29. 更新前先获取当前 issue，以保留未修改字段。
30. 标准标签回退：适用时使用 bug、enhancement、documentation、good first issue、help wanted、question、wontfix、duplicate、high-priority。
31. 创建 issue 前始终确认仓库上下文。
32. 缺少关键信息时询问用户，而不是猜测。
33. 已知关联 issue 时链接，例如写 Related to #123。
34. 高级搜索：复杂布尔逻辑、日期范围、跨仓库搜索、issue field filters（field.name:value）参考 references/search.md。
35. 子 issue 与父 issue：把工作拆成层级任务参考 references/sub-issues.md。
36. 里程碑：创建、读取、更新、关闭、重开、删除 milestones 及管理 milestone issues 参考 references/milestones.md。
37. 标签管理：发现、创建、重命名、改色、删除仓库 labels；给 issue 添加或替换 labels 参考 references/labels.md。
38. Issue 依赖：跟踪 blocked-by / blocking 关系参考 references/dependencies.md。
39. Issue types 高级操作：MCP list_issue_types / type 参数之外的 GraphQL 操作参考 references/issue-types.md。
40. Projects V2：项目板、进度报告、字段管理参考 references/projects.md。
41. Issue fields：自定义元数据，如日期、优先级、文本、数字（private preview）参考 references/issue-fields.md。
42. Issue 中图片：通过 CLI 在 issue 正文和评论中嵌入图片参考 references/images.md。

适用边界 · 注意事项

• 未配置 @modelcontextprotocol/server-github MCP server 且未认证 gh CLI 时，无法按本技能操作。
• 需要管理非 GitHub 平台（如 GitLab、Jira）的 issue 时。
• 组织未启用 issue types 时不能使用 type 分类，只能回退到 labels；依赖 private preview 的 issue fields 但账号无权限时也不适用。