agent-skills-systemrdl

A hierarchical SystemRDL 2.0 authoring reference for coding agents, packaged as an Agent Plugin.

The plugin contains one Agent Skill, systemrdl-ref, that lets an agent write legal Accellera SystemRDL 2.0 — syntactically valid, semantically consistent, and free of the property combinations the standard forbids.

Why

The SystemRDL 2.0 standard is ~130 pages. An agent asked to write a register map otherwise has to guess, or read the whole thing. Both produce descriptions that look right and are subtly illegal: mutually exclusive properties set together, woclr on a read-only field, a writable field straddling an access-width boundary.

How it is organized

Content is a disclosure ladder — a loading order, not a filing scheme:

A trivial task stops at a hub for ~2.2k tokens; a typical one reaches two leaves for ~5.7k; only exhaustive lookups (full BNF, full UVM/IP-XACT access-mode mapping) go further.

src/agent_skills_systemrdl/share/skills/systemrdl-ref/   (== skills/systemrdl-ref)
├── SKILL.md                 # entry point: authoring loop, 5 rules, hub map, express lane
├── references/
│   ├── components/          # field, reg, regfile, mem, addrmap, signal, enum, struct, constraint
│   ├── properties/          # sw/hw access, counters, interrupts, reset, addressing, HDL path, UDPs
│   ├── language/            # lexical, types, expressions, scoping, parameters, preprocessor, BNF
│   ├── patterns/            # recipes, arrays, reuse, antipatterns
│   ├── validation/          # checklist, compiler errors, tooling
│   └── _deep/               # full BNF, full access modes, full property table
├── data/properties.yaml     # all 90 properties, schema-validated
├── scripts/                 # validate_rdl.py, query_property.py, explain_error.py
└── assets/templates/        # 8 compilable starting points

Every normative claim cites its clause or table — [§9.6.1 k], [Table 19] — so any sentence can be audited against the standard. Uncited statements are marked as advice.

Install

pip install agent-skills-systemrdl

That registers an agent.skills entry point, so tools that walk that group — including IVPM's agents handler — find the skill without being told where it is. In an IVPM project, one line is enough:

# ivpm.yaml
    - name: agent-skills-systemrdl
      src: pypi

ivpm update then assembles .agents/skills/, .claude/skills/, and .cursor/skills/.

Without IVPM, symlink the installed skill into your client's skills directory:

python -c "from agent_skills_systemrdl.skills import get_skill_dirs; print(get_skill_dirs()[0])"

The package has no runtime dependencies. To let the bundled scripts do real work rather than report that they cannot, install agent-skills-systemrdl[validate]; otherwise validate_rdl.py exits 2 with a "NOT VALIDATED" banner and the skill reports its output as unchecked rather than implying otherwise.

The repository is also a portable Agent Plugin — plugin.json at the root and skills/systemrdl-ref — so a client can be pointed at a checkout directly. See docs/ for other clients and the IVPM-based development setup.

Develop

./bootstrap.sh                                    # venv under packages/python, then `ivpm update`
                                                  # (deps come from pyproject.toml via ivpm.yaml)
packages/python/bin/python -m pytest tests/       # full test suite
packages/python/bin/python tools/lint_skill.py    # ladder invariants, budgets, frontmatter
packages/python/bin/python -m build .             # sdist + wheel
make -C docs html                                 # documentation (built with -W)

The skill's canonical location is src/agent_skills_systemrdl/share/skills/systemrdl-ref/, because setuptools only packages data found under the package directory. skills/systemrdl-ref is a relative symlink to it, which is what gives the repository its Agent Plugins layout — one copy of the content, two shapes. CI checks the symlink survives checkout and that every file under the skill reaches the wheel.

CI enforces the claim that the shipped examples are legal:

• every .rdl in assets/templates/ and tests/golden/ compiles and elaborates;
• every ```systemrdl block in the prose compiles, or declares an inline reason why not (currently 77 compile, 26 skipped with stated reasons);
• 20 negative cases must fail with their recorded diagnostics, so the error catalogue cannot drift from what the compiler actually says;
• ladder invariants, token budgets, generated-file freshness, and property coverage;
• the wheel carries all 58 skill files, and the version agrees across __version__.py, plugin.json, and SKILL.md.

Releases are tag-driven: pushes to master build a .<run-id> dev-suffixed wheel that is never published; a v<version> tag publishes to PyPI and the docs. See .forgejo/workflows/ci.yml (primary) and .github/workflows/ci.yml (mirror).

Documentation

docs/ builds a Sphinx site whose reference pages {include} the skill's Markdown rather than copying it, plus four generated analysis pages: the disclosure ladder with measured token costs, the property index, a spec-clause map, and a coverage report.

Project

git.dvkit.org is authoritative. CI, releases, and documentation all publish from there (.forgejo/workflows/ci.yml); any GitHub mirror runs build-and-test only.

License

Apache-2.0. The Accellera SystemRDL 2.0 specification is copyright © 2015–2018 Accellera; this repository restates its rules with citation and is not an official Accellera publication. Where this reference and the standard disagree, the standard governs.