Community生产力与协作github.com

issue-project-init

为仓库初始化 GitHub Issue 跟踪:创建标准标签、带有 Status/Reach/Impact/Confidence/Effort/RICE 字段的 Projects v2 看板(从头创建或从参考看板复制),将其链接到仓库并记录工作流程。在为新仓库设置 Issue 和项目时,或当标签/字段发生偏离时使用。

issue-project-init 是什么?

该技能为仓库自动初始化 GitHub Issue 跟踪标准约定。它会创建一套预定义的标签(如 bug、feature、tech-debt、epic 以及可选的组件标签)、一个带有 Status、Reach、Impact、Confidence、Effort 和 RICE 评分字段的 Projects v2 看板(支持从头创建或从已有参考看板复制),并将看板链接到目标仓库。最后,它会在仓库的 AGENTS.md 或 CLAUDE.md 中写入完整的工作跟踪文档,确保所有其他 issue-* 技能(issue-search、issue-file、issue-start、issue-pr-refs、issue-close-out、issue-project-fields、issue-score、issue-link、issue-plan-doc、issue-file-found、issue-audit-scores)能够正常工作。该技能适用于 Claude Code、Cursor、Codex 等 AI 编码代理,要求已安装 gh 和 jq,且 gh 已认证了 repo 和 project 作用域。所有操作均直接写入 GitHub(不涉及 git push),建议在执行写入操作前先向用户说明即将创建的内容并获得确认。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/marsv024/gh-issue-skills/tree/master/skills/issue-project-init

Installed? Explore more 生产力与协作 skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

为仓库初始化和 Issue 及项目

设置其他 issue-* 技能所依赖的约定。所有操作均直接写入 GitHub(标签、项目、仓库链接):请先说明将要创建的内容并征得用户同意。不会推送到 git。

前提条件:gh auth status 显示 repo 和 project 作用域(否则执行 gh auth refresh -s project);已安装 jq。

1. 检查(只读)

REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner); OWNER=${REPO%%/*}
gh label list --repo "$REPO" --limit 100
gh project list --owner "$OWNER"

2. 标签

创建以下标准标签(名称|描述|颜色)。添加仓库自己的组件标签(默认为 backend、frontend;根据需要删除或添加)。除非另有要求,否则保留 GitHub 的默认标签(enhancement、documentation 等)。

while IFS='|' read -r n d c; do
  gh label create "$n" --repo "$REPO" --description "$d" --color "$c" --force
done <<'EOF'
bug|Something isn't working|d73a4a
feature|New user-facing capability|a2eeef
tech-debt|Tracked technical debt|fbca04
epic|Multi-issue effort|5319e7
backend|Backend / services|0e8a16
frontend|Frontend / web app|1d76db
performance|Performance|fef2c0
security|Security|d93f0b
testing|Tests / CI / E2E|c5def5
privacy|Privacy / GDPR|bfdadc
ai|Addressable by an AI agent without human intervention|7057ff
needs-context|AI-addressable once a quick check or decision is answered (also carries ai)|fbca04
needs-human|Needs a device, store/legal/owner decision, external access or a roadmap choice|d93f0b
wontfix|This will not be worked on|ffffff
EOF
gh label list --repo "$REPO"      # 创建时默认静默,请验证

3. 看板

A. 复制参考看板(仅字段和视图,不包含项目):

gh project copy <源编号> --source-owner <源所有者> --target-owner "$OWNER" --title "<仓库名称>"

B. 从头创建:

gh project create --owner "$OWNER" --title "<仓库名称>" --format json -q '.number'   # 记下编号为 $N
for f in Reach Impact "Confidence (%)" "Effort (days)" RICE; do
  gh project field-create "$N" --owner "$OWNER" --name "$f" --data-type NUMBER
done

新看板已自带一个Status字段,包含 Todo、In Progress、Done;这已经足够(可以在看板 UI 中添加 Defer 选项)。

然后链接并验证:

gh project link "$N" --owner "$OWNER" --repo "$REPO"
# 然后按照 issue-project-fields 中的“先解析 ID”步骤操作:它必须找到看板及所有字段

4. 在仓库中记录

将以下内容添加到仓库的代理指令文件中(AGENTS.md、CLAUDE.md 或两者都加),用 <...> 占位符填写具体信息(仓库、看板 URL 以及你在步骤 2 中创建的组件标签;如果技能来自某个插件,请说明并注明插件名称)。在分支上提交,不要提交到默认分支。

## 工作跟踪(GitHub Issues)

待办事项位于 **GitHub Issues**(`<owner/repo>`)中,通过 **<看板标题>** 项目(<看板 URL>)进行跟踪。Issue 是上下文和状态的唯一真实来源;通过 Issue 编号(`#123`)和标签来引用工作。工作流程技能:`issue-search`、`issue-file`、`issue-start`、`issue-pr-refs`、`issue-close-out`、`issue-project-fields`、`issue-score`、`issue-link`、`issue-plan-doc`、`issue-file-found`、`issue-audit-scores`、`issue-project-init`(<它们来自哪里>)。

### 标签

| 分组 | 标签 | 规则 |
|---|---|---|
| 类型 | `bug`、`feature`、`tech-debt`、`epic` | 每个 Issue 恰好一个 |
| 组件 | <例如 `backend`、`frontend`> | 根据需要添加多个 |
| 主题 | `performance`、`security`、`testing`、`privacy` | 可选 |
| 代理路由 | `ai`、`needs-context`、`needs-human` | 可选。`ai` = 代理可以无人值守完成;`needs-context` = 代理在快速回答问题后即可完成(也带有 `ai`);`needs-human` = 需要设备、外部访问或所有者决策 |

### 项目字段

| 字段 | 值 | 说明 |
|---|---|---|
| Status | Todo / In Progress / Done | 仅由编排代理设置 |
| Reach | 1–5 | 影响到的用户数 |
| Impact | 0.5–3 | 影响程度 |
| Confidence (%) | 整数百分比,例如 `70` | |
| Effort (days) | 数字 | |
| RICE | `(Reach × Impact × Confidence) / Effort` | 同时在正文中写为 `**Score:** RICE x = (R × I × C%) / Ed`,使 Issue 可独立阅读 |

### Issue 正文和工作流程

**Issue 正文**包含完整记录:描述、当前状态、需要完成的事项、重要性、相关文件、估算。使用 `#n` 链接相关工作;使用“blocked by”表达排序关系(正文文本和 dependencies API,参见 `issue-link`)。大型工作是一个 `epic`,其计划放在 Issue 正文中,子任务为子 Issue。

- **开始之前:** 先搜索(`issue-search`);尽量复用或扩展,而不是提交重复项。
- **工作期间:** 将项目设置为“In Progress”并分配给自己(`issue-start`);分支名称应包含 Issue 编号(`feat/123-short-desc`)。Bug 和技术债务以失败的测试开始。将无关的发现作为新 Issue 提交,而不是扩大范围(`issue-file-found`)。
- **完成时:** 每个 PR 引用其 Issue(每个 Issue 用 `Closes #n`,epic 用 `Part of #n`;`issue-pr-refs`);合并后将 Status 设置为“Done”并更新相关 Issue(`issue-close-out`)。
- `gh` 需要 `project` 作用域(`gh auth refresh -s project`)。只有编排代理才能更改 Issue/项目状态;委派的子代理不创建、编辑或关闭 Issue。

5. 可选:植入一个 epic

issue-file(类型 epic)→ issue-plan-doc → 每个切片执行 issue-file + issue-link + issue-project-fields + issue-score。

注意事项

  • gh label create、gh project copy|link|item-edit 在成功时默认静默:请始终验证。
  • 复制的看板初始为空;item-add 是幂等的。
  • 子 Issue 和依赖关系的 REST 调用需要 Issue 的数值数据库 ID(参见 issue-link)。
  • Confidence 是整数百分比(70);不同看板的字段 ID 不同,因此始终重新发现它们(issue-project-fields)。

相关技能