---
name: duck-rtl
description: Build, explore, and verify Verilog/SystemVerilog RTL. Use when the user wants to write an RTL module, understand or review existing Verilog, or verify a design against a Python golden model with cocotb. Also extracts and diagrams control FSMs from the AST (deterministic, no hallucinated states) when a state diagram is explicitly wanted — but default to writing or reading Verilog, not diagramming.
---

# Duck RTL — Verilog build/explore + token-optimized co-sim loop

Default behavior: **write Verilog or explore the existing code** in the repo. This skill provides deterministic guardrails for building and verifying RTL against a Python Golden Model, plus an optional AST-based FSM extractor (structure from the **AST**, labels from *you* — no LLM backend, no API key) for when a state diagram is explicitly requested.

## When to use
- Write / scaffold a new Verilog module
- Understand, review, or modify existing RTL in this repo
- Verify a design against a Python golden model (ledger → scaffold → check → cocotb sim)
- *Only when explicitly asked:* diagram / visualize the control FSM of a module

## Operating instructions

The full flow — the relabeling contract, the co-sim build loop (Rules 1–5), and the
Verilog-2001 constraints — lives in **`${CLAUDE_PLUGIN_ROOT}/AGENTS.md`.** Read it before
proceeding; it's the single source of truth and is kept in sync for every agent.

Invoke the CLI through the plugin root so it works from any project directory
(`${CLAUDE_PLUGIN_ROOT}` is set by Claude Code to this plugin's install path).

Quick reference (FSM diagram, the common case):
```bash
python "${CLAUDE_PLUGIN_ROOT}/main.py" extract --file module.v --out graph.json   # raw graph, deterministic
# read graph.json; write labels.json: {"states":[{"id","label"}],"edges":[{"id","label"}]}
python "${CLAUDE_PLUGIN_ROOT}/main.py" render --graph graph.json --labels labels.json --out fsm.svg
python "${CLAUDE_PLUGIN_ROOT}/main.py" run    --file module.v --out fsm.svg        # one-shot, raw conditions as labels
```

Prereqs (once): `pip install -r "${CLAUDE_PLUGIN_ROOT}/requirements.txt"`, plus `iverilog` and Graphviz `dot` on PATH.