yasukei/agent-skills

GitHub issue 的建立

讓 AI 根據使用者指定的格式來撰寫 issue 的技能。目標是「每次都用相同的結構，建立一個閱讀後即可直接開始實作、完成後可明確判斷是否完成的 issue」。尤其是 Acceptance criteria 章節，因為後續在 issue-to-pr 等流程中會直接作為實作與審查的完成條件，所以必須以可驗證的方式來撰寫。

1. 優先檢查 repository 的模板

如果 repository 已有模板，則以該 repository 的規則為優先，取代此技能的模板。請檢查以下位置：

• .github/ISSUE_TEMPLATE/ 目錄下的 *.md 以及 *.yml / *.yaml（config.yml 是設定檔案，不是模板）
• .github/ISSUE_TEMPLATE.md、根目錄的 ISSUE_TEMPLATE.md、docs/ISSUE_TEMPLATE.md
• 如果以上皆無，則檢查 owner 的組織共用 repository <owner>/.github 的相同位置

若本地已有 clone，可直接檢視檔案。若無，則透過 gh api repos/<owner>/<repo>/contents/.github/ISSUE_TEMPLATE 等方式取得。

找到模板後：

• 根據要建立的 issue 類型（任務 / Bug），從檔案名稱、name、about、labels 中選出相符的模板。
• 標題結構完全依照模板，不要混用此技能的標題。僅在結尾簡短附加模板中沒有位置但重要的資訊（如依賴關係）。
• 若為 YAML 的 issue form 模板，GitHub 會將表單提交內容以各欄位 attributes.label 作為 ### <label> 標題的方式儲存為內文。請以相同格式組裝內文，並務必填寫 required: true 的欄位。
• 反映模板 frontmatter / 表單定義中的 title（前綴）、labels、assignees。

如果沒有與要建立的類型相符的模板（例如：有 Bug 模板但沒有任務模板），則只對該類型使用下方的預設模板。

2. 決定類型

• 任務：新功能、改善、重構、文件、CI、調查等「要做的事」。→ 使用任務模板
• Bug：修正未如預期運作的行為。→ 使用 Bug 模板

若不確定，請以「當前行為是否違反規格」來判斷。若違反，則為 Bug。

3. 任務模板

## Goal

<以 1~2 句說明要達成什麼，並簡述為什麼需要>

## Scope

- <要做的事。若有多個任務群組，請使用 **粗體小標題** 分組>

## Out of scope

- <不做的事。明確指出容易混淆的相鄰領域>

## Acceptance criteria

- <可判斷完成的條件。必須是可觀測的形式，例如測試、CI、指令結果等>

## Depends on

- #<編號>

Part of #<父 issue 編號>．

撰寫要點：

• Goal 除了說明「做什麼」，也要加入「為什麼」，讓後續閱讀者能追溯優先級與判斷依據。
• Scope 應以讓實作者不會困惑的粒度撰寫，具體寫出型別名稱、指令名稱、檔案名稱等。若有從先前審查遺留的事項，應使用可識別的小標題區分。
• Out of scope 明確寫出「本次不包含」的內容，以防止範圍膨脹。若真的沒有，則寫 - None，並保留該章節（這樣才能知道「沒有」是刻意寫的，而不是忘記）。
• Acceptance criteria 不應寫「～已實作」，而應寫「～的測試存在且通過」、「CI 中～被執行且成功」等第三者可以確認的形式。
• Depends on 列出需要先完成的 issue，格式為 - #編號（GitHub 會自動顯示標題）。若無，則寫 - None。
• 若是從父 issue 分割出來的任務，請在結尾加上 Part of #<編號>．。
• 只有在有背景資料、參考連結、未決定事項時，才在 Acceptance criteria 之後加入 ## Notes 章節。不要硬湊。

4. Bug 模板

## Summary

<以 1~2 句說明發生了什麼>

## Steps to reproduce

1. <步驟>
2. <步驟>

## Expected behavior

<應該要怎樣才對>

## Actual behavior

<實際上是怎樣。錯誤訊息或日誌請使用程式碼區塊>

## Environment

- Version / commit: <版本或 commit hash>
- <OS / 瀏覽器 / Node 等相關資訊>

## Acceptance criteria

- 按照上述步驟，應得到 Expected behavior 所述的行為
- 新增能夠重現此 Bug 的回歸測試，且該測試通過

## Notes

<原因推測、相關 issue/PR、暫行解決方案等。若無則省略此章節>

撰寫要點：

• 步驟、環境、日誌僅撰寫從使用者處聽到或親自確認的內容。不清楚的項目不要用猜測填寫，應寫 Unknown 或詢問使用者。虛構的再現步驟會誤導調查。
• 原因推測應與事實（Actual behavior）分開，寫在 Notes 中。若將症狀與假設混在一起，當假設錯誤時會讓 issue 難以閱讀。
• 即使修正方針已確定，也應寫在 Notes 中。

5. 標題、標籤、中繼資料

• 標題格式為 <area>: <內容>（例如：core: data types, tree IR, and UI–runtime protocol）。area 應對應 repository 既有的分類（例如 area:* 標籤）。Bug 的標題應描述症狀而非修正內容（例如：runtime: TON timer does not fire after coldReset）。
• 標籤請透過 gh label list 從既有標籤中選取。除了 area 相關標籤外，Bug 還應加上 bug 標籤（若有）。不要擅自建立不存在的標籤。
• 若已知 milestone 或父 issue，請一併設定。
• 標題與內文的語言應與該 repository 既有的 issue 和 PR 一致（可透過 gh issue list --state all --limit 10 與 gh pr list --state all --limit 10 確認）。若既無 issue 也無 PR，則使用日文。
• 章節名稱（Goal、Scope、Summary、Steps to reproduce 等）即使內文為日文，也保持英文。但如果使用 repository 的模板，則直接沿用該模板的標題。

6. 建立 issue

將內文寫入暫存檔，並透過 --body-file 傳遞（以避免 shell 引號導致內文格式錯亂）。

gh issue create --repo <owner>/<repo> \
  --title "<title>" --body-file /tmp/issue-body.md \
  --label "<label>" --milestone "<milestone>"

• 如果使用者明確說「建立」，則直接建立。若只是要求草稿，或內容大多為推測，則應先顯示內文給使用者確認後再建立。
• 若有父 issue，除了在內文中加入 Part of #N． 之外，也應透過 GitHub 的 sub-issue 功能進行關聯（使用 gh api 呼叫 POST /repos/<owner>/<repo>/issues/<父編號>/sub_issues，sub_issue_id 應傳入子 issue 的 id 而非編號）。若 API 無法使用，僅在內文中描述即可。
• 若要建立多個分割 issue，請從被依賴者開始依序建立，確保 Depends on 中填入的是實際的編號。
• 建立完成後，回報 issue 的 URL 給使用者。