Skip to content
Back to search

verilog-generator

Agent skill for Verilog-2001 RTL generation and FPGA design workflows.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Eriemon/verilog-generator with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Eriemon/verilog-generator'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/eriemon--verilog-generator/badge.svg)](/listings/eriemon--verilog-generator)

HTML

<a href="/listings/eriemon--verilog-generator"><img src="/api/listings/eriemon--verilog-generator/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> Ask your AI to install the skill from https://github.com/Eriemon/verilog-generator.

After installation, call the skill in the same conversation with `$readable-verilog-generator` or describe the Verilog task directly.

The v2.0.0 release package also includes `install.ps1`, `install.sh`, and `install.bat` beside `SKILL.md` for manual installation. Supported Harness targets are Codex (`codex`), Claude (`claude`), Gemini (`gemini`), and DeepSeek (`deepseek`). From the release directory, preview and install with one of these commands:

.\install.ps1 -Platform codex -DryRun -Json
.\install.ps1 -Platform codex -Json
./install.sh --platform codex --dry-run --json
./install.sh --platform codex --json
install.bat -Platform codex -DryRun -Json
install.bat -Platform codex -Json

Real wrapper writes automatically back up an existing target before replacement; `DryRun` never writes. Source directories without the configured release receipt are rejected. See `references/skill/installation.md` for the parameterized contract.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 140 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: readable-verilog-generator
  3. description: >-
  4. Use when creating, writing, reviewing, annotating, repairing, refactoring, or validating readable Verilog RTL, including synthesizable Verilog-2001 .v files, existing-RTL analysis, semantic comment annotation, testbench scaffold planning, ASIC-quality review, local or remote Vivado/xsim validation, evidence-backed repair, and workflow trace diagnosis.
  5. ---
  6. # Readable Verilog Generator
  7. Generate, analyze, improve, and verify readable Verilog-2001 RTL through the bundled runtime under `scripts/python/`. Keep design RTL and verification testbenches in `.v` files, use `scripts/python/facade/verilog_api.py` for host integration, and treat formatter-AST and external-tool evidence as stronger than model self-assessment.
  8. ## Route
  9. - `create/write`: confirm the design contract, then use `requirements -> codegen_plan -> spec_document -> python -> rtl`.
  10. - `deep_review`: insert a non-empty structured review between the Python semantic model and RTL; it must cover interface, reset, timing/pipeline, handshake or FSM behavior, width, synthesis, testbench coverage, and risks.
  11. - `review/analyze`: remain read-only and report the eight public gate states before suggesting changes.
  12. - `annotate`: preserve an immutable normalized baseline, change only `//` comments, prove token equivalence from that baseline, and rerun the final deliverable gate.
  13. - `repair/refactor`: bind the task to real RTL, reproduce or validate the issue, and apply the smallest evidence-backed change.
  14. - `agentic_repair`: use the existing-RTL `verify_existing_verilog(...)` loop with an explicit `conservative`, `semi_auto`, or `auto_apply` choice.
  15. - `validate`: collect static or external evidence without implicitly editing RTL.
  16. - Load `references/workflows/verilog_dispatcher.md` before routing. Existing assets, logs, waveform clues, and mixed inputs use its read-only entry decision before any generation, validation, backup, or remote action.
  17. ## Install v2.0.0
  18. The package root contains `install.ps1`, `install.sh`, and `install.bat` beside this `SKILL.md`. They share the package-local Python backend and read only the generated installer projection under `assets/installer/` plus the same-level bootstrap descriptor. Platform IDs, root resolution, target templates, status text, exit codes, transaction policy, and verification cases are data-driven by `config/installer/`; do not add platform branches or current test values to code or comments.
  19. Install only from a versioned payload with the configured `RELEASE_RECEIPT.json`. Use `--DryRun`/`--dry-run` to validate without creating transaction resources; use replacement flags only when the target and overwrite intent are explicit. A transaction handles one platform and one target, preserves unlisted target files, writes an install receipt, and attempts rollback on failure. Unknown IDs and source directories without a valid release receipt fail closed. See `references/skill/installation.md` for the complete contract and parameterized invocation templates.
  20. ## Generate And Modify
  21. 1. Confirm module name, ports, clock/reset, behavior, pipeline expectation, interface family, and verification cases.
  22. 2. Use `regular` by default; use `deep_review` only when its extra review stage adds value; use `agentic_repair` only for existing RTL.
  23. 3. Generate a Python semantic model before RTL in the staged workflow and use it as the testbench semantic contract.
  24. 4. Select local interface and ADC/DAC family templates only when the confirmed design matches them; record every adaptation in the requirements and codegen plan.
  25. 5. Keep batch execution generation-only, with one run directory per confirmed spec. Do not use batch mode for existing-RTL mutation or decision resume.
  26. 6. Treat streaming as provider interaction only. The finalized response artifact remains the extraction source of truth.
  27. 7. Run the strict generated-deliverable gate before downstream use. Optional lint and testbench helpers never replace it.
  28. Every module generated or modified by this skill must ship with a same-name `<module>_spec.md` companion. The canonical JSON contract accepts a single legacy module projection or a `modules` array, but each normalized module must declare a safe `.v` `rtl_path`, complete interface ports, clock/reset semantics, cycle behavior, constraints, corner cases, verification cases, and at least one `timing_diagrams` entry. A timing entry contains `id`, `title`, `scenario`, `description`, and WaveJSON with named signals. `python -m scripts.python.workflow.cli write-spec --spec <spec.json> --out-dir <artifact-root> [--source <rtl.v>] --language <zh|en>` writes `spec/<feature>/<module>_spec.md` plus sibling `spec/<feature>/waveforms/<module>_<scenario>.json5` and `.svg`. The `--source` form fails closed when a module or port is undeclared; the no-source form validates and renders only the confirmed spec and never infers behavior from RTL. All waveform rendering goes through the renderer runtime declared by the settings authority and fails closed when its configured Node/npm prerequisites, package identity, version, or executable are unavailable. A render failure stages diagnostics without overwriting the previous valid bundle.
  29. The default profile is `erie_strict`. Its authoritative naming, bilingual header, region, FSM, comment, port-order, runtime-message, and formatter-AST rules live in `references/rules/verilog-code-comment-naming-standard.md`, `references/rules/erie-style.md`, `references/rules/verilog-comment-placement.md`, and machine-readable assets. Do not duplicate those rule catalogs in this entry document.
  30. ## Quality
  31. Strict quality control is mandatory. ASIC quality review, independent static lint, and testbench scaffold are optional workflow steps selected only when the task needs their evidence. Optional helper tools are inside the workflow and never replace the generated-deliverable gate.
  32. Generated deliverables must pass the formatter-backed gate with zero errors and zero strict warnings. The public result matrix is exactly `compile`, `ast`, `readability`, `comment`, `naming`, `profile`, `testbench`, and `toolchain`; static compile evidence does not imply that an external simulator, synthesis, or remote validation ran.
  33. Verilog/SystemVerilog filenames must describe real function. Functional digits are valid; VG148 rejects only terminal version or meaningless numeric suffixes. A file recognized as a testbench by `tb_`, `_tb`, `testbench`, or an exact `tb`/`testbench`/`sim` directory must use the `tb_<function>.v` or `tb_<function>.sv` form; `_tb` is recognition evidence, not an allowed output name. When an ordinary design filename carries at least two independent testbench-content evidence groups, VG149 remains inconclusive until the user confirms `design` or `testbench` through `file_role_confirmations`. Confirming `testbench` does not waive the prefix rule: rename the file to the authority-selected `tb_<function>` form before it can pass. VG150 rejects configured workflow/evidence phrases on entity comments and high-confidence periodic unrelated tail families; it does not blacklist ordinary Chinese words or isolated functional descriptions. The full filename and comment contract lives in `references/rules/verilog-code-comment-naming-standard.md`, and gate/report semantics live in `references/rules/verilog-quality-gates.md`.
  34. Use strict mode for new or modified deliverables. `--non-strict --warn-only` is limited to historical reference-corpus analysis and never approves generated output. The formatter backend under `scripts/python/quality/formatter_backend/` is the parser source for quality checks; do not add a second Verilog parser.
  35. For comment-only work, normalize the original RTL once, annotate a copy, run the comment-only verifier with a required delta, run the final gate, and compare the final file again against the immutable baseline. Comments must not change RTL tokens, modules, ports, lvalues, resets, always targets, or instance connections. Reused generic entity comments do not satisfy semantic-comment coverage.
  36. When `VG097` cannot see an external XPM, UNISIM primitive, or project-generated IP interface, first consult the exact-name AMD-Xilinx primitive catalog in `assets/xilinx_primitive_semantics.json` and its detailed contract in `references/rules/xilinx-primitive-exemptions.md`. Keep the result `inconclusive` until a governed pure-interface `.v` source is supplied through the repeatable `--external-interface-source` option when the name is not cataloged or the profile conflicts. Use the registered `quality.external-interface-extract` command for explicit vendor-source module whitelists and `quality.external-interface-manifest` for reviewed project-IP contracts. Never infer that an unknown width is a mismatch, and never use a stub or primitive profile as simulation, synthesis, implementation, or hardware evidence.
  37. Generated RTL must remain synthesizable Verilog-2001. Prefer the governed interface templates for AXI-Stream, AXI4-Lite, AXI4, AHB, and APB; use complete combinational assignments and case defaults; avoid raw gated clocks; document CDC/reset assumptions; keep datapath and control timing-reviewable; and avoid generated `function` or `task` blocks when explicit logic is clearer for waveform debug. Every FSM must use three independent processes for the state register, procedural combinational next-state logic, and state output/task logic; a continuous `assign` to any next-state signal is forbidden. Every continuous or procedural combinational target must pass both the transitive source-cone limit and the configured real-operation budget, each defaulting to at most three. VG146/VG147 evaluate the complete source closure: formatter structured port associations bind child outputs into the parent cone, parameter/localparam specialization selects the materialized implementation, and each definition root, full instance path, specialization fingerprint, and static target remains an independent report identity. Output connections expand through known implementations; inout and unresolved-net boundaries never invent reverse ownership; all known wire/tri drivers are merged; and a clocked output Q cuts upstream expansion while its D input remains checked. The operation budget covers unary, binary, ternary, comparison, selector, control-decode, continuous-assign, combinational-process, clocked D-input, and elaborated `for` operations. Moving logic into `always @(*)` or directly into a clocked D expression does not bypass either gate. If `loop_presence=unknown`, VG146 and VG147 both apply and share the same lower-bound evidence: an over-limit known lower bound fails both, otherwise both remain inconclusive. When the operation budget fails, recommend pipeline registers, registered flags or predecode, or a multicycle FSM decomposition first, and disclose that these changes may alter visible latency; immutable-latency protocols require manual architecture review. Only an exact output bridge from an output port to a clocked internal `_o` `reg` is exempt from the source-cone rule. Detailed VG rules and ASIC review criteria remain authoritative in `references/rules/verilog-quality-gates.md` and `references/rules/asic-verilog-quality.md`.
  38. VG151-VG155 provide module-independent structural contracts. Parameter constraints are selected automatically from the identifiers in each restricted expression; `module`, `instance`, `hierarchy`, and `scope` fields are invalid. VG152 reports large dynamically selected packed storage with a configurable positive threshold and offers structured case/FSM, inferred-memory, or vendor-memory alternatives. VG153/VG154 expose read-without-driver and unused declaration evidence, including reg/wire/function/task facts. VG155 uses explicit top-level ready-valid role facts and requires both valid and ready for a transfer consumer; no target module name is part of these contracts.
  39. Before generating or repairing declarations, apply VG156-VG158 as design-time naming and comment constraints, not only as a final audit. VG156 checks every module/function/task variable declaration by underscore token: a token containing digits is valid only when its complete case-insensitive text appears in the governed protocol/algorithm/rate allowlist. VG157 forbids ordinary-comment version markers such as `v2` or `version 3`; only the formatter-recognized fixed bilingual header and revision-history range is exempt. VG158 repeatedly removes the governed direction/type prefixes and `_o`, then requires at least one functional token outside the closed meaningless-token set; unknown domain terms pass. The formatter must assign each declaration to exactly one region using the shared conflict priority, place the first group comment directly below its banner, place later group comments after exactly one blank line, leave no empty group, keep one trailing blank line per non-empty region, and produce byte-identical output on the second pass.
  40. ## Existing RTL
  41. - `analyze_existing_verilog(...)` owns structural analysis and durable design explanation.
  42. - `improve_existing_verilog(...)` owns controlled testbench, style, partition, merge, and optimization assist flows.
  43. - `compare_verilog_semantics(...)` owns equivalence, QoR, and transform-validation evidence.
  44. - `verify_existing_verilog(...)` owns log-driven verification, diagnosis, candidate patches, confirmation resume, and terminal closure.
  45. `optimize_assist` and `merge_assist` are assist-only by default and never silently accept or rewrite source RTL. `conservative` is report-only; `semi_auto` requires confirmation before overwrite; `auto_apply` is valid only after explicit selection and still downgrades non-eligible patch classes to confirmation. Preserve source and testbench backups, diff and decision artifacts, diagnostics, and terminal status exactly as specified by `references/workflows/workflow-contracts.md` and `references/integration/host-integration.md`.
  46. Existing-RTL diagnostic comment findings are advisory so compile, semantic, interface, and high-confidence lint failures remain visible. A report file being written is not success; blocker, warning, failed, toolchain, external-validation, or confirmation-blocked terminal states remain non-success.
  47. ## Dependencies And External Evidence
  48. Run dependency preflight before first use and before remote, Vivado, or Vitis work. Missing required dependencies require user approval before installation; if declined, continue only with self-contained static Verilog work and block remote/execute/implement claims. The required skill dependency remains `erie-remote-ssh`; the optional context-engineering group is the only recommended external skill group. No additional external skill suite is included. The required external renderer dependency, package identity, version, executable, and Node/npm floor are read from the settings authority; use `scripts/python/toolchain/wavedrom_runtime.py` with the `check`, `install --yes`, or `render` subcommand, never an ad-hoc package command. Prefer `vivado-developer` and `vitis-developer` for AMD-Xilinx, and `pds-developer` for PangoMicro. FPGA-Agent-Skills remains an explicit manual fallback.
  49. Compile, execute, simulation, synthesis, or implement readiness requires actual external evidence. Remote validation is preferred and must use `erie-remote-ssh`, a user-confirmed server, local-only server selection/configuration, and the remote workdir's `.settings/verilog.remote.json`. A configured default is only a recommendation. Multiple Vivado settings candidates require user selection. Do not silently fall back to local tools and do not add direct SSH/SCP logic.
  50. Remote validation runs are retained by default, including fixed remote-fixture reports. Cleanup occurs only when explicitly requested. Vivado xsim is the preferred simulator backend, followed by VCS+Verdi and then iverilog/vvp; yosys is implement-readiness evidence only. VCS+Verdi support is scripted backend invocation, not full GUI/session automation.
  51. ## Document And Command Registry
  52. Registration is enabled for this skill. Markdown remains the authoritative knowledge source. Editable command records live under `config/registry/commands/`; document responsibilities and search metadata have one owner in `config/registry/documents/catalog.json`; current duplicate and interface decisions live in `config/registry/governance/reviews.json`; `config/registry/registry.sqlite3` is a generated local FTS5 trigram index at the location required by the agents-md-generator gate. The skill runtime is self-contained and must not import or call an external `agents-md-generator` registry implementation.
  53. Document governance scans `SKILL.md` and every Markdown file below `references/`, recursively. It records one responsibility per document, knowledge pointers, exact and fuzzy duplicate adjudications, interface mappings, and content hashes. Remove only confirmed equivalent duplication; preserve structural repetition and every unique contract. Installed copies may query and check but must not mutate registry sources.
  54. Detailed command syntax, examples, prerequisites, outputs, exit codes, risk warnings, and relations are retrieved from the local registry:
  55. ```text
  56. python -m scripts.python.registry.query_registry ask "<question>" [--kind <kind>] [--category <name>] [--limit 1..10] [--json]
  57. ```
  58. The query is read-only and never executes returned commands. Exit codes are `0` for hits, `1` for no match, `2` for request errors, and `3` for a missing, corrupt, stale, or incompatible index. After JSON source changes, use registry instruction `registry.build`; never edit SQLite by hand. See `references/skill/script-guide.md` for the compact registry lifecycle.
  59. ## Verify
  60. The first outer command group is the generated-deliverable gate:
  61. ```text
  62. python -m scripts.python.validation.generated_deliverable_gate <rtl-file-or-dir> --json <report.json> --markdown <report.md>
  63. ```
  64. When either report option is omitted, the CLI writes both reports under the caller's current working directory: `reports/readable/deliverable_gate.json` and `reports/readable/deliverable_gate.md`. The focused quality CLI follows the same policy with `quality_gate.json` and `quality_gate.md`. Supplying one explicit path only overrides that format; JSON and Markdown paths must resolve to different files. Runtime reports must never be written back to the source or installed skill root.
  65. Both CLIs publish v3 reports and print compact `[Python]` finding lines containing the VG rule, status, confirmed location, concrete problem, and direct fix instruction. The JSON and Markdown files contain the full evidence, ordered repair steps, risk and human-review obligation, plus bad/good examples. Exit code `1` means the gate found RTL issues; exit code `2` means invocation, diagnostic-contract, or report-publication failure.
  66. The second outer command group is package validation:
  67. ```text
  68. python -m scripts.python.validation.validate_verilog_skill --settings .\config\defaults.json
  69. ```
  70. Run the smallest relevant checks while editing, then the governed final chain. The extended repository-regression, external-audit, and remote variants live in `references/integration/configuration.md` and registry instruction `validation.skill`. Local success does not replace requested remote pytest, simulator, synthesis, or installed-copy evidence. Never claim an unrun check passed.
  71. ## Resources
  72. - `references/skill/script-guide.md`: registry query, build, document-governance, and command-category contract.
  73. - `references/workflows/verilog_dispatcher.md`: task classification, public gate matrix, and safe repair boundary.
  74. - `references/workflows/workflow-contracts.md`: run artifacts, statuses, resume behavior, and trace semantics.
  75. - `references/integration/configuration.md`: paths, dependencies, remote settings, and validation configuration.
  76. - `references/integration/host-integration.md`: facade functions and host-owned execution boundaries.
  77. - `scripts/python/workflow/spec_document.py`: strict module contract, source cross-check, Markdown and WaveDrom bundle writer.
  78. - `scripts/python/toolchain/wavedrom_runtime.py`: pinned Node/npm/WaveDrom check, explicit install, and SVG renderer.
  79. - `references/rules/verilog-code-comment-naming-standard.md`: canonical readable RTL rule text.
  80. - `references/rules/verilog-quality-gates.md`: VG catalog and report semantics.
  81. - `references/rules/xilinx-primitive-exemptions.md`: exact AMD-Xilinx UNISIM/XPM/project-IP primitive inventory and VG097/VG132/VG146/VG147 boundary contract.
  82. - `references/rules/asic-verilog-quality.md`: ASIC quality review criteria and risk boundaries.
  83. - `references/rules/testbench-patterns.md`: self-checking testbench scaffold patterns.
  84. - `references/checklists/lint-checklist.md`: independent static lint review checklist.
  85. - `references/corpus/verilog-style-observations.md`: empirical ideal/bad corpus observations that do not override normative rules.
  86. - `references/checklists/verilog-readability-gate.md`: final human review.
  87. - `references/skill/skill-standards.md`: skill packaging and progressive-disclosure requirements.
  88. ## Boundaries
  89. - Do not generate non-Verilog hardware flows, C/C++ kernels, or alternate RTL dialects.
  90. - Do not invent source RTL, testbenches, logs, successful tool evidence, or repair confirmation.
  91. - Do not store caller run artifacts inside the skill; use caller-selected directories such as `reports/`.
  92. - Do not let optional helpers, model reviews, or registry query results replace actual quality or toolchain evidence.
README.md · README · 194 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <a href="README.md"><strong>English</strong></a>
  3. <span>&nbsp;|&nbsp;</span>
  4. <a href="README-CN.md">Chinese</a>
  5. </p>
  6. <p align="center">
  7. <img src="assets/readme/hero-overview.png" alt="Verilog Generator: from RTL intent to reviewable delivery" width="100%">
  8. </p>
  9. <p align="center">
  10. <a href="LICENSE"><img alt="Apache-2.0 license" src="https://img.shields.io/badge/license-Apache--2.0-2ad4ee"></a>
  11. <img alt="VERSION v2.0.0" src="https://img.shields.io/badge/version-v2.0.0-8ce85d">
  12. <img alt="Verilog-2001" src="https://img.shields.io/badge/RTL-Verilog--2001-ffb85c">
  13. <img alt="Agent skill" src="https://img.shields.io/badge/target-agent%20skill-8ce85d">
  14. </p>
  15. <p align="center">
  16. <strong>Readable RTL → clear behavior → reviewable delivery</strong><br>
  17. Give AI the design intent, review the behavior preview, and receive artifacts you can inspect and verify.
  18. </p>
  19. Verilog Generator is an agent skill for practical Verilog-2001 work. It helps you create a module from a clear requirement, understand an existing RTL design, add semantic comments, repair a problem from real diagnostics, and run the checks that your task actually needs.
  20. ## What it does
  21. - Turn a module requirement into readable, synthesizable Verilog-2001 RTL.
  22. - Explain an existing module through its ports, clock/reset behavior, state, timing, and data flow.
  23. - Add or improve semantic comments without silently changing RTL behavior.
  24. - Repair an existing design against a compiler, linter, simulator, or tool log.
  25. - Prepare a testbench scaffold or request real simulation results when the environment is available.
  26. The skill keeps results honest: a static review, a simulation, a synthesis run, and a hardware result are reported separately. A check that did not run is never presented as a completed result.
  27. ## Install
  28. > Ask your AI to install the skill from https://github.com/Eriemon/verilog-generator.
  29. After installation, call the skill in the same conversation with `$readable-verilog-generator` or describe the Verilog task directly.
  30. The v2.0.0 release package also includes `install.ps1`, `install.sh`, and `install.bat` beside `SKILL.md` for manual installation. Supported Harness targets are Codex (`codex`), Claude (`claude`), Gemini (`gemini`), and DeepSeek (`deepseek`). From the release directory, preview and install with one of these commands:
  31. ```text
  32. .\install.ps1 -Platform codex -DryRun -Json
  33. .\install.ps1 -Platform codex -Json
  34. ```
  35. ```bash
  36. ./install.sh --platform codex --dry-run --json
  37. ./install.sh --platform codex --json
  38. ```
  39. ```bat
  40. install.bat -Platform codex -DryRun -Json
  41. install.bat -Platform codex -Json
  42. ```
  43. Real wrapper writes automatically back up an existing target before replacement; `DryRun` never writes. Source directories without the configured release receipt are rejected. See `references/skill/installation.md` for the parameterized contract.
  44. ## Before you start
  45. Prepare only the material that matches your task:
  46. ![What to prepare for a Verilog task](assets/readme/project-facts.png)
  47. - **New module:** purpose, module name, ports, clock and reset semantics, cycle-by-cycle behavior, protocol rules, boundary cases, and the checks you expect.
  48. - **Existing RTL review:** the `.v` files, relevant testbench or integration context, and the questions or risks you want reviewed.
  49. - **Commenting or repair:** the original RTL, the diagnostic or log, the intended behavior, and whether the change must be comment-only or may change logic.
  50. - **Simulation or external validation:** a usable testbench with expected outcomes, the simulator/tool environment, and any required project or remote access.
  51. If something important is missing, the skill asks for it before making a consequential change.
  52. ## How to call it
  53. Use a normal request. These examples are ready to adapt:
  54. ```text
  55. Use $readable-verilog-generator to create a Verilog-2001 AXI-Stream packet counter.
  56. First ask for any missing interface and timing details, then show me the module spec
  57. and WaveDrom behavior preview before generating RTL.
  58. ```
  59. ```text
  60. Use $readable-verilog-generator to review this RTL for reset behavior, handshake
  61. errors, width issues, naming, comments, and synthesis risks. Do not modify the file.
  62. ```
  63. ```text
  64. Use $readable-verilog-generator to add semantic comments to this Verilog file.
  65. Preserve every RTL token and show the comment-only verification result.
  66. ```
  67. ```text
  68. Use $readable-verilog-generator to diagnose and repair this module from the
  69. attached simulator log. Show the proposed change and validation results first.
  70. ```
  71. ## Preview and confirm before generation
  72. For a new module or a behavior-changing repair, ask for a preview before asking AI to write the final RTL. The preview should make these decisions visible:
  73. ![Preview and confirmation before generation](assets/readme/design-profile.png)
  74. 1. Interface, port directions, widths, clock, and reset behavior.
  75. 2. State transitions, handshake conditions, data-path timing, and corner cases.
  76. 3. At least one WaveDrom scenario that shows the intended cycle behavior.
  77. 4. The checks that will be run and what each result can prove.
  78. Confirm the preview only after the behavior matches your intent. If it does not, revise the requirement and preview again; do not treat an unconfirmed interpretation as the final design.
  79. ## What you receive
  80. Depending on the request, the handoff can include:
  81. ![What you receive after the task](assets/readme/rule-rendering.png)
  82. - readable Verilog-2001 source (`.v`);
  83. - a same-name module specification (`<module>_spec.md`);
  84. - WaveDrom behavior files (`.json5` and rendered `.svg`);
  85. - a testbench scaffold or updated testbench when requested;
  86. - review, repair, static-check, simulation, or tool reports showing only checks that actually ran;
  87. - a concise explanation of remaining assumptions, warnings, and unverified areas.
  88. ## Review and deliver
  89. ![Reviewable delivery](assets/readme/evidence-guard.png)
  90. Review the generated files and the checks that actually ran before accepting the handoff. Keep assumptions and unverified areas visible.
  91. ## Example result
  92. The example below is a 32-bit AXI-Stream meter. It counts bytes only after a `TVALID`/`TREADY` transfer, counts packets on a transferred `TLAST`, and saturates instead of wrapping.
  93. ```verilog
  94. // AXI-Stream transaction detection
  95. assign flag_transfer = i_axis_tvalid & i_axis_tready;
  96. assign flag_packet_end = flag_transfer & i_axis_tlast;
  97. always@(posedge i_axis_aclk or negedge i_axis_arstn)begin
  98. if(i_axis_arstn == 1'b0)begin
  99. cnt_packet_o <= 32'd0;
  100. end else if(i_clear == 1'b1)begin
  101. cnt_packet_o <= 32'd0;
  102. end else if(flag_packet_end == 1'b1)begin
  103. if(data_frame_sum[32] == 1'b0)begin
  104. cnt_packet_o <= data_frame_sum[31:0];
  105. end else begin
  106. cnt_packet_o <= 32'hFFFF_FFFF;
  107. end
  108. end
  109. end
  110. ```
  111. **[Open the complete commented source →](assets/examples/readme/axis_packet_meter.v)**
  112. | Example check | Result |
  113. | --- | ---: |
  114. | Formatter AST | `PASS` |
  115. | Readability, comments, naming, profile | `PASS` |
  116. | Errors | `0` |
  117. | Strict warnings | `0` |
  118. > This is an example static result for the published sample. It does not claim that a simulator, synthesis tool, hardware target, or remote environment ran.
  119. ## Authors and citation
  120. Jiyuan Liu and He Li · Southeast University(东南大学)· HIQC (Heterogeneous Intelligence and Quantum Computing Laboratory)
  121. If this skill supports your research, teaching, or engineering work, cite [CITATION.cff](CITATION.cff).
  122. ```bibtex
  123. @software{liu_2026_verilog_generator,
  124. author = {Jiyuan Liu and He Li},
  125. title = {{Verilog Generator}: An Agent Skill for Verilog-2001 RTL Workflows},
  126. year = {2026},
  127. version = {2.0.0},
  128. date = {2026-08-12},
  129. url = {https://github.com/Eriemon/verilog-generator},
  130. license = {Apache-2.0},
  131. note = {Agent skill for readable Verilog-2001 RTL workflows}
  132. }
  133. ```
  134. ---
  135. <p align="center">
  136. <a href="SKILL.md">Skill details</a>
  137. <span>&nbsp;&bull;&nbsp;</span>
  138. <a href="LICENSE">Apache License 2.0 (Apache-2.0)</a>
  139. <span>&nbsp;&bull;&nbsp;</span>
  140. <a href="CITATION.cff">Citation</a>
  141. <span>&nbsp;&bull;&nbsp;</span>
  142. <a href="mailto:<REDACTED_EMAIL>">Contact</a>
  143. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.