Your RTL, minus the chaos.
A coding agent skill that turns a messy Verilog module into a clean, column-aligned, review-ready one — without touching a single gate of logic.
Drop it into your agent once. From then on you just say "tidy this module".
rtl_veteran is not a formatter. It's a house style with teeth.
At its core is SKILL.md — a 1000-line spec for how a Verilog module should be laid out:
declarations up top, logic below, columns aligned to a fixed ruler, one signal per line,
no ?: hiding inside a clocked always. Alongside it sit six zero-dependency Python
scripts that do the parts a human is bad at: aligning columns, scoring style, and
catching the structural bugs that survive lint.
The whole thing is agent-native. You don't run it — your agent does. You describe the outcome, and the agent reads the spec, runs the scripts, verifies, and hands you back a report.
The one promise it makes and keeps: zero logic change. What the synth tool saw before, it sees after. Only three transforms are permitted, and all three are provably netlist-preserving.
- Code review shouldn't be about whitespace. Right now it is. Half the comments on your last PR were "align this" / "move this decl up" / "one signal per line". Automate those; spend the review on the datapath.
wire x = expr;is a trap. It looks tidy. It scatters your logic across the declaration block, and it's the single biggest reason a module becomes unreadable at 800 lines. This skill splits every one of them.- The bug lint can't see. You move a declaration to the top, forget its
assign, and now a wire is declared, connected to an instance port, and driven by nothing. Lint passes. The instance readsz. This skill runs a reverse driver-completeness check because it has bitten us for real. - Three-alarm structural smells, caught mechanically: two independent
ifs writing the same register, a ternary on a nonblocking RHS, and registers in onealwaysthat don't share a write condition. All fixable, all semantic-preserving. - A number, not an argument. "Your code is 4.2 / 10" ends the style debate faster than a thirty-message thread.
- It writes you a report. Every refactor ends with a single self-contained HTML page showing before/after, the rule each change satisfies, and the verification results.
| Two-zone layout | Declarations in Zone 1 (localparam → signals, each under a banner + ASCII ruler), logic in Zone 2 under a // Func Begin directory. Never mixed. |
| Column alignment | Ports, localparam, signal declarations, assign runs, case and always bodies — all aligned to a fixed ruler. Idempotent: run it twice, byte-identical result. |
| Structural lint | Catches same-layer multi-if register writes, ?: on a clocked nonblocking RHS, and mismatched write conditions across registers in one always. Real tokenizers, not grep. |
| Comment tiers | BIG banner vs SMALL note, enforced. Kills //====== ornament lines, half banners, and banner explosions before they flatten your comment hierarchy. |
| Quality score | 8 weighted items, 10 points total, half-life decay curve. Scores the original code — a low score is exactly why you needed the refactor. |
| HTML report | One self-contained page: score panel, per-change cards with real before/after code, verification table, split-view diff. |
| No dependencies | Pure Python 3.6+, no pip install, no network. Runs on EDA hosts from 2015. |
The skill is a folder containing SKILL.md plus scripts. Point your agent at it:
git clone https://github.com/shawnnjupt/rtl_veteran_extension.git| Agent | Where it goes |
|---|---|
| hermes | ~/.hermes/skills/software-development/rtl_veteran/ |
| Claude Code | ~/.claude/skills/rtl_veteran/ |
| Codex CLI | ~/.codex/skills/rtl_veteran/ |
| opencode | ~/.config/opencode/skills/rtl_veteran/ |
One command does most of them:
cp -r rtl_veteran_extension ~/.claude/skills/rtl_veteran💡 opencode reads
~/.claude/skills/too, so installing for Claude Code covers both. Want it per-project instead of global? Use.claude/skills//.codex/skills//.opencode/skills/at your repo root and commit it — the whole team gets the same style.
No commands to memorize. Open the file and ask:
tidy this module
separate declarations from assignments in bpq4x_dda_add_check.v
score this file and tell me what's dragging it down
The agent reads the spec, does the work, runs the checks, and produces the report.
SKILL=~/.claude/skills/rtl_veteran
python3 $SKILL/verilog_assign_align.py path/to/module.v # align columns in place
python3 $SKILL/verilog_quality_score.py path/to/module.v # 8-item score / 10
python3 $SKILL/verilog_w415a_check.py path/to/module.v # multi-if register writes
python3 $SKILL/verilog_proc007_check.py path/to/module.v # ?: on a clocked RHS
python3 $SKILL/verilog_comment_check.py path/to/module.v # comment tier violationsAll checkers exit 1 when they find something, so they drop straight into CI.
Reads your code. Doesn't rewrite your logic. That's the whole deal. 🤝