Agent-almanac create-github-issues

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/zh-CN/skills/create-github-issues" ~/.claude/skills/pjt222-agent-almanac-create-github-issues-e3e0bd && rm -rf "$T"

manifest: i18n/zh-CN/skills/create-github-issues/SKILL.md

source content

创建 GitHub Issue

从审查发现或任务拆解中结构化创建 GitHub Issue。将发现列表（来自

review-codebase

、

security-audit-codebase

或手动分析）转化为格式规范的 GitHub Issue，包含标签、验收标准和交叉引用。

适用场景

代码库审查产生了需要跟踪的发现表格后
规划会议识别出应成为 Issue 的工作项后
将 TODO 列表或待办事项转换为可跟踪的 GitHub Issue 时
批量创建需要一致格式和标签的相关 Issue 时

输入

必需：
```
findings
```
——条目列表，每条至少包含标题和描述。理想情况下还包含：严重程度、受影响文件和建议标签
可选：
- ```
group_by
```
  ——将发现批量归入 Issue 的方式：
```
severity
```
  （严重程度）、
```
file
```
  （文件）、
```
theme
```
  （主题）（默认：
```
theme
```
  ）
- ```
label_prefix
```
  ——自动创建标签的前缀（默认：无）
- ```
create_labels
```
  ——是否创建缺失的标签（默认：
```
true
```
  ）
- ```
dry_run
```
  ——预览 Issue 而不实际创建（默认：
```
false
```
  ）

步骤

第 1 步：准备标签

确保所有所需标签在仓库中存在。

列出现有标签：
```
gh label list --limit 100
```
识别发现所需的标签（来自严重程度、阶段或显式标签字段）
将严重程度映射到标签（若未映射）：
```
critical
```
、
```
high-priority
```
、
```
medium-priority
```
、
```
low-priority
```

将阶段/主题映射到标签：

security

、

architecture

、

code-quality

、

accessibility

、

testing

、

performance

若

create_labels

为 true，创建缺失的标签：

gh label create "name" --color "hex" --description "desc"

使用一致的颜色：红色用于 critical/security，橙色用于 high，黄色用于 medium，蓝色用于 architecture，绿色用于 testing

预期结果： 发现引用的所有标签均在仓库中存在，未创建重复标签。

失败处理： 若

gh

CLI 未认证，提示用户运行

gh auth login

。若标签创建被拒绝（权限不足），在不创建标签的情况下继续，并记录缺失的标签。

第 2 步：分组发现

将相关发现批量归入逻辑性 Issue，避免 Issue 泛滥。

若
```
group_by
```
为
```
theme
```
：按阶段或类别分组（所有安全发现 → 1-2 个 Issue，所有无障碍问题 → 1 个 Issue）
若
```
group_by
```
为
```
severity
```
：按严重程度分组（所有 CRITICAL → 1 个 Issue，所有 HIGH → 1 个 Issue）
若
```
group_by
```
为
```
file
```
：按主要受影响文件分组
在每组内按严重程度排序（CRITICAL 优先）
若一组超过 8 条发现，按子主题拆分为子组
每组对应一个 GitHub Issue

预期结果： 形成一组 Issue 分组，每组包含 1-8 条相关发现。Issue 总数应可管理（完整代码库审查通常为 5-15 个）。

失败处理： 若发现没有分组元数据，退回到每条发现对应一个 Issue。对于小型发现集（< 10 条）这是可接受的，但对于较大的发现集会产生过多 Issue。

第 3 步：撰写 Issue

使用标准模板构建每个 Issue。

标题：

[Severity] Theme: Brief description

——例如：

[HIGH] Security: Eliminate innerHTML injection in panel.js

正文结构：

## Summary
One-paragraph overview of what this issue addresses and why it matters.

## Findings
1. **[SEVERITY]** Finding description (`file.js:line`) — brief explanation
2. **[SEVERITY]** Finding description (`file.js:line`) — brief explanation

## Acceptance Criteria
- [ ] Criterion derived from finding 1
- [ ] Criterion derived from finding 2
- [ ] All changes pass existing tests

## Context
Generated from codebase review on YYYY-MM-DD.
Related: #issue_numbers (if applicable)

应用标签：严重程度标签 + 主题标签 + 任何自定义标签
若发现引用了特定文件，在正文中提及（不作为受理人）

预期结果： 每个 Issue 有清晰的标题、带严重程度标记的编号发现、复选框验收标准和适当的标签。

失败处理： 若正文超过 GitHub Issue 大小限制（65536 个字符），将 Issue 拆分为多个部分并相互交叉引用。

第 4 步：创建 Issue

使用

gh

CLI 创建 Issue 并报告结果。

若
```
dry_run
```
为 true，打印每个 Issue 的标题和正文，不实际创建，然后停止

对每个已撰写的 Issue 执行创建：

gh issue create --title "title" --body "$(cat <<'EOF'
body content
EOF
)" --label "label1,label2"

记录每个已创建 Issue 的 URL
所有 Issue 创建完成后，打印汇总表：
```
#number | Title | Labels | Findings count
```
若 Issue 需要排序，添加交叉引用：编辑第一个 Issue，注明"Blocked by #X"或"See also #Y"

预期结果： 所有 Issue 创建成功，打印出包含 Issue 编号和 URL 的汇总表。

失败处理： 若单个 Issue 创建失败，记录错误并继续处理剩余 Issue，最后汇总报告失败情况。常见失败原因：认证已过期、未找到标签（若

create_labels

为 false）、网络超时。

验证清单

所有发现均在至少一个 Issue 中得到体现
每个 Issue 至少有一个标签
每个 Issue 有复选框形式的验收标准
未创建重复 Issue（对照现有开放 Issue 检查标题）
Issue 数量与发现数量匹配合理（大型发现集不应 1:1 对应）
已打印包含所有 Issue URL 的汇总表

常见问题

Issue 泛滥：每条发现创建一个 Issue 会产生 20+ 个难以管理的 Issue。应积极分组——完整审查产生 5-10 个 Issue 为理想状态
缺少验收标准：没有复选框的 Issue 无法验证是否完成。每条发现至少应映射到一个复选框
标签混乱：创建过多标签会使筛选失去意义。坚持使用严重程度 + 主题，而非每条发现单独建标签
引用了陈旧内容：若从旧审查中创建 Issue，请先验证发现是否仍适用。代码可能已变更
忘记试运行：对于大型发现集，始终先用
```
dry_run: true
```
预览。编辑计划比关闭 15 个错误 Issue 容易得多