Community生產力與協作github.com

write-issue

將問題(錯誤、功能或任務)的描述寫入專案 issues 資料夾中的 CommonMark 檔案,方便複製到問題追蹤系統(Redmine、GitHub、GitLab)。當使用者描述待解決問題或待辦任務並希望準備 issue 時使用。

write-issue 是什麼?

此技能會根據使用者的描述(`$ARGUMENTS` 及對話內容)產生 issue 的文字內容,並以 CommonMark 格式寫入專案根目錄下的 `issues/` 資料夾。產生的檔案包含標題、上下文、描述、重現步驟(僅限錯誤)、預期行為、驗收條件、技術備註和參考資料等章節,方便使用者直接複製貼上到 Redmine、GitHub 或 GitLab 等問題追蹤系統。 技能執行時會先確保 `issues/` 資料夾存在且有正確的 `.gitignore`,然後分析使用者請求,將其分類為錯誤、功能或任務,並透過查閱專案程式碼來驗證描述的真實性。若資訊不足或有矛盾,技能會一次性地向使用者提問澄清,避免產生不完整的 issue。 **重要限制**:此技能僅負責產生 issue 文本,**絕不直接操作**問題追蹤系統——不允許任何寫入、修改、刪除、評論或狀態變更的操作,僅能使用 `GET` 請求或唯讀命令(如 `gh issue view`、`gh issue list`)。使用者需自行將產生的 issue 複製到問題追蹤系統中建立正式 issue。 此技能適用於任何開發專案,支援常見的問題追蹤平台,特別適合需要標準化 issue 格式且避免 AI 誤操作正式系統的情境。產生的檔案命名規則為 `issues/<YYYY-MM-DD>-<slug>.md`,使用者建立 issue 後可將檔案重新命名加上 issue 編號以便後續查閱。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/gabriele-murara/team-skills/tree/HEAD/plugins/issues/skills/write-issue

Installed? Explore more 生產力與協作 skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

撰寫 issue

根據使用者的描述($ARGUMENTS 及對話內容)準備 issue 的文字內容。使用者會將文字複製到問題追蹤系統中,並在那裡建立 issue、設定負責人、優先順序、版本等。此技能不會在問題追蹤系統上建立 issue。

問題追蹤系統:僅限讀取

在問題追蹤系統(Redmine、GitHub、GitLab)上,AI 只能讀取 issue。絕對不得修改它們,即使使用者提出要求也不行:

  • 不得建立、修改、關閉、重新開啟或刪除 issue;
  • 不得新增留言、備註、附件、記錄工時;
  • 不得變更狀態、負責人、優先順序、版本、標籤。

僅使用讀取請求:不帶 -X 或資料的 curl(即 GET)、gh issue view、gh issue list。絕對不得使用 POST、PUT、PATCH、DELETE,也不得使用 gh issue create、edit、comment、close、reopen、delete 等指令。如果需要將文字寫入問題追蹤系統,請將其寫入 issues/ 資料夾中的檔案,由使用者自行複製。

1. issues 資料夾

在專案根目錄(若存在 git 倉庫則為其根目錄)下,必須存在 issues/ 資料夾,內含一個忽略所有內容(除了自身)的 .gitignore 檔案:

*
!.gitignore

如果缺少資料夾或 .gitignore,請建立它們。如果 .gitignore 已存在但內容不同,請勿修改,並通知使用者。

2. 資訊收集與驗證

  1. 將請求分類為:錯誤、功能 或 任務(維護、更新、重構、文件等)。
  2. 在專案程式碼中驗證描述:搜尋提及的檔案、類別、路由、資料表及行為,確認它們存在且運作正常。記錄涉及的檔案。
  3. 找出遺漏或模糊的資訊,例如:
    • 錯誤:重現步驟、預期行為與實際行為、環境(正式、測試、本機)、錯誤訊息或日誌;
    • 功能:使用者對象、應能執行的操作、邊界情況、限制條件;
    • 所有類型:判斷 issue 已解決的標準。
  4. 如果缺少必要資訊,或程式碼與描述不符,請先詢問使用者。將所有問題一次提出,且只問真正需要的內容。

請勿提出或實作解決方案:issue 只需要描述問題與預期結果。技術備註僅供後續處理人員參考。

3. 檔案寫入

將檔案寫入 issues/<YYYY-MM-DD>-<slug>.md,其中 slug 為全小寫標題,單字間以 - 分隔,不含特殊字元(最多 50 個字元)。如果檔案已存在,則加上 -2、-3 等後綴。

檔案結構:

# <簡短且具體的標題>

## 背景

[問題或任務的所在位置及其必要性。]

## 描述

[錯誤:當前行為。功能/任務:需要完成的事項。]

## 重現步驟

1. [...]

## 預期行為

[...]

## 驗收條件

- [ ] [可驗證的條件]

## 技術備註

- `檔案/路徑` — [相關原因]

## 參考資料

- [連結、相關 issue、日誌、螢幕截圖]

規則:

  • 重現步驟 僅限錯誤類型使用;預期行為 適用於錯誤與功能。若 技術備註 或 參考資料 為空則可省略。
  • # 標題 這一行對應問題追蹤系統的標題欄位;其餘從 ## 級別標題開始的內容則放入描述欄位。
  • 使用 CommonMark 格式;程式碼與日誌需使用含語言標記的程式碼區塊。
  • 語言:繁體中文。不使用表情符號。
  • 文字簡潔明確,讓未參與對話的人也能理解:避免使用「如上述所提」或提及當前會話。

4. 回應使用者

告知使用者:

  • 建立的檔案路徑;
  • 建議的標題與類型(錯誤、功能、任務);
  • 在問題追蹤系統中建立 issue 後,建議將檔案重新命名,加入 issue 編號(例如 issues/123-<slug>.md):這樣即使無法連線問題追蹤系統,open-issue 123 也能找到該檔案。

相關技能