| name | findings-writer |
| description | Write professional smart contract security findings and append them to a file. Trigger this skill when the user types the command /write-the-finding (case-insensitive). |
Smart Contract Security Findings Writer
Convert vulnerabilities discussed in conversation into clear, concise, judge-proof security findings and append them to a specified file.
Findings are formatted for audit platforms: Code4rena, Sherlock, Cantina, Immunefi, or similar.
The skill accepts flags in any order: -file (markdown file to write to), severity as H, M, or L (High, Medium, Low), platform as Code4rena, Sherlock, Immunefi, or Cantina (case-insensitive). If any flag is missing, ask for it before proceeding.
Inputs
The skill is triggered exclusively by the slash command:
/write-the-finding -file <filename> -severity <H|M|L> -platform <platform>
Flags (any order, case-insensitive):
| Flag | Values | Description |
|---|
-file | any filename | Markdown file to append the finding to |
-severity | H, M, L | Maps to High, Medium, Low |
-platform | Code4rena, Sherlock, Immunefi, Cantina | Target submission platform (case-insensitive) |
Examples:
/write-the-finding -file findings.md -severity H -platform sherlock
/write-the-finding -platform Cantina -severity m -file audit/issues.md
If any flag is missing, ask for it before proceeding. The vulnerability content comes from the current conversation context.
Your Responsibilities
- Identify the vulnerability from the conversation or user input
- Write a complete, professional finding
- Format it per the target platform's style
- Append it to the provided file (never overwrite)
- Confirm to the user what was written and where
Writing Rules
1. Extremely Clear and Simple
- Write in plain, direct English
- Judges must understand the issue immediately
- Avoid: complicated language, unnecessary theory, long paragraphs
- Prefer: short explanations, structured sections, direct statements
2. Impossible to Invalidate
- Base all arguments on code behavior
- Avoid speculation or hypothetical claims without proof
- Prove the issue with: code references, logical reasoning, clear impact explanation
3. Concise but Complete
- Short enough to read in under 1 minute
- No filler text - every sentence must add value
4. Code References with Relative Links
Always use relative markdown links when referencing code:
[Contract.sol:123](path/to/Contract.sol#L123)
[transfer() implementation](src/token/Token.sol#L45)
5. Reference Protocol Documentation When Useful
Link to README, invariants, or design docs to strengthen the argument:
[README: liquidation assumptions](README.md#liquidation-model)
6. Show Real Impact
Every finding must explain:
- what goes wrong
- when it happens
- why it matters
Avoid vague statements like "may cause issues." Say instead:
"This allows a user to withdraw more tokens than deposited."
Finding Structure
Use this structure unless the platform requires otherwise:
## Title
Short, direct description of the issue.
## Summary
2-3 sentences: what the issue is, where it happens, what the consequence is.
## Root Cause
Exactly why the vulnerability exists. Include code references.
## Vulnerability Details
Step-by-step explanation of the faulty logic and resulting incorrect state.
## Impact
Real consequence - who can exploit it, what they gain.
Examples: funds stolen, tokens minted without backing, invariants broken.
## Proof of Concept (if applicable)
Minimal steps to trigger the issue. No full test unless necessary.
## Mitigation
Simple, concrete fix suggestion.
Platform Formatting
| Platform | Style |
|---|
| Code4rena | Standard markdown sections |
| Sherlock | Concise markdown issue format |
| Cantina | Structured markdown issue |
| Immunefi | Impact-driven report |
Always preserve the same logical sections regardless of platform.
File Handling
Append findings to the provided file in this format:
---
## [Severity] Finding Title
(full finding content)
---
Never overwrite existing findings. Always append at the end.
If the file does not exist, create it with a header:
# Security Findings
Tone
- Professional, confident, factual, neutral
- Do NOT exaggerate impact
- Arguments must stand on clear logic and code references
Goal
Produce findings that:
- Judges can read quickly and understand immediately
- Are difficult to dispute
- Clearly demonstrate a real vulnerability
- Look professional and audit-quality
