1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | guidelines-advisor-trailofbits-skills |
| 作者/维护者 | Trail of Bits（插件作者：Omar Inuwa、Paweł Płatek） |
| 来源链接 | https://github.com/trailofbits/skills/tree/main/plugins/building-secure-contracts/skills/guidelines-advisor |
| 许可证 | CC-BY-SA-4.0（GitHub API 获取，明确） |
| GitHub Stars / Forks | 6,418 / 555（GitHub API 获取；这是所属 trailofbits/skills 合集仓库的整体数字，不代表本技能个体热度，本技能自身的受欢迎度取证见第 6 章） |
| 最新版本 | 所属插件 building-secure-contracts v1.1.2（含本技能在内共 11 个子技能） |
| 安装方式 | Claude Code 插件市场一条命令：/plugin install trailofbits/skills/plugins/building-secure-contracts |
2. 功能介绍与亮点
guidelines-advisor 把 Trail of Bits 公开发布的《Building Secure Contracts》开发指南，转化为一套可对话执行的智能合约代码库全面自查流程，覆盖 11 个评估领域：
- 文档与规范（生成系统的通俗英文描述、架构图、NatSpec 完整度检查）
- 链上/链下计算分布（Gas 优化机会识别）
- 可升级性模式（迁移 vs 可升级方案的权衡、数据分离模式）
- Delegatecall 代理模式（存储布局一致性、初始化风险、函数遮蔽风险）
- 函数组织质量（函数大小、逻辑分组、模块化程度）
- 继承结构（层级深度、菱形继承风险）
- 事件日志（关键操作覆盖度、命名一致性）
- 常见陷阱（重入、整数溢出、访问控制缺陷等）
- 依赖质量（第三方库版本管理、拷贝代码检测）
- 测试与验证（覆盖率、模糊测试、形式化验证、CI/CD 集成）
- 平台专属建议（Solidity 版本选择、编译警告、内联汇编风险等）
按发现上下文→文档生成→架构分析→实现审查→建议五个阶段推进，最终产出四类交付物：系统文档（含架构图）、架构分析、实现审查、按 CRITICAL/HIGH/MEDIUM/LOW 优先级排列的改进建议清单。
亮点一：内置一张“合理化陷阱”对照表，逐条拆穿“系统很简单不用写文档”“没检测到升级就跳过可升级性章节”这类会导致漏检的省事借口，并规定必须先做代码库检索验证才能跳过某一章节。亮点二：附带一份完整的示例分析报告（以 NFT 交易市场为样例），逐段展示从系统描述、架构图清单到优先级建议的完整输出形态，用户动手前就能预见交付物长相。技能会根据项目实际使用的平台（Solidity、Rust、Cairo 等）自适应，可选调用 Slither 生成架构图，未安装时也能仅靠人工分析继续工作。
3. 适用场景
所属分类：安全与合规（核心产出是对照 Trail of Bits 安全开发指南展开的架构与实现质量审查，属于安全实践的具体落地，而非通用代码重构或效率工具）。
适用于智能合约开发团队在功能迭代或正式外部审计前，对代码库做一次系统性自查——尤其是采用了可升级代理模式、依赖第三方库、或缺少完整架构文档的项目。受益人群：DeFi 协议与智能合约工程团队、负责把控代码质量的技术负责人、以及需要在提交审计前先梳理清楚架构与文档现状的项目负责人。
4. 跨 Agent 兼容性
- Claude Code：原生支持——标准
.claude-plugin/plugin.json插件市场清单 + SKILL.md，一条/plugin install命令安装，/guidelines-advisor触发。 - Codex：原生支持——所属仓库 README 明确注明“Codex supports Claude plugin marketplaces directly, so this repository does not need Codex-specific sidecar metadata”，可用
codex plugin marketplace add trailofbits/skills直接安装同一插件市场。 - OpenClaw：未验证——未见相关适配材料。
- Hermes Agent：未验证——未见官方原生支持证据。
5. 推荐理由
guidelines-advisor 是 Trail of Bits 官方出品的智能合约开发全流程顾问，把一份需要逐条人工对照的静态指南文档，变成会主动探索代码库、生成项目专属分析报告的对话式工具。内置的“合理化陷阱”对照表专门堵住“看起来简单就跳过检查”这类最容易漏检的省事心态，示例报告让用户在动手前就清楚会拿到什么。对没有专职安全工程师、但希望在功能迭代或提交审计前先做一轮系统性自查的团队，是一份能直接落地执行的架构与实现质量体检工具。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 8 | 官方 Trail of Bits（知名智能合约安全审计机构）出品；skills.sh 平台该子技能独立安装量 4.0K；被 Snyk 安全领域评测文章个体点名描述（“for architecture, upgradeability, and implementation review”） |
| 可用性 | 9 | 一条命令安装；SKILL.md 含完整 11 个评估领域说明与 5 阶段流程，另附三份独立资源文档（评估标准细则、交付物模板、完整示例分析报告）；所属仓库最近一次提交为 2026-08-03，维护活跃；无需付费依赖 |
| 安全性 | 9 | 见下方检查清单 |
安全检查清单： ① shell 命令：无强制脚本执行，可选调用 Slither 等工具生成架构图，由用户在自有环境自行运行，技能本身不代为执行、不索取额外系统权限； ② 联网外发：无，纯本地代码库分析与文档生成工作流，不外发数据； ③ API key/凭据：不需要任何凭据； ④ 可疑指令：通读 SKILL.md 及三份资源文件（评估标准细则、交付物模板、示例报告）全文未见隐藏指令、混淆代码或异常外发迹象； ⑤ 作者信誉：Trail of Bits 官方仓库，信誉良好； ⑥ License：CC-BY-SA-4.0，明确； ⑦ 维护时间：本技能文件最近一次结构性提交 2026-06-05，所属仓库整体最近提交 2026-08-03，仍在积极维护。
7. 跟同类 Skills 相比的优势
| 对比对象 | 定位 | 与 guidelines-advisor 的差异 |
|---|---|---|
| Slither（crytic/slither，Trail of Bits 自家静态分析引擎） | Solidity 静态分析工具，内置 90+ 检测器 | 只输出扁平化的漏洞/警告列表，不覆盖架构设计评审、可升级性模式、文档生成、依赖质量等开发阶段的整体指导；guidelines-advisor 把 Slither 作为可选调用工具融入更全面的 11 维度评审流程 |
| Building Secure Contracts（crytic/building-secure-contracts，guidelines-advisor 依据的原始指南文档仓库，约 2,474★） | Trail of Bits 发布的智能合约安全开发培训材料与指南文本 | 是需要人工逐条对照代码检查的静态文档；guidelines-advisor 把该文档转化为会主动探索代码库、生成项目专属分析报告与优先级建议的可执行流程 |
| OpenZeppelin 官方文档（可升级合约与代理模式设计指南） | 业界广泛参考的可升级合约设计最佳实践文档 | 同样是静态参考资料，覆盖面聚焦可升级性单一主题；guidelines-advisor 覆盖面更广（文档、架构、可升级性、实现质量、依赖、测试共 11 个领域），且能针对具体项目自动生成分析结果而非通用建议 |
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。
9. 其他补充
技能会根据项目所用平台自动调整分析重点（Solidity、Rust、Cairo 等均可），检测不到可升级模式或代理模式时会如实跳过对应章节而非强行套用模板。所属插件 building-secure-contracts 同时打包了 6 个链平台专属漏洞扫描器与另外 4 个开发指南类子技能，guidelines-advisor 是其中覆盖面最广的一个，定位为“先做全局自查、再决定是否需要针对具体链的漏洞扫描”的入口工具。
10. 安装使用方式
Claude Code：
/plugin install trailofbits/skills/plugins/building-secure-contracts安装后无需重启，直接输入 /guidelines-advisor 即可在当前项目触发五阶段自查流程；技能会先探索代码库结构，再逐领域展开分析并给出优先级排序的改进建议。
Codex：
codex plugin marketplace add trailofbits/skills
codex plugin add building-secure-contracts@trailofbits11. 注意事项
- 该技能提供的是结构化建议与优先级排序，不能替代专业安全审计团队的人工代码审查，尤其是涉及资金安全的高风险合约仍建议配合第三方审计；
- 若需要生成架构图，需用户自行在本地环境安装 Slither，技能本身不负责安装该外部依赖；
- 属于合集仓库
trailofbits/skills下building-secure-contracts插件的 11 个子技能之一，安装该插件会连带装入其余 10 个子技能（含 6 个链平台漏洞扫描器与另外 4 个开发指南助手）。