skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
ashe-li/agent-skills53 installs

pr

總結當前工作、commit、推送並建立或更新 PR。自動將對話脈絡寫入 PR description,確保 reviewer 能快速理解背景。

How do I install this agent skill?

npx skills add https://github.com/ashe-li/agent-skills --skill pr
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill is a robust PR management tool that includes multiple safety features such as base branch protection, automated security reviews, and manual user confirmation steps. It possesses an indirect prompt injection surface as it processes external data from Git logs and GitHub PR descriptions, though this is managed via human-in-the-loop checkpoints.

  • Socketpass

    No alerts

  • Snykwarn

    Risk: MEDIUM · 1 issue

  • Runlayerpass

    1 file scanned · No issues

What does this agent skill do?

/pr — 總結工作並維護 PR

請依照以下步驟執行:

Step 1: 分析當前工作

1a. Git 分析

  1. 執行 git status 和 git diff(staged + unstaged)了解未 commit 的變更
  2. 執行 git log 查看近期 commit 風格
  3. 關鍵步驟 — 同步遠端並確認 PR 完整範圍:
    • 先執行 git fetch origin(⚠️ Stale Local Branch 陷阱:本地的 master/main/hotfix 可能落後遠端數十個 commits,忘記 fetch 會把已經 merge 的 commits 算進 PR 範圍,導致 description 嚴重失準)
    • 執行 git log --oneline origin/<base-branch>..HEAD 查看 PR 包含的所有 commits(永遠用 origin/<base-branch> 比較,不要用本地 <base-branch>)
    • 執行 gh pr diff <PR-number> --name-only 查看 PR 涉及的所有檔案
    • 如果已有 open PR,執行 gh pr view <PR-number> --json body 讀取現有 description
    • 交叉驗證: 比對 git log 結果與 gh pr diff 結果,若差異過大(例如 git log 顯示 50+ commits 但 gh pr diff 僅 1-2 files),以 gh pr diff 為準並重新檢視

1b. 對話脈絡分析

回顧本次對話的完整內容,提取以下 context 項目(這份清單是本 skill 唯一權威清單,Step 5 撰寫 PR description 時逐條比對,不重新定義):

  1. 動機:使用者最初提出的問題或需求是什麼?
  2. 討論過程:過程中探索了哪些方案?做了哪些比較或調查?
  3. 決策點:哪些地方有多個選擇?最終為什麼選擇這個方案?
  4. 放棄的嘗試:有沒有試過但放棄的做法?為什麼放棄?
  5. 隱含知識:對話中出現但不會反映在 diff 裡的重要 context(例如:調查數據、外部工具比較、效能考量)
  6. 業界/學術依據:技術決策是否引用業界標準(RFC、OWASP 等)或學術研究?
  7. 社群共識與反面意見:對話中是否討論過社群主流看法、已知的反面意見或陷阱?
  8. Ticket 參照:掃描對話中是否出現 [A-Z]+-\d+ 編號(如 JIRA-123)、Notion URL、或「Notion Ticket」字樣,記錄找到的編號與票名(供 Step 5 PR 標題使用)
    • Linear ticket(強制):先推斷 team key:從當前 branch 名 <type>/<team>-<number>-<slug>(git branch --show-current,如 fix/abc-1234-...)或 repo 既有 commit/PR 標題帶的票號格式取得,推斷不出來就問使用者,不要掃任意 [A-Z]+-\d+(會誤判 UTF-8 這類字串)。有了 team key 之後,掃這四個來源的 <TEAM>-\d+(大小寫不拘):對話內容、當前 branch 名、origin/<base-branch>..HEAD 的 commit message、既有 PR 的 title/body。命中後一律正規化成大寫 <TEAM>-<number>(如 ABC-1234),只記在這條、不重複列進上面的通用 ticket 清單,記進 Context Manifest,並往下傳給 Step 3.5(branch 命名)與 Step 5(PR 標題)。有多張就全部列出
    • 只算這次工作對應的票:舉例、引用別的 PR 標題、blocked by/相關票這類順帶提到的編號不算。對話裡出現多個編號、又分不出哪張才是這次的工作,用 AskUserQuestion 讓使用者選,不要猜

Step 1b 結束時建立「Context Manifest」,供 Step 5 逐條比對:

## Context Manifest(Step 1b → Step 5 交接)

| # | Context 類型 | 摘要 | 已寫入 PR Description? |
|---|------------|------|------------------------|
| 1 | 動機 | 使用者原始需求 xxx | 待比對 |
| 2 | 放棄的方案 | 考慮過 A 但因 B 放棄 | 待比對 |
| 3 | 決策依據 | 選 X 不選 Y,因為 Z | 待比對 |
| ... | ... | ... | 待比對 |

expected_count = N(對話中識別的 context 項目總數)

1c. 總結

綜合 git 分析 + 對話脈絡,總結本次工作的目的、做了什麼、為什麼這樣做。

Step 2: Quick Review

對所有變更進行快速 code review,檢查以下項目:

檢查清單

  • 安全性:是否有敏感資訊外洩(API keys、secrets、.env 內容)
  • 正確性:邏輯是否正確、有無明顯 bug
  • 遺漏:是否有 debug code(console.log、debugger)未清除
  • 型別:TypeScript 型別是否正確、有無 any 濫用
  • 樣式:是否符合專案既有 coding style
  • 視覺驗收面:變更是否觸及 UI 視覺/互動行為?觸及則列出「待截圖驗收項目」草稿(一項一個可判 PASS/FAIL 的斷言),交給 Step 5.5 收尾;未觸及則明示「無視覺面,Step 5.5 將跳過」

主動安全審查(依 rules/security-guidance/skill-integration.md 的觸發閘)

判斷變更是否觸及安全敏感面(認證/輸入/endpoint/DB/反序列化/檔案/shell/SSRF/DOM/加密,定義見上述文件):

  • 觸及 → 委派內建 /security-review skill 審查當前 branch 的 pending changes,判準以 ~/.claude/claude-security-guidance.md 為準;findings 併入下方輸出,CRITICAL/HIGH 在「互動確認」中提示先修正
  • 未觸及 → 明示「無安全敏感面,跳過」
  • 若從 /update 串接:Step 2 已含安全審查,此處不重複委派(去重)。但**「視覺驗收面」判定不在 /update 涵蓋範圍**——即使跳過本步驟其餘檢查,該判定仍要做(或由 Step 5.5a 直接從 gh pr diff --name-only 補判),否則 Step 5.5 會無輸入而誤跳過

輸出格式

用簡潔的表格或清單呈現 review 結果:

  • ✅ 沒問題的項目一句帶過
  • ⚠️ 有疑慮但不阻擋的項目說明原因
  • ❌ 必須修正的問題列出檔案和行號

互動確認

Review 完成後,使用 AskUserQuestion 詢問使用者:

  • 繼續 PR 流程:review 結果沒問題,繼續 commit → push → PR
  • 先修正問題:先處理 review 發現的問題,修完再重新執行 /pr

如果使用者選擇「先修正問題」,則根據 review 結果逐一修正,修正完後重新從 Step 1 開始。

Step 2b: 自動修正

若 Step 2 發現可自動修正的問題(dead code、命名、nesting、重複程式碼),委派內建 /simplify skill 執行;未發現則跳過。

Step 2c: Plan 歸檔檢查

在 commit 之前,若本次對話涉及的 plan 已完成(plans/active/*.md 的 Status 為 COMPLETED/完成,或所有 Phase/Step 皆標記 [x]/✅),呼叫 /plan-archive skill 歸檔至 plans/completed/;沒有已完成的 plan 則跳過。

Step 3: Commit 當前變更

  1. 如果有未 commit 的變更,根據變更內容撰寫 commit message
  2. 使用 conventional commits 格式(feat / fix / chore / refactor / test / docs),英文撰寫
  3. 確保不要 commit 敏感檔案(.env, credentials 等)

Step 3.5: Linear ticket 與 branch 名(Step 1b 有找到 Linear ticket 才做)

branch 名要帶 ticket,格式 <type>/<team>-<number>-<kebab-slug>(例:fix/abc-1234-editor-toolbar-keyboard-sticky),<type> 沿用 conventional commit 前綴。沒找到 Linear ticket 就跳過本步驟。

當前狀態動作
branch 名已含 <team>-<number>(大小寫不拘)符合,直接進 Step 4
還在 base/long-lived branch 上(main、master、hotfix、develop*、release-*)直接用上面格式開新 branch,不要改 long-lived branch 的名字
自己的 branch、還沒推上遠端也沒有 PR用 AskUserQuestion 提議 git branch -m <新名>,選項「改名(推薦)」/「維持原名」
已推上遠端或已有 PR不改名(重推新名會讓既有 PR 斷掉),ticket 改由 PR 標題承載,Step 6 回報時註明 branch 名沒帶 ticket

Step 4: 推送到遠端

有 remote tracking branch 用 git push;沒有則 git push -u origin <branch> 建立。有 profile(/verify-change Step 1 回 MATCH)且引擎可用時,push 前先在最終 HEAD 跑 $E checks($E 的定義與工作樹須乾淨的限制見該 skill Step 2);沒有 profile 或引擎不可用,照現行流程,行為與現在完全相同(下方 pr register、receipt ci、UI 判定的接線同此)。

Step 5: 建立或更新 PR

Base Branch 防護(強制執行)

PR 的 base branch 禁止直接指向主要的 production branch(如 master、main)。

執行以下檢查:

  1. 讀取專案的 branch 策略(如果有 skills/git-workflow/SKILL.md 或類似文件)
  2. 如果專案有定義預設的 base branch(如 hotfix、develop),自動使用該 branch
  3. 如果使用者明確要求指向 master 或 main → 必須中斷並警告:
    • 使用 AskUserQuestion 提醒:「依照專案規範,PR 不建議直接指向 master/main。確定要繼續嗎?」
    • 提供選項:「改為 [專案預設 base branch](推薦)」/「我確定要指向 master/main」
    • 只有使用者明確確認後才能繼續
  4. 如果專案沒有特別的 branch 策略,使用 repo 的 default branch

CHANGELOG 檢查(Release PR 專用)

當 base branch 為 master 或 main 時,必須檢查 CHANGELOG.md:

  1. 確認專案根目錄是否有 CHANGELOG.md
  2. 如果有,檢查最新條目是否涵蓋本次 PR 的變更:
    • 讀取 CHANGELOG.md 最新版本區塊
    • 比對 git log origin/<base-branch>..HEAD --oneline 的 commits
    • 如果有 commits 未被記錄在 CHANGELOG 中 → 使用 AskUserQuestion 提醒:

      CHANGELOG.md 尚未包含以下變更:

      • <未記錄的 commit 摘要>

      1. 幫我更新 CHANGELOG — 自動補上缺少的條目
      2. 跳過 — 不更新 CHANGELOG,繼續 PR 流程
  3. 如果專案沒有 CHANGELOG.md,跳過此步驟

PR Title 格式

依據 base branch 和 ticket 參照決定 PR 標題:

Release PR(base branch 為 master/main)

當 PR 的 base branch 為 master 或 main 時,標題必須使用 Release 格式:

  • 格式:Release vX.Y.Z: <摘要>
  • 版本號推斷優先順序:CHANGELOG.md 最新版本 → package.json version → git tag
  • 摘要從 PR 包含的 commits 中提取主要變更,簡短描述即可
  • Step 1b 有找到 Linear ticket 時,把編號全部附在標題尾巴:Release v1.18.0: <摘要> (ABC-1234 ABC-1235)

更新既有 PR 時,也必須檢查 title 是否符合此規則,不符合則一併更新。

一般 PR(base branch 非 master/main)

使用 Step 1b 提取的 ticket 參照決定 PR 標題:

  • 有找到 Linear ticket → 標題必須帶字面上的 <TEAM>-<number>,只寫票名不算數。預設放在尾巴:fix(kyc): 注意事項清單改 inline style (ABC-1234)。若 repo 慣例是寫進 scope(fix(ABC-1234): ...)也可以。多張票全部列出:(ABC-1234 ABC-1235)
  • 有找到其他 ticket(不含 Linear ticket,Linear ticket 一律走上一條)→ 標題必須包含 ticket 資訊,二擇一:
    1. 標題末尾附上 ticket 編號:fix(seo): add noindex for empty about page (TICKET-1234)
    2. 標題包含票名:fix(seo): [Bug] empty about page should be no-indexed
  • 沒找到 ticket → 正常標題,不需額外處理

更新既有 PR 時,也要檢查 title 有沒有漏掉 Linear 票號,漏了就用 gh pr edit --title 補上。

判斷邏輯

  • 如果提供了 PR 號碼($ARGUMENTS),更新該 PR
  • 如果沒有提供號碼,檢查當前 branch 是否已有 open PR
    • 有 → 更新該 PR description
    • 沒有 → 建立新 PR(使用專案規範的 base branch)
  • 建立或更新 PR 之後(含更新既有 PR)一律跑 $E pr register --repo . --from-gh,把 PR 登記進本機註冊表

PR Description 格式

PR description 必須包含以下區塊,使用繁體中文撰寫:

## Summary

<!-- 1-3 句話說明這個 PR 的目的和背景脈絡,讓 reviewer 30 秒內理解「為什麼要做這件事」 -->

## Context(對話脈絡)

<!-- 最重要的區塊。內容依 Step 1b 的 Context Manifest 逐條寫入,來源優先序:對話脈絡 > git diff > commit messages -->
<!-- 目標:reviewer 不需要問「為什麼這樣做?」就能從這裡找到答案 -->

## Changes

<!-- 按主題分類列出變更,涵蓋 PR 的所有 commits(不只是當次對話的工作) -->
<!-- 用 git log origin/<base-branch>..HEAD 確認完整範圍(必須先 git fetch origin) -->
<!-- 用 git diff origin/<base-branch>..HEAD --diff-filter=D --name-only 確認刪除的檔案 -->
<!-- 每個主題明確標示:新增了什麼、刪除了什麼、修改了什麼 -->
<!-- 非本次對話親自做的 commit(跨 session 的 branch、更新既有 PR):條目須對 git diff 核實,commit message 只用來定位、不當證據;核不到的標「無法佐證」 -->

## Test plan

<!-- 測試計畫,checkbox 格式 -->
<!-- 若 Step 2 判定有視覺面,此處列出待截圖驗收的編號項目(B1/C1…),並在 Step 5.5 完成後回頭勾選;
     移除/重構類不要列截圖項,改列量測項(grep 殘留、bundle diff、目錄不存在) -->

模板不含署名行。commit 的 Co-Authored-By 與 PR 描述的「Generated with Claude Code」要不要加,依使用者的 Claude Code attribution 設定,不由本 skill 決定。

Manifest 逐條比對: 撰寫完 Context 區塊後,逐條比對 Step 1b 的 Context Manifest,確保每個項目都已反映;差集(expected_count − actual_written)> 0 的項目必須補齊,不可遺漏。

Evidence Gate(寫回前,強制)

description 定稿後、執行 gh pr create/gh pr edit 前,呼叫 evidence-gate skill 過關卡:commit range 固定 origin/<base-branch>..HEAD(沿用 Step 1a 已 git fetch origin 的範圍),description 每條事實宣稱拆成該 skill 第 1 節的 Claim Schema,證據一律溯源 git diff/git log --numstat,commit message 僅供定位不當證據;並依其第 4 節派 fresh-context subagent 對抗性複驗。零 FAIL 且零 SCHEMA-DEFECT 才可繼續下方 gh pr create/gh pr edit;任一 FAIL 或 SCHEMA-DEFECT 回本節修正 description,不寫回 PR。

Skill({ skill: "evidence-gate" })

Step 5.2: CI 收集檢查(變更的測試真的被跑到嗎)

「CI 綠但新測試沒被跑到」發生過至少七次(selective CI 沒收錄新 spec、glob 沒涵蓋、job 被跳過),綠燈證明不了,要比對識別碼。放在 Step 5.5 之前:Test plan 的 CI 項目要先定稿,5.5 才回填。

觸發:git diff --name-status origin/<base>...HEAD 有狀態 A、M、R 的測試檔(有 profile 取其 Tests glob,沒有就用 test_*.py、*_test.*、*.test.*、*.spec.*)。沒有就明示「無變更測試,跳過」。

  1. 把變更測試的識別碼(要與 log 列出的同一種形狀,如 pkg.mod.Cls.test_x 或檔案路徑)一行一個存到 .verification/<date>/changed-tests.txt。

  2. 取 PR head SHA 那次 run 的 log:gh run list --commit <head-sha> 找 run,對 profile 的 Required-jobs(沒有就取跑測試的 workflow)gh run view <id> --log > .verification/<date>/ci-<job>.log。重試過的只取最後一次 attempt(--attempt <N>)。

  3. 比對(matrix 各 job 的 log 全部帶上;profile 有 List-pattern 就改用 --pattern,但自訂樣式不做跳過偵測,見契約的 List-pattern;細節見 --help):

    python3 scripts/ci_collected.py ids --ids-file .verification/<date>/changed-tests.txt \
      --log .verification/<date>/ci-<job>.log --runner unittest   # 或 pytest/jest/playwright
    
  4. 只有 PASS 才能在 Test plan 勾「變更的測試已在 CI 執行」;FAIL 列出 NOT-FOUND 與 SKIPPED(log 有列出但被跳過,不算已執行)並回頭修;UNVERIFIABLE 照實寫並附原因(如 log 不列識別碼),不寫「CI 綠」。checks 還在 pending 時留一條未勾選項並明講「CI 未跑完,收集狀況待確認」。

  5. 要附總數比較時(輔助,不能單獨當 PASS):count --before <base log> --after <head log> --pattern <Count-pattern>;base 取 PR merge-base SHA 的 run、同一個 workflow 與 job,matrix 各 job 先去重再加總;找不到符合的 base run 就寫 UNVERIFIABLE。

腳本不存在時照同樣步驟手動比對 log。取得結果後,有 profile 時跑 $E receipt ci --from-gh;CI 還沒跑完加 --pending-declared,回報明講「CI 未跑完,未宣稱完成」。

Step 5.5: 截圖驗收 gate(PR 已存在後執行)

PR 建立/更新完成後,判斷本次變更是否需要截圖驗收,需要就用 AskUserQuestion 取得授權再跑。 這步在 Step 5 之後才做:截圖要貼成 PR comment,PR(與 preview env)不存在就沒有落點。

適用範圍不限於由 /pr 建立的 PR。 若 PR 由派工 agent 或手動 gh pr create 建立, 派工者仍須在 PR 存在後補跑本步驟——委派出去的是工作,不是責任。 這個 gate 只寫在 /pr 裡,所以繞過 /pr 的路徑會讓它靜默消失; 而「請 agent 開 PR」正是最常見的繞過方式。

特別要抓的一種狀態:截圖已經拍了、trace 也存了,但全部落在 .verification/ 之類的本機路徑。 證據存在卻停在 reviewer 打不開的地方,等同沒有證據——這正是 /pr-evidence-comment 要解決的問題本身。

5.5a 分類(沿用 /pr-evidence-comment Step 0 的同一張表)

以 Step 2 的「視覺驗收面」判定與 gh pr diff <PR> --name-only 為依據分類(有 profile 時 UI 與否以 profile 的 Paths UI/UI-exclude 為準,以 $E select 印出的 ui 判定為準):

變更類型驗收手段本步驟動作
UI 視覺/互動行為headed 截圖進 5.5b 詢問
狀態遷移後「行為不變」截圖(證沒壞)+ 量測(證真的遷了)進 5.5b 詢問,並提醒量測項不可省
純移除/重構量測(grep 殘留、bundle diff、目錄不存在)不問截圖,直接提示補量測項到 Test plan
API/資料正確性curl/測試輸出不問截圖,直接提示補測試輸出
純文件/設定/CI無明示「無視覺面,跳過」

5.5b 互動確認(AskUserQuestion)

判定為「需要截圖驗收」時,必須用 AskUserQuestion 詢問,不可自行決定跑或不跑(會開瀏覽器、要人工登入、且會以使用者身分公開發 comment)。

問題帶上:偵測到的視覺面變更檔案、Step 2 草擬的驗收項目編號清單、以及可用的驗收環境(preview URL/staging/local)。選項:

  1. 現在就驗(推薦) — 委派 /pr-evidence-comment,帶入驗收項目清單與環境 URL
  2. 只列清單,我自己驗 — 把編號清單寫進 PR 的 Test plan(未勾選),不開瀏覽器
  3. 這次不需要 — 記錄理由並在 PR 補一句說明為何免視覺驗收

環境判定:base 為專案預設分支且 repo 有 preview 部署慣例時,先確認 preview env 是否就緒(例如 PR 需要特定 label 才部署)。未就緒不要硬跑——改問使用者要「等 preview 好了再驗」還是「先用 local 驗」。

5.5c 執行與回填

使用者選 1 → 用 Skill tool 委派:

Skill({ skill: "pr-evidence-comment" })

該 skill 跑完(截圖已上傳、gh pr view 驗證過 user-attachments 數量相符)後回到本步驟:

  • 把逐項 PASS/FAIL 結論回填 PR description 的 Test plan(勾選已驗項目)
  • FAIL 項目不可當成「已驗收」帶過——列出來並回到修正流程
  • 驗收結論同時回貼 PR comment(由該 skill 完成),對話裡只做摘要
  • 這次回填不必重跑 Step 5 的 evidence-gate:證據就是剛產生的截圖與 comment 連結,回填時直接引用;但 Test plan 只能寫實際驗過的項目,未驗的維持未勾選

使用者選 2 或 3 → 依選項寫回 Test plan/說明,不呼叫該 skill。

Step 6: 確認結果

  1. 輸出 PR URL
  2. 確認 PR description 已更新
  3. 回報 Step 5.5 的結果:已截圖驗收(附 comment 連結)/已列清單待人工驗/判定免驗(附理由)/無視覺面
  4. 回報 Linear ticket 放在哪裡:偵測到的編號與出處、PR 標題有沒有帶、branch 名有沒有帶。沒帶的話講原因(例如 branch 已推上遠端,不改名)。沒找到就明說「未偵測到 Linear ticket」
  5. 如果有相關的其他 PR(如 feature → develop、develop → master),檢查是否需要同步更新

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/ashe-li/agent-skills/pr">View pr on skillZs</a>