SkillHub

Skills trailofbits skills

guidelines-advisor

Use it when:
You want to know whether a smart contract project follows development best practices, or need advice on its design, upgrades or tests.
It does:
Explores the code, drafts a plain-English system description and diagrams, reviews architecture and implementation across 11 areas, and asks about design choices.
You get:
System documentation, an architecture and implementation review with file and line references, and recommendations ranked Critical to Low.
Works on:
Mainly Solidity, using Slither for diagrams and upgradeability checks when available; it adapts to Rust, Cairo and other platforms.

TL;DR

Trail of Bits' Building Secure Contracts development guidelines, applied to your codebase. The 11 areas are documentation and specifications, including NatSpec; what runs on-chain versus off-chain; upgradeability, weighing migration against upgrades; delegatecall proxies, such as storage layout, initialization and function shadowing; function composition; inheritance; events; common pitfalls such as reentrancy, overflow and access control; dependencies, including copied code; testing and verification, from coverage to fuzzing and formal verification; and platform guidance such as compiler version and inline assembly. A section that seems not to apply, such as upgradeability in a project without proxies, is skipped only after searching the code, since upgradeability can hide in ownable patterns or delegatecall. It rejects generic best-practice advice in favour of project-specific findings with file and line references, and ends with a prioritized roadmap. Detailed criteria, deliverable templates and an example report live in separate resource files.

Summarizes the skill at e4dd0bb.

npx skills add https://github.com/trailofbits/skills --skill guidelines-advisor

skills.sh pageSource on GitHubAll skills from trailofbits/skills

Total Downloads
5,800 on skills.sh, Nov 9, 2026
Repo stars
8,081 trailofbits/skills
First seen
Jan 19, 2026 on skills.sh
Weekly Downloads
183
+50% over the 8 weeks to Nov 9
Weekly values
Week toInstalls
Sep 21122
Sep 28107
Oct 596
Oct 12124
Oct 19127
Oct 26153
Nov 2169
Nov 9183
Category
category:securitycategory:software-engineering

Compliance, guardrails, skill vetting and browser fingerprinting.

Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills.
Type
type:workflow

A multi-step process the agent follows: interview, debug, run a TDD loop, review.
Effect
effect:none

Adds no side effects of its own. It shapes how the agent thinks, writes or reviews. Guidelines and routers are always effect:none, even when the task they support edits code.
Needs
needs:none

Instructions only. Works in any agent that supports skills.
Publisher
by:official

A verified publisher on skills.sh, or the company or maintainer behind the product the skill operates.
Topics
securityweb3architecturecode-reviewcode-quality
Stack
stack:soliditystack:slither

SKILL.md

From trailofbits/skills at e4dd0bb. Checked daily, last changed Nov 6, 2026.

Frontmatter
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. Use when asking whether a smart contract project follows development best practices, reviewing on-chain/off-chain split, upgradeability, or delegatecall proxy patterns against guidelines, or seeking recommendations on contract design, inheritance, events, documentation, dependencies, or test strategy.

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
  • Existing documentation
  • Architecture patterns (proxies, upgrades, etc.)
  • Testing setup
  • Dependencies
Phase 2: Documentation Generation

Helps create:

  • Plain English system description
  • 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.

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.

Example Output

When the analysis is complete, you'll receive comprehensive guidance covering:

  • System documentation with plain English descriptions
  • Architectural diagrams and documentation gaps
  • Architecture analysis (on-chain/off-chain, upgradeability, proxies)
  • Implementation review (functions, inheritance, events, pitfalls)
  • Dependencies and testing evaluation
  • Prioritized recommendations (CRITICAL, HIGH, MEDIUM, LOW)
  • Overall assessment and path to production

For a complete example analysis report, see EXAMPLE_REPORT.md.

Deliverables

I provide four comprehensive deliverable categories:

1. System Documentation
  • Plain English descriptions
  • Architectural diagrams
  • Documentation gaps analysis
2. Architecture Analysis
  • On-chain/off-chain assessment
  • Upgradeability review
  • Proxy pattern security review
3. Implementation Review
  • Function composition analysis
  • Inheritance assessment
  • Events coverage
  • Pitfall identification
  • Dependencies evaluation
  • Testing analysis
4. Prioritized Recommendations
  • CRITICAL (address immediately)
  • HIGH (address before deployment)
  • MEDIUM (address for production quality)
  • LOW (nice to have)

For detailed templates and examples of each deliverable, see DELIVERABLES.md.

Assessment Process

When invoked, I will:

  1. Explore the codebase

    • Identify all contract/module files
    • Find existing documentation
    • Locate test files
    • Check for proxies/upgrades
    • Identify dependencies

  2. Generate documentation

    • Create plain English system description
    • Generate architectural diagrams (if tools available)
    • Identify documentation gaps

  3. Analyze architecture

    • Assess on-chain/off-chain distribution (if applicable)
    • Review upgradeability approach (if applicable)
    • Audit proxy patterns (if present)

  4. Review implementation

    • Analyze functions, inheritance, events
    • Check for common pitfalls
    • Assess dependencies
    • Evaluate testing

  5. Provide recommendations

    • Present findings with file references
    • Ask clarifying questions about design decisions
    • Suggest prioritized improvements
    • Offer actionable next steps

Rationalizations (Do Not Skip)

Rationalization Why It's Wrong Required Action
"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!