solidity-security

solidity-security 技能總覽

solidity-security 是做什麼用的

solidity-security 是一套聚焦於 Solidity 智慧合約稽核與安全撰寫的指南型技能。當你希望 agent 在程式碼進入正式上線或外部正式稽核前，先針對常見攻擊類型檢查合約邏輯、提出更安全的實作模式，並說明為什麼某種設計有風險時，這個技能特別好用。

哪些人適合安裝 solidity-security 技能

這個技能特別適合：

• 正在把 Solidity 合約部署到 mainnet 或 testnet 的開發者
• 做第一輪檢視的稽核人員
• 準備將 DeFi、token、vault 或具管理權限控制的合約送交外部 Security Audit 的團隊
• 想要比泛泛一句「review this code」更有結構的安全回饋的工程師

如果你的專案不是 EVM 生態，或你要做的是純協議經濟模型分析，那它的幫助就相對有限。

使用者真正要解決的工作

使用者通常不只是想拿到一份漏洞清單。他們真正需要的是：把像「幫我檢查這個 vault 有沒有 reentrancy 和權限問題」這種模糊目標，轉成一套可重複執行的檢查流程，涵蓋可能的攻擊路徑、更安全的實作方式，以及修補優先順序。這正是 solidity-security 比一般 prompt 更有價值的地方。

solidity-security 和一般提示有什麼不同

這個技能的範圍很窄，但非常實用。它不是給你大而全的區塊鏈建議，而是集中處理 Solidity 常見的核心失敗模式，例如：

• reentrancy
• 算術邊界與例外情況
• access control 錯誤
• 不安全的 external calls
• 以安全為前提的實作模式

如果你在意的是精準度而不是涵蓋面，solidity-security 會比泛用型提示更適合。

採用 solidity-security 前要先知道什麼

這個 repository 很輕量：技能內容主要集中在 SKILL.md，沒有額外的規則、腳本或參考檔。這讓它很適合快速導入，但也代表輸出品質非常仰賴你提供的上下文。如果你只丟一句「audit this contract」，結果通常會偏泛。如果你能補上合約用途、threat model、特權角色以及關鍵函式，solidity-security skill 的實用性會明顯提高。

如何使用 solidity-security 技能

如何安裝 solidity-security

使用相容 skills 的 client，直接從 repository 安裝即可。常見做法如下：

npx skills add https://github.com/wshobson/agents --skill solidity-security

如果你的 agent 平台採用不同的安裝方式，也可以從這個位置加入技能：

https://github.com/wshobson/agents/tree/main/plugins/blockchain-web3/skills/solidity-security

repository 裡先看哪些檔案

先從這個檔案開始：

• plugins/blockchain-web3/skills/solidity-security/SKILL.md

因為這個技能的資料夾裡沒有額外的 README.md、rules/ 或 references/ 檔案，所以 SKILL.md 就是完整的操作手冊。建議先看其中的 “When to Use This Skill” 與漏洞分類相關段落，先理解它是用什麼安全視角來做審查。

solidity-security 要吃到哪些輸入，效果才會好

solidity-security usage 的品質，高度取決於你提供的合約上下文是否具體。建議至少提供：

• Solidity 版本
• 合約檔案或關鍵程式片段
• 合約用途
• 使用者角色與特權角色
• 資產流向：誰可以 deposit、withdraw、mint、burn、liquidate、upgrade
• 外部整合：oracles、ERC20s、bridges、routers、callbacks
• 對 trusted actors 的假設
• 你想要的輸出形式：快速掃描、深度稽核清單、攻擊情境，或 remediation 建議

少了這些資訊，這個技能大多只能輸出一份比較空泛的漏洞教科書式說明。

第一次審查時，最推薦的 prompt 形式

一個很好的起手式 prompt 是：

“Use the solidity-security skill to review these contracts for reentrancy, access control, unsafe external calls, arithmetic or accounting mistakes, and other high-severity issues. For each finding, include impact, exploit path, affected functions, and a concrete remediation. Distinguish confirmed issues from areas needing more context.”

這個 prompt 之所以有效，是因為它同時要求了：

• 明確的問題類型
• 有優先順序的輸出
• 攻擊推理
• 實作層級的修補建議
• 對不確定性的區分與處理

如何把模糊需求變成完整的 solidity-security prompt

弱的 prompt：

• “Check this Solidity code.”

更好的 prompt：

• “Use solidity-security for Security Audit preparation on this vault contract. Focus on withdrawal flow, share accounting, admin powers, pausing, upgradeability assumptions, and external token interactions. Identify critical and high findings first, then list medium-risk hardening opportunities.”

較好的版本把範圍收斂到業務上最關鍵的攻擊面，能有效提升訊號密度、減少無關的填充內容。

solidity-security 推薦的稽核工作流程

一個實用的 solidity-security guide 流程是：

1. 先請 agent 根據整組合約整理 threat model 摘要。
2. 再要求它做逐函式的風險地圖。
3. 深入檢查會改變狀態的 external-call 路徑。
4. 檢查受角色限制的函式與初始化邏輯。
5. 針對最高優先級問題要求 remediation 範例。
6. 把修補後的程式碼再丟回去，請它說明還剩哪些風險。

這種分階段的流程，通常會比一開始就要求做一輪超大型完整稽核，得到更好的結果。

使用 solidity-security 時，最值得強調的高價值檢查區域

呼叫 solidity-security 時，建議你明確要求 agent 聚焦在：

• withdrawal 與 payout 函式
• 支援 callback 的 token 互動
• 角色轉移與 ownership 邏輯
• 初始化與升級路徑
• accounting invariants
• oracle 或定價依賴
• 緊急控制機制
• 對 ERC20 相容性的假設

這些地方往往是淺層 prompt 最容易漏掉實質風險的區域。

solidity-security 看起來最擅長覆蓋哪些問題

從原始內容來看，這個技能最強的是常見 Solidity 漏洞類型與安全實作模式，尤其是 reentrancy，以及像 checks-effects-interactions 這類相關的防禦性撰寫習慣。最適合把它當成以安全為核心的寫碼與審查助手，而不是拿來取代 formal verification 或協議層級的經濟模型分析。

哪些實務技巧能提升 solidity-security 輸出品質

想讓 solidity-security usage 的結果更好，可以加上這些資訊：

• 直接貼出實際會移動資金的函式
• 標明哪些角色是 trusted、哪些是外部可控
• 說明合約是否可升級，或是否透過 proxy 部署
• 不只問 bug 名稱，也要求列出 exploit prerequisites
• 要求依嚴重性排序，並附上理由
• 要求模型把程式碼事實與推測假設分開

這些小補充，對最終判斷品質通常有很實質的提升。

不要對 solidity-security 抱哪些期待

不要期待 solidity-security skill 會自動：

• 執行測試
• 檢查已部署 bytecode
• 以數學方式證明 invariants
• 取代完整的人工 Security Audit
• 發現你從未提及、且高度依賴生態脈絡的問題

它最有效的定位，是你已提供程式碼與架構上下文後的專家級審查骨架。

solidity-security 技能常見問題

solidity-security 適合拿來做 Security Audit 前置準備嗎？

適合。solidity-security for Security Audit 是很強的使用情境，特別是在你想先抓出明顯或中度隱晦的 Solidity 問題、再決定是否投入外部稽核費用時。它能幫團隊先把程式碼收斂、把假設寫清楚，並在進入正式稽核前，先減少一些本可避免的發現項目。

它真的比一般的「audit my contract」prompt 更好嗎？

通常是。泛用 prompt 常常只會回一份樣板化的智慧合約風險清單。solidity-security 則替 agent 提供了更聚焦的安全框架，通常能更集中在攻擊路徑、安全模式與修補細節上。

solidity-security 適合初學者嗎？

適合，但有限度。初學者可以用它來認識常見的 Solidity 攻擊面與較安全的撰寫方式，但不應把它當成完整課程。如果你是新手，建議要求它用白話解釋每個 finding，並示範更安全的替代寫法。

在什麼情況下 solidity-security 不太適合？

它不太適合以下工作：

• 非 Solidity 鏈
• 前端錢包安全
• tokenomics 設計審查
• 治理機制的 game theory 分析
• 缺乏程式碼上下文的 production 事故應變

遇到這些需求時，應該改用更完整的區塊鏈安全流程，或換成其他更專門的技能。

它可以只看單一檔案，還是一定要整個 codebase？

它可以審查單一檔案，但有周邊上下文時結果會更好。舉例來說，一個 vault 合約如果缺少 token、oracle、access-control 或 proxy 的脈絡，看起來可能很安全，但真正關鍵的假設其實藏在別的地方。

這個技能只會抓經典漏洞嗎？

不是，但經典漏洞確實是它的重心。你可以預期它在已知的 Solidity 實作風險上表現最好，而不是特別客製、偏協議經濟層的攻擊。如果你最在意的是 insolvency、oracle manipulation 或 liquidation 設計，務必要明講。

如何進一步提升 solidity-security 技能的效果

一開始就把 threat model 給 solidity-security

想最快提升 solidity-security 的輸出品質，最有效的方式就是先定義：

• 攻擊者能力
• trusted roles
• 需要保護的資產
• 不可接受的結果

例如：

• “Assume any external user is adversarial, admin key is trusted but fallible, and loss of user deposits is the top-risk outcome.”

這能幫 agent 把重點放在真正重要的風險，而不是流於風格層級的回饋。

不只貼程式碼，也提供 invariants

高品質輸入應包含系統規則，例如：

• total shares should never exceed claimable assets
• only governance can change fee parameters
• user withdrawals must not depend on untrusted callbacks

當你提供 invariants，這個技能就能依照你預期的行為測試邏輯，而不只是掃描語法模式。

要求它寫出 exploit 敘事

常見失敗模式之一，是只得到一份平面的 finding 清單，卻看不出問題是否真的重要。改進方式是直接要求：

• entry condition
• 攻擊步驟
• 預期影響
• 這是實際風險，還是只是理論上的可能性

這會迫使 solidity-security skill 用稽核員的方式推理，而不是只像 linter 一樣列點。

讓 remediation 請求更具體

不要只問「這要怎麼修？」應改問：

• 最小 patch 是什麼
• 更安全的設計替代方案是什麼
• 每種修法的 tradeoff 是什麼
• patch 是否會影響 gas costs 或 UX

比起泛泛的安全撰寫建議，這種具體的 remediation prompt 通常更能產生可執行的結果。

對修補後的程式碼重新跑一次 solidity-security

完成第一輪後，把修改過的函式或合約再貼回去，並追問：

• 哪些風險已經被移除
• 還殘留哪些風險
• 修補是否引入新的 edge cases
• 應該補哪些測試

這是採用後最值得投入 solidity-security install 時間的使用方式之一，效益通常很高。

使用 solidity-security 時要留意的常見失誤

即使用了這個技能，仍要注意以下問題：

• 把推測性漏洞說得過度確定
• 漏看繼承合約中隱藏的前提假設
• 忽略角色管理細節
• 明明深層問題是 accounting design，卻只給出標準 reentrancy 建議
• 把所有 external calls 都當成同樣危險

你可以透過補上 inheritance 上下文，並要求模型對每個結論都指出確切的函式路徑，來降低這些誤差。

更適合深度審查的 solidity-security prompt

一個很好的第二輪 prompt：

“Use solidity-security to review only the withdrawal, reward-claim, and admin-setter paths. Ignore gas micro-optimizations. For each issue, cite the function, state variable, attacker capability required, exploit sequence, and the safest realistic remediation for this codebase.”

這類 prompt 之所以有效，是因為它同時限制了範圍與輸出格式。

把 solidity-security 和測試、人工審查搭配使用

最佳流程不是只靠技能。應該用 solidity-security 先產生假設，再透過以下方式驗證：

• unit tests
• invariant tests
• fuzzing
• 人工逐行審查

這種組合，比單靠一般 prompt 或只靠靜態閱讀程式碼都強得多。

如何判斷 solidity-security 真的有幫上忙

如果 solidity-security guide 有做到以下幾點，就表示它發揮作用了：

• 更快找出最危險的函式
• 更清楚說明漏洞可利用性
• 產出更好的修補方案候選
• 幫你整理出更乾淨、可交給外部稽核員的問題
• 減少泛用 prompt 帶來的猜測成本

如果跑了兩輪之後輸出還是很空泛，通常原因不是安裝本身，而是你提供的合約上下文還不夠。