github-issues

你可以创建、更新、查询和评论 GitHub（或 GitLab）议题。

规则概览

规则	影响	文件
议题标题	高	rules/issue-title.md
遵循模板	中	rules/template-adherence.md
不使用清单	中	rules/no-checklists.md

CLI 与 MCP 的优先级

所有 CLI 原生支持的操作都使用 CLI（gh/glab）——它是此技能中默认使用的接口。对于没有原生 CLI 子命令的操作（目前包括议题字段——议题上的结构化优先级／工作量／日期／自定义元数据），按以下顺序回退：

1. GitHub MCP 服务工具，前提是已连接此类服务。在 Claude Code 中，其工具通常命名为 mcp__github__*（list_issue_fields、issue_read、issue_write），但具体名称取决于服务的注册方式——应根据功能检测，而非依赖确切 ID。切勿假定该服务可用。此技能不会预先批准任何 MCP 工具——主机会请求权限，由用户决定是否允许使用。
2. 使用 gh api 调用 REST API，并发送 -H "X-GitHub-Api-Version: 2026-03-10"：
   • 列出字段：gh api orgs/{org}/issue-fields（需要 read:org）——返回每个字段的数字 id、name、data_type（text、number、date、single_select、multi_select）和 options[].name
   • 读取议题的字段值：gh api repos/{owner}/{repo}/issues/{number}/issue-field-values
   • 添加或更新字段值而不影响其他字段：向同一路径发送 POST，使用 --input -，请求体为 {"issue_field_values":[{"field_id":1,"value":"High"}]}。单选字段使用选项的名称，多选字段使用名称数组，数字字段使用数字，日期字段使用 YYYY-MM-DD
   • 向同一路径发送 PUT 会替换议题上的所有字段值——除非确实需要，否则避免使用
   • 清除单个字段：DELETE repos/{owner}/{repo}/issues/{number}/issue-field-values/{field_id}（如果该字段没有值，则返回 404）
3. 妥善跳过：完成操作的其余部分，说明哪些字段无法设置，并指出连接 GitHub MCP 服务即可启用类型化议题字段支持。

工作流

1. 确定操作：创建、更新、查询或评论
2. 从 git remote get-url origin 检测远程主机（github.com → gh，gitlab.com → glab；默认使用 GitHub），并在整个过程中使用对应的 CLI。获取所有者/仓库（或群组/项目）信息。仅限 GitHub 的功能——组织议题类型、议题字段、子议题和 .github/ISSUE_TEMPLATE/——在 GitLab 上不存在：使用 GitLab 时，跳过议题类型、议题字段和子议题步骤，并使用 .gitlab/issue_templates/ 以及描述中的检查清单
3. 在主机惯用的位置检查议题模板：GitHub 上为 .github/ISSUE_TEMPLATE/ 或 .github/；GitLab 上为 .gitlab/issue_templates/
4. 列出可用的组织议题类型（用户所有的仓库会导致此操作失败，这是预期行为；继续处理即可）
5. 通过上文所述的 CLI 与 MCP 优先级规则，使用 CLI 列出可用的议题字段（组织级，仓库会继承）。没有原生 CLI 子命令，因此请使用 MCP 服务或 gh api（用户所有的仓库会导致此操作失败，这是预期行为；继续处理即可）。组织有四个默认字段：Priority（单选：Urgent、High、Medium、Low）、Effort（单选：High、Medium、Low）、Start date 和 Target date。将这些字段视为可能存在，但仍须在运行时确认——组织可能已重命名或移除这些字段，也可能添加了选项
6. 创建或更新时：
   • 更新时：先获取当前议题
   • 有可用议题类型时，选择最合适的类型（例如，缺陷选 Bug、新功能选 Feature、一般工作选 Task）
   • 用户指定字段值（优先级、工作量、日期、自定义字段）时，通过上文所述的 CLI 与 MCP 优先级规则设置这些字段——值必须符合字段声明的类型（单选选项名称、文本、数字、YYYY-MM-DD 日期）
   • 如果 Priority 和 Effort 存在，但用户未指定这两项，则根据议题内容分别提出建议：Priority 依据严重程度和影响范围，Effort 依据预期变更范围，并说明所选值。如果议题过于模糊，无法判断，则留空而不要猜测；除非用户要求，否则不要设置日期
   • 按照 rules/issue-title.md 生成标题
   • 如果找到模板，则按照模板生成正文（参见 rules/template-adherence.md）；否则使用清晰的结构化格式
   • 创建时：获取当前已认证用户，并将其加入受指派人
   • 如果用户指定了父议题，则将创建或更新的议题关联为子议题（使用议题的节点 ID，而非编号）
7. 管理父议题/子议题：
   • 列出子议题：获取父议题的子议题
   • 添加子议题：传入父议题编号和子议题的节点 ID
   • 移除子议题：解除子议题与父议题的关联
   • 调整子议题顺序：使用 after_id 或 before_id 重新排序
   • 创建多个相关议题时，优先将其组织成一个父议题及多个子议题，而不是彼此独立的议题
8. 查询时：
   • 按编号获取特定议题
   • 检查父议题的子议题层级
   • 按筛选条件、关键词和跨仓库查找搜索议题
   • 按议题字段值筛选（使用 MCP field_filters 或 API；没有原生 CLI 对应功能——按照上述优先级规则尽可能处理）
   • 列出仓库议题
9. 评论时：
   • 必要时先获取议题上下文
   • 在议题中添加评论
10. 显示摘要，列出议题链接和变更内容

验证

• 标题：遵循 rules/issue-title.md
• 带模板的正文：遵循 rules/template-adherence.md
• 标签：仅使用仓库中已有的标签
• 字段：仅设置组织或仓库中已有的字段；不得臆造字段名称或单选选项
• 受指派人：仅指派有效的仓库协作者