Compiling the Hacker's Intuition: Inside shuvonsec/web3-bug-bounty-hunting-ai-skills

How a strictly orchestrated collection of Markdown files turns generic LLMs into economically-aware Web3 security auditors.

7 min read • View on GitHub • More from shuvonsec

A mechanical arm pulling specific books from a classical library shelf in a numbered sequence, ignoring dusty papers on the floor. This represents structured, sequential knowledge retrieval for machines versus unstructured data. — By structuring knowledge explicitly for AI ingestion, the repository forces generic models to follow a rigid investigative path.

Key Takeaways

The repository relies on structured Markdown files acting as a state machine to orchestrate sequential reasoning in LLMs.
Hardcoded heuristics derived from over two thousand reports prevent the AI from generating low-severity noise.
A rigid 10-point scorecard forces the model to evaluate the economic viability of a potential exploit before reporting it.

A Textbook for the Machine

We have moved past writing software for humans to execute. We are now writing curriculums for AI agents to read. This repository is not a tool, a script, or a framework. It is an operating system made entirely of highly structured Markdown files. It codifies the raw intuition of expert Web3 security auditors into deterministic skill chains that prevent LLMs from hallucinating.

Feeding a raw codebase to an LLM usually results in informational noise. The AI flags every minor deviation from best practices. This repository acts as a structured brain, curating real-world reports into readable files that teach the AI what actually matters.

18 Claude Code skill files for smart contract security — built from 2,749 Immunefi reports, 681 DeFiHack reproductions, and real hunt experience

shuvonsec, Project Creator · shuvonsec/web3-bug-bounty-hunting-ai-skills

Chaining the AI's Thoughts

The repository uses a directed graph approach to learning. Each file ends with a NEXT pointer, ensuring that an AI reading the repository maintains a logical flow from mindset to exploitation to reporting. This prevents the AI from skipping straight to hallucinated exploits.

The Skill Chain forces the LLM to traverse a strict directed graph, preventing it from reporting vulnerabilities without generating a Proof-of-Concept.

The Sibling Rule and the War on Noise

The repository distills complex vulnerabilities into simple heuristics. One such abstraction is the Sibling Function Rule. If one function has a security modifier, the AI is instructed to immediately check its sibling function. This simple heuristic is cited as explaining nearly a fifth of all critical findings.

Two identical vault doors side-by-side. The left door is secured with a massive padlock. The right door is slightly ajar, revealing a missing internal latch. This illustrates the Sibling Function Rule where one function is secured but its pair is forgotten. — The Sibling Function Rule codifies a common developer oversight: securing one function perfectly while forgetting to apply the exact same modifier to its pair.

The Economics of the Exploit

A bug is only a bug if it results in a net return on investment for the attacker. The foundation skills implement a strict 10-point scorecard. An AI usually just looks for code flaws, but this repository trains the AI to act like a mercenary.

An old-fashioned merchant's scale. On one side, a single line of glowing code. On the other side, a stack of heavy gold coins and a tiny hourglass. The scale tips heavily toward the coins, illustrating economic cost and ROI prioritization. — The 10-point scorecard trains the AI to evaluate the total value locked and the gas cost of the attack, ignoring technically correct but economically unviable bugs.

The End of the Human Grep

Traditional security wikis are built for human readers. This repository represents a paradigm shift toward AI-orchestrated workflows. It bridges the gap between finding a theoretical bug and proving a profitable exploit.

Feature	Traditional Security Wikis	AI-Native Skill Chains
Target Audience	Human Readers	LLM Context Windows
Structure	Categorical lists	Directed Graph with NEXT pointers
False Positive Filtering	Left to human intuition	Hardcoded Kill Signals in prompts
Final Output	Text description of the bug	Executable Foundry Proof-of-Concept