Smart contract development advisor based on Trail of Bits' best practices. Analyzes codebase to generate documentation/specifications, review architecture, check upgradeability patterns, assess implementation quality, identify pitfalls, review dependencies, and evaluate testing.
Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/guidelines-advisor
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Smart contract development advisor based on Trail of Bits' best practices. Analyzes codebase to generate documentation/specifications, review architecture, check upgradeability patterns, assess implementation quality, identify pitfalls, review dependencies, and evaluate testing.
📊 Stats
Stars6,227
Forks540
LanguagePython
LicenseCC-BY-SA-4.0
📦 Ships with trailofbits-skills
</> SKILL.md
guidelines-advisor.SKILL.md
---name: guidelines-advisor
description: Smart contract development advisor based on Trail of Bits' best practices. Analyzes codebase to generate documentation/specifications, review architecture, check upgradeability patterns, assess implementation quality, identify pitfalls, review dependencies, and evaluate testing. Provides actionable recommendations.
---# Guidelines Advisor
## Purpose
Systematically analyzes the codebase and provides guidance based on Trail of Bits' development guidelines:
1. **Generate documentation and specifications** (plain English descriptions, architectural diagrams, code documentation)
2. **Optimize on-chain/off-chain architecture** (only if applicable)
3. **Review upgradeability patterns** (if your project has upgrades)
4. **Check delegatecall/proxy implementations** (if present)
5. **Assess implementation quality** (functions, inheritance, events)
6. **Identify common pitfalls**
7. **Review dependencies**
8. **Evaluate test suite and suggest improvements**
**Framework**: Building Secure Contracts - Development Guidelines
---## How This Works
### Phase 1: Discovery & Context
Explores the codebase to understand:
- Project structure and platform
- Contract/module files and their purposes
- Architectural diagrams (using Slither printers for Solidity)
- Code documentation recommendations (NatSpec for Solidity)
### Phase 3: Architecture Analysis
Analyzes:
- On-chain vs off-chain component distribution (if applicable)
- Upgradeability approach (if applicable)
- Delegatecall proxy patterns (if present)
### Phase 4: Implementation Review
Assesses:
- Function composition and clarity
- Inheritance structure
- Event logging practices
- Common pitfalls presence
- Dependencies quality
- Testing coverage and techniques
### Phase 5: Recommendations
Provides:
- Prioritized improvement suggestions
- Best practice guidance
- Actionable next steps
---
## Assessment Areas
I analyze 11 comprehensive areas covering all aspects of smart contract development. For detailed criteria, best practices, and specific checks, see [ASSESSMENT_AREAS.md](resources/ASSESSMENT_AREAS.md).
### Quick Reference:
1. **Documentation & Specifications**
- Plain English system descriptions
- Architectural diagrams
- NatSpec completeness (Solidity)
- Documentation gaps identification
2. **On-Chain vs Off-Chain Computation**
- Complexity analysis
- Gas optimization opportunities
- Verification vs computation patterns
3. **Upgradeability**
- Migration vs upgradeability trade-offs
- Data separation patterns
- Upgrade procedure documentation
4. **Delegatecall Proxy Pattern**
- Storage layout consistency
- Initialization patterns
- Function shadowing risks
- Slither upgradeability checks
5. **Function Composition**
- Function size and clarity
- Logical grouping
- Modularity assessment
6. **Inheritance**
- Hierarchy depth/width
- Diamond problem risks
- Inheritance visualization
7. **Events**
- Critical operation coverage
- Event naming consistency
- Indexed parameters
8. **Common Pitfalls**
- Reentrancy patterns
- Integer overflow/underflow
- Access control issues
- Platform-specific vulnerabilities
9. **Dependencies**
- Library quality assessment
- Version management
- Dependency manager usage
- Copied code detection
10. **Testing & Verification**
- Coverage analysis
- Fuzzing techniques
- Formal verification
- CI/CD integration
11. **Platform-Specific Guidance**
- Solidity version recommendations
- Compiler warning checks
- Inline assembly warnings
- Platform-specific tools
For complete details on each area including what I'll check, analyze, and recommend, see [ASSESSMENT_AREAS.md](resources/ASSESSMENT_AREAS.md).
---
## Example Output
When the analysis is complete, you'll receive comprehensive guidance covering:
- System documentation with plain English descriptions
| "System is simple, description covers everything" | Plain English descriptions miss security-critical details | Complete all 5 phases: documentation, architecture, implementation, dependencies, recommendations |
| "No upgrades detected, skip upgradeability section" | Upgradeability can be implicit (ownable patterns, delegatecall) | Search for proxy patterns, delegatecall, storage collisions before declaring N/A |
| "Not applicable" without verification | Premature scope reduction misses vulnerabilities | Verify with explicit codebase search before skipping any guideline section |
| "Architecture is straightforward, no analysis needed" | Obvious architectures have subtle trust boundaries | Analyze on-chain/off-chain distribution, access control flow, external dependencies |
| "Common pitfalls don't apply to this codebase" | Every codebase has common pitfalls | Systematically check all guideline pitfalls with grep/code search |
| "Tests exist, testing guideline is satisfied" | Test existence ≠ test quality | Check coverage, property-based tests, integration tests, failure cases |
| "I can provide generic best practices" | Generic advice isn't actionable | Provide project-specific findings with file:line references |
| "User knows what to improve from findings" | Findings without prioritization = no action plan | Generate prioritized improvement roadmap with specific next steps |
---
## Notes
- I'll only analyze relevant sections (won't hallucinate about upgrades if not present)
- I'll adapt to your platform (Solidity, Rust, Cairo, etc.)
- I'll use available tools (Slither, etc.) but work without them if unavailable
- I'll provide file references and line numbers for all findings
- I'll ask questions about design decisions I can't infer from code
---
## Ready to Begin
**What I'll need**:
- Access to your codebase
- Context about your project goals
- Any existing documentation or specifications
- Information about deployment plans
Let's analyze your codebase and improve it using Trail of Bits' best practices!
