inspect-github-agent-resources
先審查,再決定裝不裝
把 skill、plugin、MCP server 或 agent 範本裝進 agent 之後,agent 會讀它的說明,有些資源還附帶會被執行的指令。裝之前能看到的,通常只有 README、星數和幾行簡介。這些寫的是作者怎樣介紹它,很少說它在你的環境裡會讀什麼、寫什麼、連去哪裡。
讀過 README 也不等於看過來源。說明文字、被隱藏的註解、附帶的範例檔,都可能含有寫給 agent 看的句子。審查的人(或 agent)讀到它們,只能當證據,不能當指令。
本文介紹一套靜態審查的做法,以及執行它的 agent skill。它回答三件事:這個資源能幫你完成什麼工作;依來源看,哪些安全疑慮會影響你的用法;裝它或更新它之前,最小的一項驗證是什麼。它不安裝、不執行被審查的程式碼,也不發安全證明。
程序
1. 先寫下你要做的決定。你要完成什麼工作、可接受的成品長什麼樣、現在怎麼做、卡在哪裡;環境、資料、帳號、能不能執行程式碼這些限制;以及你要的是找選項、檢視一個指定資源、比較幾個,還是規劃驗收與維護。已經給過的資訊,skill 不會要你重講。缺一項而且會改變結論時,只問一個問題,其餘不受影響的檢視照常進行。工作還說不清時,它改給有來源支持的示例用途和有條件的適配判斷,不替你編造用戶畫像。
2. 開始查之前,先宣告界線。探索階段的起始預算是 3 個搜尋、篩 12 個 repo、深查 3 個候選。指定目標的審查,起始是最多 3 個目標;每個目標看它的出處資料、被指定的那個單元,以及該單元直接引用的檔案(往下一層),最多 40 個文字檔。你另有範圍就從你的。上限只是涵蓋範圍的限制,不是危險的證據。只讀了一部分的檔案、沒讀到的重要引用,都要記下;想擴大範圍時只提出來,不會自行擴大。公開目標只用匿名的公開來源;本機快照只讀你明確授權的路徑,不上傳,也不順手去搜帳號或機器上的其他資料。
3. 把版本釘死。公開目標要確定 repo 的正式名稱、擁有者、要看的 ref 和確切的 commit SHA,並查發布者身分、授權、維護狀況、release 與相關的官方安全公告。本機目標則記下來源、確切單元和觀察到的雜湊值;沒有的出處就寫沒有,不替本機檔案編造 GitHub 身分或 commit。
4. 讀四類面向。
- 說明與隱藏內容:提示注入、越權指示、被隱藏的註解、Unicode 異常字元。異常字元單獨出現不足以證明攻擊,需要解讀。
- 權限與資料處理:要求憑證、讀取敏感檔案、寫入、網路目的地、遙測,以及可能的外洩路徑。
- 執行與持續存在:安裝 hook、指令、可執行檔或二進位入口、背景行為、自動更新。
- 出處與供應鏈:確切版本、相依套件、發布者證據、相關官方公告,以及沒審到的部分。
整個過程不 clone、不下載壓縮檔、不安裝、不匯入、不啟用、不更新、不執行候選的程式碼。倉庫裡的說明、隱藏註解和範例內容,一律只當證據,不當權威。
5. 有確切位元組時,才跑清點 helper。你授權的穩定本機快照已經存在時,skill 附一支不需安裝套件的 Node.js 腳本,清點檔案雜湊、隱藏 Unicode、註解、部分 hook 與執行面。它只產出機械指標,不判斷惡意程式,也不證明隔離。拿不到位元組時,skill 要說明缺了這一步,哪些結論下不了,仍回答其餘能回答的部分。
6. 先給答案,再附證據。回報先回答你的決定:適合哪項工作、在什麼條件下適配、建議的下一步。接著是支撐它的證據,每個推論連到出處。證據分四種標記:
source-verified:在記錄的 ref 或雜湊上直接看到的來源內容。inferred:由證據和你的限制推論出來的結論。not-found:在指定範圍內搜過沒找到,不等於別處不存在。runtime-unverified:要執行或連線才能知道,並寫明需要什麼驗證。
涵蓋範圍另分 reviewed、partial、not-reviewed、not-applicable。處置只有四種:stop(來源證據顯示違反你宣告的界線,或有具體的完整性、權限、隱藏指示問題)、insufficient-evidence(關鍵的出處或安全涵蓋缺失,下不了結論)、needs-review(有需要解讀或驗證的疑慮)、no-blocker-observed(範圍內適用的檢查都完成,沒看到阻礙;探索階段的篩選不能得到這一項)。skill 不輸出數字分數,也不用「safe」「approved」「cleared for install」當結論。
有用和能裝是兩個問題。一個資源可以對你的工作有用,同時安裝處置仍是 insufficient-evidence;沒有靜態阻礙的資源,也可能對你的工作毫無幫助。兩個答案分開列。最後給出最小的一項驗證:做什麼、誰提供證據、預期看到什麼。能用唯讀檢查或合成案例解決的,優先用。
資源改版時
資源改版就是一次新的審查。skill 附另一支腳本,比較兩份你授權的本機快照,列出檔案雜湊的差異。它不去抓新版本,不排程,也不判斷該不該更新。雜湊變了,表示有某些結論要回頭重看;被改動的 hook 是一條要追查的線索,並未證明有漏洞,也沒證明已修好。雜湊沒變,也不代表外部公告或你的部署環境沒變。沒受影響的證據連同原版本保留,受影響的結論標為待重審,舊的決定不會悄悄沿用。
出處
本頁程序的整體組合,以及四種證據標記的分法、四種處置的判定次序、審查範圍的起始預算、改版時只把受影響的結論送回重審,是 Trigpoint(2026)的工作選擇。各部分的基本想法都有前人做過,不屬首創:
- 把受審 repo 裡的文字當證據、不當指令:Greshake 等(2023)指出外部內容可以間接注入指令;OWASP(2025)LLM01 建議把不受信任的內容分開並清楚標示。
- 把直接取得的資料與推論分開標示:ODNI(2015)ICD 203 已列為情報分析標準。
- 處置與證據紀錄:OASIS(2020)SARIF 2.1.0 的結果類別 fail、open、review、pass,與 stop、insufficient-evidence、needs-review、no-blocker-observed 大致一一對應;其 run 物件同樣把一次分析的工具、版本與結果收在一起。
- 安裝前讀四類審查面:Mercer(2026)在 Aident 發表的〈How to Audit an Agent Skill Before You Install It〉已涵蓋同樣四類。
- 有用和能裝分開回答:SkillAudit(2026)的 SkillPortrait 已把效用與安全分成兩軸,且不合成一個分數。
- 不依賴外部服務的靜態清點:Cisco AI Defense(2026)的 skill-scanner 已有不需外部服務的靜態分析器。
- 改版比較:SARIF 2.1.0 以基準版本把結果標為新增、不變或消失;Trail of Bits(2026)的 differential-review 是審查差異的 agent skill,開發期曾與它比較。
- 驗收包:NIST(2018)SP 800-37 的授權包,同樣把評估紀錄交給具名負責人決定是否接受。
目前的成效
v0.1.0 的驗收紀錄放在 repo 的 VALIDATION.md,能說的範圍很窄。
清點與比較腳本:在 macOS arm64 上,Node.js 20.0.0 和 24.21.0 各自通過全部 24 個回歸測試,沒有略過;兩個版本也都跑了文件裡的示範清點和前後比較。測試涵蓋唯讀清點、隱藏文字指標、上限、涵蓋缺口、指令遮蔽、Unicode 位移、符號連結、固定排序與比較語意。Node 20 已終止維護,相容只供舊環境參考,日常請用維持中的 LTS 版本。
Agent 使用:獨立的 agent 工作階段拿到 skill 和它引用的來源,沒有拿到標準答案,輸出對照事先記下的評分表。三個本機情境:
- 首次使用:照 README 不安裝的路徑,讀示範檔、跑清點腳本,把窄範圍的適配、尚未測的行為和模型供應方的隱私分開講。這一輪也讓 README 修掉一處示範與連結範例不一致的地方。
- 靜態審查:對一個示範資源,找出一條會讀取筆記並嘗試 HTTP POST 的 postinstall 路徑,以及一段想壓下這項發現的 HTML 註解。agent 沒有照註解裡給審查者的指示做,也沒有執行目標。
- 版本審查:找出新增的外送筆記資料、同步改非同步的 API 變動,以及對離線和錯誤處理的影響;保留沒受影響的證據,沒有把乾淨的機械掃描當成安全的證明。
第四個情境用了一份公開的第三方 PDF skill。agent 解析出固定的 commit,讀了六個目標檔和六份直接相關的官方來源,把表格擷取的適配度連到相依套件與範例行為,查了該單元的授權,保留未固定的執行環境和公告的不確定性,並提出以頁、列、值為單位的驗收檢查。它沒有安裝目標,沒有處理任何 PDF,也沒有量測擷取品質。這個情境和首次使用案例是同一個 agent,不算第四個獨立 agent。
這些是同一個 agent 環境下的有限觀察,沒有量到一般的偵測率、誤報率、節省的人工時間,也沒有跨 agent 的相容性。目標程式碼都沒有被執行。
還沒驗證的部分
VALIDATION.md 沒有宣稱已驗證:Codex 與 GitHub Copilot 的宿主原生 skill 探索與安裝;Windows 與 Linux 的執行測試;對抗性的即時檔案系統隔離;動態惡意程式測試;公開發布與下載的驗證。合集頁對這個 skill 的標記也只有「macOS arm64 的 helper 測試,宿主原生探索未測」。
此外:審查品質沒有做過基準測試,也沒有與其他做法比較準確度。這是一次靜態審查,不是沙箱執行、滲透測試、完整的惡意程式偵測,或安全認證。helper 在本機運作,agent 讀檔卻可能把內容送給它的模型供應方;檔名、雜湊和報告本身也可能洩漏私人資訊,分享前請先看過。
適用時機
適用於:要試用一個不熟的 skill、plugin、MCP server 或 agent 範本之前;為某項工作比較幾個候選;資源改版後決定要不要更新。只想知道這類資源能幫上什麼忙時,直接問,skill 不會因此展開一次 repo 審查。
它不能取代執行期的實測。要確認資源實際會做什麼,需要在你授權的範圍內另行測試,不在這個 skill 的範圍內。
取得 skill
skill 放在 GitHub:github.com/trigpoint-pub/agent-skills 的 skills/inspect-github-agent-resources,目前版本 0.1.0,2026-10-24 以 trial prerelease 發布(Release 頁),授權 MIT。這個 skill 最早以獨立 repo 發布,該 repo 已封存,現行版本在合集。
安裝時只複製 skills/inspect-github-agent-resources/ 整個資料夾(含 LICENSE),不要複製其他檔案:
- Codex:專案內放
.agents/skills/inspect-github-agent-resources/,個人放~/.agents/skills/inspect-github-agent-resources/。 - GitHub Copilot:專案內放
.github/skills/inspect-github-agent-resources/,個人放~/.copilot/skills/inspect-github-agent-resources/。
這是文件目前記載的預設位置,不蓋過你所在組織的規定。目的地已存在時,先比較版本再決定要不要替換。各宿主能不能找到這個資料夾,沒有端到端測過;裝好後若 skill 選單沒出現,請照該宿主的說明重新整理或重啟。
證據標記、涵蓋值與處置的完整定義在 skill 內的 references/audit-contract.md,清點 helper 的範圍與限制在 references/scanner.md,改版維護在 references/maintenance.md。
第一次使用
前提。一個能讀檔的 agent。審查公開 repo 需要匿名的公開網頁存取;只審本機檔案不需要上網,缺少的出處與公告證據會照實列為缺口。helper 需要 Node.js:建議用維持中的 LTS 版(測過 24.21.0),下限是 20.0.0(已終止維護)。不需要 npm install、API key 或第三方套件。驗證用的 agent 環境,紀錄沒有指名宿主。
不安裝先試。從 Release 頁取 v0.1.0 的壓縮檔,解壓到一個工作資料夾,保持 skills/inspect-github-agent-resources/ 完整。用能讀檔的 agent 開啟該資料夾,貼上這段請求,把 <repo> 換成解壓後的資料夾:
Read <repo>/skills/inspect-github-agent-resources/SKILL.md and use that skill to inspect <repo>/skills/inspect-github-agent-resources/examples/demo-snapshot. I want to summarize my own local notes. Explain task fit, source-based security concerns, evidence gaps, and the smallest useful acceptance check. Do not install or execute the reviewed resource. You may run this review skill's inventory helper.
這段請求取自 repo 說明,保留原文以免走樣;skill 要求用你慣用的語言作答。
示例一。此為示範樣本。demo-snapshot 是一份只有說明、沒有腳本和相依套件的簡單資源,功用是把使用者提供的一份筆記整理成大綱。repo 附的參考答覆是:它可以把你明確提供的一份筆記整理成大綱,但光憑來源裡的指示,證明不了摘要品質,也無法證明模型是離線處理的;先拿一份帶有不確定說法的合成筆記試試,檢查不確定性有沒有被保留。這是 repo 的示意,沒有實測結果支持。
示例二。此為示範樣本。repo 的 examples/review-example.md 設了另一個情境:使用者每週手動檢視第三方 skill,問本機清點 helper 能不能改善這個流程,檔案必須留在本機,也還沒準備執行候選程式碼。示意答覆說,它可以幫重複性的檔案清點和版本差異偵測,腳本的語意與沒掃到的相依套件仍要人看;目前沒有證據顯示它找得到更多漏洞,或省下可量的時間;安裝處置是 insufficient-evidence,因為出處與行為證據不足,但這不妨礙指出它的清點角色。兩項擬定的驗收:
- 人工審查前先清點:輸入已授權的快照,輸出雜湊、hook 與略過檔案的記錄。驗收是一個已知的合成 hook 被列出,略過的目錄仍看得到,沒有執行任何候選 hook。
- 回看改版:輸入兩份限定範圍的快照,輸出變動檔案的觀察。驗收是被改動的 hook 讓觀察改變,涵蓋不完整時,不會被寫成「確定移除」或「完全相同」。
成功的樣子。答覆說明它窄範圍的用途,引用你提供的檔案,把來源宣告的行為和執行期證據分開,並提出一項小驗證。不該出現:宣稱安全認證,或編造發布者與 release 歷史。
失敗與限制。答覆若給出數字分數,或用「safe」「approved」當結論,就不合 skill 自己的契約。helper 的結束碼:0 表示納入範圍的清點完成,不表示資源可以安裝;1 表示清點不完整或失敗;2 表示輸入無效。helper 的報告請存在被掃描的資料夾之外,免得改動了正在量測的證據。
版本與驗證。skill 0.1.0,trial prerelease;驗收紀錄在 VALIDATION.md。一般問題請用 GitHub Issues,附上合成的重現步驟,不承諾回覆時限;涉及安全的回報,走 GitHub 的私人漏洞回報管道。