solidity-security

solidity-security skill 概览

solidity-security 适合用来做什么

solidity-security skill 是一套聚焦 Solidity 智能合约审计与安全编码的实用指南。它最适合在代码上线生产环境或进入正式审计之前使用：让 agent 帮你检查合约逻辑中的常见漏洞类别、给出更安全的实现模式，并解释某个设计为什么有风险。

谁适合安装这个 skill

这个 skill 适合：

• 正在向 mainnet 或 testnets 部署合约的 Solidity 开发者
• 做首轮代码审查的审计人员
• 准备将 DeFi、token、vault 或带管理员权限的合约送交外部 Security Audit 的团队
• 希望获得比泛泛一句“review this code”更有结构化安全反馈的工程师

如果是非 EVM 项目，或你关注的是纯协议经济模型分析，它的价值就没那么高。

它真正解决的核心问题

用户要的不只是一个漏洞清单。他们真正需要的，是把“帮我看看这个 vault 有没有重入和权限问题”这类模糊目标，转成一套可重复执行的审查流程：覆盖可能的攻击路径、更安全的实现方式，以及修复优先级。这正是 solidity-security 比普通提示词更强的地方。

solidity-security 的差异点在哪里

这个 skill 很聚焦，也很实战。它不提供泛泛的区块链安全建议，而是围绕 Solidity 的核心失效模式展开，例如：

• reentrancy
• arithmetic 边界情况
• access control 错误
• 不安全的 external calls
• 面向安全的实现模式

所以当你更看重“判断要准”，而不是“覆盖面要广”时，solidity-security 会更合适。

采用前需要知道的事

这个仓库非常轻量：skill 内容基本都在 SKILL.md 里，没有额外的规则、脚本或参考文件。这意味着它上手很快，但也意味着输出质量会高度依赖你提供的上下文。

如果你只给一句“audit this contract”，那大概率只能得到比较泛的结论；如果你补充合约用途、threat model、特权角色和关键函数，solidity-security skill 的实际可用性会明显提升。

如何使用 solidity-security skill

如何安装 solidity-security

使用兼容 skills 的客户端，可以直接从仓库安装。常见方式是：

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

如果你的 agent 平台使用的是其他安装机制，也可以从下面这个地址添加该 skill：

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

仓库里先看什么

先看这里：

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

因为这个 skill 的目录下没有配套的 README.md、rules/ 或 references/ 文件，所以 SKILL.md 就是完整的操作手册。建议先读其中的 “When to Use This Skill” 和各类漏洞说明，先建立它采用的审查视角。

要让这个 skill 发挥效果，需要提供哪些输入

solidity-security usage 的质量，取决于你是否提供了足够具体的合约上下文。建议至少提供：

• Solidity version
• 合约文件或关键代码片段
• 合约用途
• 用户角色和特权角色
• 资产流转路径：谁负责 deposit、withdraw、mint、burn、liquidate、upgrade
• 外部集成：oracles、ERC20s、bridges、routers、callbacks
• 对可信参与方的假设
• 你希望得到什么输出：quick scan、deep audit checklist、exploit scenarios，还是 remediations

如果没有这些信息，这个 skill 基本只能输出一套通用漏洞讲义。

首轮审查最合适的提示词写法

一个比较强的起手提示词是：

“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.”

这个提示词之所以有效，是因为它同时要求了：

• 具体的问题类别
• 有优先级的输出
• 对 exploit 的推理
• 实现层面的修复建议
• 对不确定性的区分处理

如何把模糊目标改写成完整提示词

弱提示词：

• “Check this Solidity code.”

更好的提示词：

• “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 guide 使用流程是：

1. 先让它根据整组合约总结 threat model。
2. 再要求它给出逐函数的风险地图。
3. 深挖所有会改状态且涉及 external call 的路径。
4. 审查受角色限制的函数和初始化逻辑。
5. 让它针对最高优先级问题给出 remediation 示例。
6. 对修补后的代码再次运行 skill，并追问还剩哪些风险。

这种分阶段的 workflow，通常比“一次性做一个超大审计 pass”产出更好。

高价值审查区域要重点强调

调用 solidity-security 时，建议明确要求 agent 重点看：

• withdrawal 和 payout 函数
• 支持 callback 的 token 交互
• 角色转移和 ownership 逻辑
• 初始化与 upgrade 路径
• accounting invariants
• oracle 或 pricing 依赖
• 紧急控制机制
• 对 ERC20 compliance 的假设

这些地方往往是浅层提示词最容易漏掉真实风险的区域。

这个 skill 看起来最擅长覆盖什么

从源码内容来看，这个 skill 最强的是常见 Solidity 漏洞类别和安全实现模式，尤其是 reentrancy，以及像 checks-effects-interactions 这样的防御性编码习惯。

更适合把它当作一个以安全为中心的编码与代码审查助手，而不是 formal verification 或协议层经济模型分析的替代品。

提升输出质量的实用技巧

想获得更好的 solidity-security usage 结果，可以补充这些信息：

• 直接贴出真正负责资金转移的函数
• 标明哪些角色可信、哪些角色受外部控制
• 说明合约是否可升级，是否走 proxy
• 不只问 bug 名称，也要求给出 exploit prerequisites
• 要求按 severity 排序并说明理由
• 让模型区分“代码事实”和“推测假设”

这些看似小的补充，往往会显著提升决策质量。

不要对这个 skill 抱有哪些预期

不要期待 solidity-security skill 会自动：

• 运行测试
• 检查已部署的 bytecode
• 用数学方式证明 invariants
• 替代完整的人工 Security Audit
• 发现你从未提及的生态特定问题

它最有效的定位，是基于你提供的代码和架构上下文，充当专家级审查框架。

solidity-security skill 常见问题

solidity-security 适合用于 Security Audit 准备吗？

适合。solidity-security for Security Audit 是一个很强的使用场景：如果你想在付费找外部审计前，先把明显问题和一部分不那么表层的 Solidity 风险筛出来，它会很有帮助。它能帮助团队先收紧代码、补齐假设说明，并以更少的可避免问题进入正式审计。

它比泛泛的 “audit my contract” 提示词更好吗？

通常是的。泛提示词经常只会返回一份模板化的智能合约风险列表；而 solidity-security skill 给 agent 预设了更窄、更明确的安全视角，通常更能聚焦 exploit path、安全模式和 remediation 细节。

solidity-security 适合初学者吗？

适合，但有边界。初学者可以用它了解常见 Solidity 攻击面和更安全的编码模式，但不能把它当成完整课程。如果你是新手，建议明确要求它用通俗语言解释每个 finding，并展示更安全的替代写法。

什么情况下 solidity-security 不太适合？

以下场景里，它的匹配度较弱：

• 非 Solidity 链
• front-end wallet 安全
• tokenomics 设计评审
• governance game theory
• 缺少代码上下文的生产事故响应

这些任务更适合更广义的区块链安全流程，或其他更专门的 skill。

它可以只审一个文件，还是需要整个代码库？

它可以审单个文件，但有上下文时效果更好。比如一个 vault contract，如果缺少 token、oracle、access-control 或 proxy 相关上下文，表面上看可能很安全，但关键假设其实藏在别的地方。

这个 skill 只覆盖经典漏洞吗？

不完全是，但经典漏洞确实是它的重心。你可以期待它在已知的 Solidity 实现层风险上表现最好，而不是在高度定制化的协议经济攻击上最强。如果你真正担心的是 insolvency、oracle manipulation 或 liquidation design，一定要明确写出来。

如何改进 solidity-security skill 的使用效果

一开始就把 threat model 讲清楚

提升 solidity-security 输出质量最快的方法，就是先定义：

• 攻击者能力
• 可信角色
• 受保护资产
• 不可接受的结果

例如：

• “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 时，这个 skill 就能基于“预期行为”来检验逻辑，而不只是扫描语法模式。

要求它给出 exploit 叙事

一个常见失败模式是：只给你一份平铺直叙的 finding 列表，却无法证明问题的重要性。改进方式是要求它补充：

• entry condition
• attack steps
• expected impact
• 这个问题是现实可利用，还是只是理论上的

这样可以逼着 solidity-security skill 以审计员的思路推理，而不是像 linter 一样机械报错。

让 remediation 请求更具体

不要只问 “how to fix this?”，建议改成明确要求：

• minimal patch
• 更安全的设计替代方案
• 每种修复方案的 tradeoffs
• patch 是否会影响 gas costs 或 UX

具体的 remediation 请求，产出的可执行性会远高于泛泛的安全编码建议。

在修补后的代码上重新跑一次

完成首轮修复后，把修改后的函数或合约重新贴进去，并继续追问：

• 哪些风险已经被移除
• 还残留哪些风险
• 修复是否引入了新的边界情况
• 应该补哪些测试

这是采用后最值得投入时间的 solidity-security install 使用方式之一。

需要警惕的常见失败模式

即使用了这个 skill，也仍然要注意：

• 把推测性的漏洞说得过于确定
• 漏掉继承合约里隐藏的关键假设
• 忽略角色管理细节
• 面对本质是 accounting design 的问题时，只给标准 reentrancy 建议
• 把所有 external calls 一概当成同等危险

你可以通过补充 inheritance context，并要求模型为每个结论标出确切函数路径，来降低这些错误。

更适合深入审查的提示词

一个更强的第二轮提示词示例：

“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.”

这个提示词有效，是因为它同时限制了范围和输出格式。

把这个 skill 与测试和人工审查配合使用

最佳 workflow 不是只靠 skill。更好的做法是用 solidity-security 生成假设，再通过以下方式验证：

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

这种组合，通常比单纯提示词审查或只靠静态阅读都更强。

如何判断这个 skill 是否真的在帮你

如果 solidity-security guide 真在发挥作用，你会看到它帮助你：

• 更快找出最危险的函数
• 更清楚地解释可利用性
• 产出更靠谱的 patch 候选方案
• 为外部审计准备更干净、更聚焦的问题
• 减少通用提示词带来的猜测成本

如果迭代两轮后输出仍然很空泛，通常问题不在安装本身，而在于你没有提供足够的合约上下文。