New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Official agent skill

Smart Contract Guidelines Advisor

by trailofbits in trailofbits/skills

Reviews a smart contract project against Trail of Bits development guidelines, covering documentation, architecture, upgradeability, implementation quality, dependencies and tests.

OfficialCC-BY-SA-4.0Auto-check passedBackend & APIs

Install Smart Contract Guidelines Advisor

skills CLI
$ npx skills add trailofbits/skills --skill guidelines-advisor -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install trailofbits/skills guidelines-advisor --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/trailofbits/skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/building-secure-contracts/skills/guidelines-advisor .claude/skills/guidelines-advisor && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
guidelines-advisor
GitHub stars
7.4k
Token cost
~2.2k tokens
SKILL.md length
854 words
Files
6 (incl. assets)
Skills in repo
79
Repo updated
First seen
Licence
CC-BY-SA-4.0

At a glance

Reviews a smart contract project against Trail of Bits development guidelines, covering documentation, architecture, upgradeability, implementation quality, dependencies and tests.

  • Works in 9 steps: Discovery & Context → Documentation Generation → Architecture Analysis → …
  • Checking whether a smart contract project follows development guidelines
  • SKILL.md covers Purpose, How This Works, Assessment Areas and Example Output, plus 5 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Work proceeds in five phases: discovery of structure, platform and existing docs; documentation generation (a plain-English system description, architecture diagrams using Slither printers for Solidity, and NatSpec recommendations); architecture analysis of the on-chain and off-chain split, upgradeability and delegatecall proxies; implementation review; and prioritized recommendations.

The implementation review looks at function composition, inheritance, event logging, common pitfalls, dependency quality and test coverage and techniques. In all there are 11 assessment areas, described in ASSESSMENT_AREAS.md, with a deliverables file and an example report alongside. Parts that do not apply, such as upgrades or off-chain components, are skipped.

When your agent uses it

  • Checking whether a smart contract project follows development guidelines
  • Reviewing upgradeability or delegatecall proxy patterns
  • Getting recommendations on inheritance, events and contract design
  • Generating documentation and architecture diagrams for a contract codebase
  • Evaluating a contract test suite and its dependencies

Example prompts

  • “Review this Solidity protocol against the Trail of Bits development guidelines.”
  • “Check our delegatecall proxy implementation and migration plan for upgrade problems.”
  • “Write a plain-English system description and architecture diagram for these contracts.”

Workflow steps

9 steps, taken from the step headings in SKILL.md.

  1. Discovery & Context
  2. Documentation Generation
  3. Architecture Analysis
  4. Implementation Review
  5. Recommendations
  6. System Documentation
  7. Architecture Analysis
  8. Implementation Review
  9. Prioritized Recommendations

What it can do on your machine

Read from SKILL.md and the folder at commit 82fe822. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Smart Contract Guidelines Advisor loads about 2.2k tokens when it runs. Until then it costs about 150 tokens; SKILL.md has 854 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~150
When it runs · the whole SKILL.md, loaded when a task matches
~2.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from trailofbits/skills at commit 82fe822, republished under its CC-BY-SA-4.0 licence (© trailofbits). 854 words, ~2,188 tokens.

Download SKILL.mdSave it as .claude/skills/guidelines-advisor/SKILL.md (or your agent's skills folder). This skill also uses 5 other files; get the full folder from GitHub.
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.

Show full SKILL.md (356 more words)Show less

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)

RationalizationWhy It's WrongRequired Action
"System is simple, description covers everything"Plain English descriptions miss security-critical detailsComplete 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 verificationPremature scope reduction misses vulnerabilitiesVerify with explicit codebase search before skipping any guideline section
"Architecture is straightforward, no analysis needed"Obvious architectures have subtle trust boundariesAnalyze on-chain/off-chain distribution, access control flow, external dependencies
"Common pitfalls don't apply to this codebase"Every codebase has common pitfallsSystematically check all guideline pitfalls with grep/code search
"Tests exist, testing guideline is satisfied"Test existence ≠ test qualityCheck coverage, property-based tests, integration tests, failure cases
"I can provide generic best practices"Generic advice isn't actionableProvide project-specific findings with file:line references
"User knows what to improve from findings"Findings without prioritization = no action planGenerate 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!

© trailofbits, CC-BY-SA-4.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 5 other files (assets) in plugins/building-secure-contracts/skills/guidelines-advisor of trailofbits/skills.

  • SKILL.md
  • agents/openai.yaml
  • assets/trail-of-bits-mark.svg
  • resources/ASSESSMENT_AREAS.md
  • resources/DELIVERABLES.md
  • resources/EXAMPLE_REPORT.md

Open the folder on GitHubat commit 82fe822

Compare with similar skills

Smart Contract Guidelines Advisor next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Smart Contract Guidelines Advisor compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Smart Contract Guidelines Advisor this skilltrailofbits/skills7.4k—~2.2kAutomated safety check: PassCC-BY-SA-4.0
Developing Smart ContractsLFDT-Lineth/lineth-monorepo126—~1.4kAutomated safety check: PassAGPL-3.0
Foundry Reference Modelaviggiano/security144—~516Automated safety check: PassMIT
Fizz Convertpashov/skills1.2k2 repos~3.7kAutomated safety check: PassMIT
Smart Contract Auditgreatpie/smart-contract-audit-skill101—~1.1kAutomated safety check: PassNone
Solidity AuditorGabson0x/bountyforge443—~3.7kAutomated safety check: PassNone

Similar skills

  • Developing Smart Contracts

    LFDT-Lineth/lineth-monorepo

    Solidity smart contract development guidelines for Lineth blockchain.

    126 GitHub stars~1.4k tokensUpdated yesterday
    Backend & APIsAuto-check passed

  • Foundry Reference Model

    aviggiano/security

    Build a simple independent Solidity reference implementation for Foundry tests.

    144 GitHub stars~516 tokensUpdated 22 days ago
    Backend & APIsAuto-check passed

  • Fizz Convert

    pashov/skills

    Convert English-language properties in PROPERTIES.md (produced by the Fizz skill) into Solidity assertions inside the existing fuzz harness, then flip their checkboxes.

    1.2k GitHub starsUsed in 2 repos~3.7k tokens
    Backend & APIsAuto-check passed

  • Smart Contract Audit

    greatpie/smart-contract-audit-skill

    Script-backed, out-of-box auditing workflow for Solidity/EVM repositories based on EVMbench detect/patch/exploit methodology.

    101 GitHub stars~1.1k tokensUpdated 7 mo ago
    Backend & APIsAuto-check passed

  • Solidity Auditor

    Gabson0x/bountyforge

    Security audit of Solidity code while you develop. An agent skill from Gabson0x/bountyforge.

    443 GitHub stars~3.7k tokensUpdated 21 days ago
    Backend & APIsAuto-check passed

  • Stellar Dev

    VelaPayments/vela-payments

    End-to-end Stellar development playbook. An agent skill from VelaPayments/vela-payments.

    131 GitHub stars~1.8k tokensUpdated yesterday
    Backend & APIsAuto-check passed

More from trailofbits/skills

All 79 skills in this repo

  • CodeQL Security Scan

    trailofbits/skills

    Official

    Scans a codebase for vulnerabilities with CodeQL's data flow and taint tracking in run-all or important-only modes, including data extensions for project-specific sources and sinks.

    7.4k GitHub stars~4.6k tokensUpdated 5 days ago
    Auto-check: notes

  • Code Graph Mermaid Diagrams

    trailofbits/skills

    Official

    Generates Mermaid diagrams from Trailmark code graphs, including call graphs, class hierarchies, module dependency maps, complexity heatmaps and attack surface data flows.

    7.4k GitHub stars~1.7k tokensUpdated 5 days ago
    Auto-check passed

  • Trailmark Graph Evolution

    trailofbits/skills

    Official

    Compares Trailmark code graphs at two snapshots, such as commits, tags or directories, to surface attack paths, blast radius and taint changes that text diffs miss.

    7.4k GitHub stars~3.4k tokensUpdated 5 days ago
    Auto-check passed

  • Let Fate Decide

    trailofbits/skills

    Official

    Draws a 12 Houses tarot spread to break ties when a request is vague or casually delegated, then reads the cards to pick the next step.

    7.4k GitHub stars~2.5k tokensUpdated 5 days ago
    Auto-check: notes

  • Semgrep Security Scan

    trailofbits/skills

    Official

    Detects languages, proposes rulesets for approval, then runs the approved Semgrep scan across a codebase and merges the output into one SARIF file.

    7.4k GitHub stars~3.7k tokensUpdated 5 days ago
    Auto-check: notes

  • Burp Suite Project Parser

    trailofbits/skills

    Official

    Searches and extracts data from Burp Suite project files on the command line: regex searches over responses, audit findings, proxy history and site map data.

    7.4k GitHub starsUsed in 3 repos~4.2k tokens
    Auto-check: notes

Works with

Categories

Questions about Smart Contract Guidelines Advisor

What does Smart Contract Guidelines Advisor do?

Reviews a smart contract project against Trail of Bits development guidelines, covering documentation, architecture, upgradeability, implementation quality, dependencies and tests. Work proceeds in five phases: discovery of structure, platform and existing docs; documentation generation (a plain-English system description, architecture diagrams using Slither printers for Solidity, and NatSpec recommendations); architecture analysis of the on-chain and off-chain split, upgradeability and delegatecall proxies; implementation review; and prioritized recommendations.

When should I use Smart Contract Guidelines Advisor?

Smart Contract Guidelines Advisor fits situations like: checking whether a smart contract project follows development guidelines; reviewing upgradeability or delegatecall proxy patterns; getting recommendations on inheritance, events and contract design; generating documentation and architecture diagrams for a contract codebase.

How do I install Smart Contract Guidelines Advisor in Claude Code?

Run `npx skills add trailofbits/skills --skill guidelines-advisor -a claude-code`. Or copy the skill folder (plugins/building-secure-contracts/skills/guidelines-advisor in trailofbits/skills) into .claude/skills/guidelines-advisor in your project. Claude Code loads it when a task matches its description.

How do I install Smart Contract Guidelines Advisor in Codex?

Run `npx skills add trailofbits/skills --skill guidelines-advisor -a codex`. Or copy the skill folder (plugins/building-secure-contracts/skills/guidelines-advisor in trailofbits/skills) into .agents/skills/guidelines-advisor in your project. Codex loads it when a task matches its description.

Can I use Smart Contract Guidelines Advisor in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add trailofbits/skills --skill guidelines-advisor -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/guidelines-advisor, .gemini/skills/guidelines-advisor, .github/skills/guidelines-advisor and .opencode/skills/guidelines-advisor in your project.

What does Smart Contract Guidelines Advisor need to run?

SKILL.md names no scripts, command-line tools or credentials: Smart Contract Guidelines Advisor is instructions for the agent only.

Does Smart Contract Guidelines Advisor access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Smart Contract Guidelines Advisor safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Smart Contract Guidelines Advisor use?

Smart Contract Guidelines Advisor is published under the CC-BY-SA-4.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Smart Contract Guidelines Advisor use?

About 2.2k tokens (SKILL.md is roughly 8.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Smart Contract Guidelines Advisor?

Skills that share tags, products or a category with Smart Contract Guidelines Advisor: Developing Smart Contracts (LFDT-Lineth/lineth-monorepo, 126 stars), Foundry Reference Model (aviggiano/security, 144 stars), Fizz Convert (pashov/skills, 1.2k stars) and Smart Contract Audit (greatpie/smart-contract-audit-skill, 101 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Smart Contract Guidelines Advisor?

trailofbits (a GitHub organization, an official publisher) maintains it in trailofbits/skills, which has 7,400 GitHub stars. The repository holds 79 skills in this directory. The repository was last updated on October 2, 2026.

Source: trailofbits/skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.