guidelines-advisor

Overview of guidelines-advisor skill

guidelines-advisor is a smart contract development advisor built around Trail of Bits’ secure development guidelines. It helps you turn a codebase into actionable engineering guidance: clearer documentation, better architecture decisions, upgradeability review, implementation quality checks, pitfall detection, dependency review, and test coverage suggestions.

Who should use guidelines-advisor

Use the guidelines-advisor skill if you are working on Solidity or other smart contract projects and need a structured review instead of a generic prompt response. It is especially useful for technical writers, protocol engineers, auditors, and teams preparing internal specs or review notes.

What it is best at

The guidelines-advisor skill is strongest when you need a guided assessment of the repository itself: what each module does, where assumptions are missing, whether upgrade patterns are documented, and how testing or dependencies could be improved. It is less about rewriting code and more about producing a decision-grade analysis of the system.

When it is a good fit

Choose guidelines-advisor when your real job is to explain, assess, or document a contract system with enough rigor to support reviews, handoffs, or safer iteration. It is a strong fit for guidelines-advisor for Technical Writing workflows where the output must be plain English, architecture-aware, and grounded in the codebase.

How to Use guidelines-advisor skill

Install and load the skill

Install with:

npx skills add trailofbits/skills --skill guidelines-advisor

For guidelines-advisor install, confirm you are pointing at the trailofbits/skills repository and the plugins/building-secure-contracts/skills/guidelines-advisor path. After install, start from SKILL.md and then read the supporting resources.

Read these files first

For the fastest ramp-up, preview:

• SKILL.md for scope and workflow
• resources/ASSESSMENT_AREAS.md for the review checklist
• resources/DELIVERABLES.md for the expected outputs
• resources/EXAMPLE_REPORT.md for the shape of a finished analysis

These files show what the skill will actually produce, which matters more than the repo name alone.

Give the skill a complete input

The best guidelines-advisor usage starts with a concrete target, not a vague request. Good input usually includes the project type, what changed, what you want assessed, and any constraints.

Better prompt:

Analyze this Solidity protocol repo for documentation gaps, upgradeability risks, dependency issues, and test coverage weaknesses. Focus on components that affect user funds and upgrade paths. Summarize findings in plain English and suggest concrete next steps.

Weaker prompt:

Review this repo.

Use it as a workflow, not a one-shot

A practical guidelines-advisor guide is:

1. Ask for a system overview first.
2. Then request architecture, upgradeability, and implementation review.
3. Finally ask for documentation gaps and test improvements tied to the repo’s actual structure.

If the repository has no upgrades or no off-chain component, say so up front. That prevents wasted analysis and keeps the output grounded.

guidelines-advisor skill FAQ

Is guidelines-advisor only for Solidity?

No, but it is most valuable for Solidity and smart contract systems. The strongest guidance in the repository is centered on building secure contracts, so non-contract projects may get less value.

How is it different from a normal prompt?

A normal prompt can ask for a review, but guidelines-advisor gives you a repeatable framework: discovery, documentation generation, architecture analysis, and implementation review. That structure reduces guesswork and makes the output easier to compare across repos.

Is it beginner-friendly?

Yes, if you want a guided explanation of a contract codebase. You do not need to know every secure-development rule in advance, but you do need a real repository and a specific goal. Beginners get the most value when they ask for plain-English documentation plus the main risks.

When should I not use it?

Do not use guidelines-advisor if you only want a quick code summary, a generic audit checklist, or analysis of a project with no meaningful contract architecture. It is also not the right fit if you need a narrow bug fix rather than a broader engineering review.

How to Improve guidelines-advisor skill

State the decision you need to make

The best way to improve guidelines-advisor skill output is to tell it what the review is for: onboarding, documentation cleanup, upgrade planning, security hardening, or release readiness. That focus changes which findings matter most.

Name the parts of the repo you care about

Strong inputs mention the relevant contracts, packages, or flows, such as proxy contracts, upgrade logic, fee paths, token transfers, or test suites. If you only want guidelines-advisor for Technical Writing, say that and ask for missing explanations, unclear assumptions, and better NatSpec targets.

Ask for evidence-based output

Ask for findings tied to file paths, functions, patterns, or missing docs. That makes the result easier to verify and reduces vague commentary. For example:

Prioritize undocumented assumptions in contracts/, upgradeability issues in proxy flows, and missing test coverage around external calls.

Iterate after the first pass

The first output is most useful as a map. Use it to ask narrower follow-ups: “expand the upgradeability section,” “list missing NatSpec by file,” or “turn these findings into a documentation backlog.” That workflow produces sharper results than asking for everything at once.