playbooks

home / skills / plurigrid / asi / guidelines-advisor

guidelines-advisor skill

/skills/guidelines-advisor

This skill analyzes smart contract codebases, derives docs and specs, reviews architecture and upgradeability, and delivers actionable security recommendations.

npx playbooks add skill plurigrid/asi --skill guidelines-advisor

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.8 KB
---
name: guidelines-advisor
description: Comprehensive 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. (project, gitignored)
category: building-secure-contracts
author: Trail of Bits
source: trailofbits/skills
license: AGPL-3.0
trit: -1
trit_label: MINUS
verified: true
featured: false
---

# Guidelines Advisor Skill

**Trit**: -1 (MINUS)
**Category**: building-secure-contracts
**Author**: Trail of Bits
**Source**: trailofbits/skills
**License**: AGPL-3.0

## Description

Comprehensive 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. (project, gitignored)

## When to Use

This is a Trail of Bits security skill. Refer to the original repository for detailed usage guidelines and examples.

See: https://github.com/trailofbits/skills

## Related Skills

- audit-context-building
- codeql
- semgrep
- variant-analysis


## SDF Interleaving

This skill connects to **Software Design for Flexibility** (Hanson & Sussman, 2021):

### Primary Chapter: 5. Evaluation

**Concepts**: eval, apply, interpreter, environment

### GF(3) Balanced Triad

```
guidelines-advisor (○) + SDF.Ch5 (−) + [balancer] (+) = 0
```

**Skill Trit**: 0 (ERGODIC - coordination)

### Secondary Chapters

- Ch4: Pattern Matching

### Connection Pattern

Evaluation interprets expressions. This skill processes or generates evaluable forms.

Overview

This skill is a comprehensive smart contract development advisor built on Trail of Bits' best practices. It analyzes a codebase to produce clear documentation, assess architecture, check upgradeability patterns, review implementation quality, and surface common pitfalls. It returns actionable recommendations focused on security, maintainability, and correctness. The skill is designed to integrate into project workflows while keeping project files and findings local and gitignored.

How this skill works

The skill scans the repository and inspects contracts, libraries, tests, and dependency manifests to build an internal model of the system. It generates documentation and specifications from code and comments, reviews design patterns and upgradeability schemes, and runs heuristic checks for common vulnerabilities and anti-patterns. It examines dependency chains and test coverage to evaluate supply-chain and testing quality. Finally, it synthesizes prioritized, concrete recommendations and remediation steps.

When to use it

  • During design reviews to validate architecture and upgradeability choices.
  • Before security audits to produce a structured specification and risk list.
  • When onboarding new contributors to generate up-to-date documentation.
  • When assessing third-party contracts or dependencies for reuse.
  • To evaluate test coverage and suggest missing test cases or scenarios.

Best practices

  • Run the advisor early and repeatedly during development and after major changes.
  • Treat generated specs as a source for formal review and acceptance testing.
  • Prioritize fixes based on exploitability and business impact in the report.
  • Complement automated findings with manual review for complex logic and economic reasoning.
  • Keep dependency manifests and lockfiles up to date to improve analysis accuracy.

Example use cases

  • Produce a design specification and threat model before a mainnet launch.
  • Review an upgradeable proxy pattern for unsafe initializer or storage-layout drift.
  • Identify risky third-party libraries and suggest safer alternatives or mitigation.
  • Assess test suites and recommend missing scenarios such as edge cases and reentrancy.
  • Create an onboarding document summarizing contract interfaces, invariants, and upgrade constraints.

FAQ

Does the advisor replace a manual security audit?

No. It automates baseline checks and produces actionable guidance but should be used to complement a manual audit by experienced reviewers.

Can it modify project files?

No. It analyzes and reports; remediation suggestions are provided as patches or guidance but changes must be applied by developers.