nerviz-diagrams
Skill11 starsChanged 3 days agoApache-2.0View on GitHub
Renders diagrams of this repository's own .claude/ harness — the layers, the skill and agent classes with their write territories, the /new-feature pipeline, the three orchestrators (/init-project, /new-feature-implement, /platform-upgrade) — from .claude/schemas/extensions.json and the files on disk, as .drawio, .excalidraw, static and animated SVG under docs/diagrams/, plus PNG and video for the site. Meta-repository only; never a use case or domain diagram, which are Mermaid inside the spec.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- ice-lfernandes/claude-spring-architectword for word, first seen Nov 1, 2026
Other versions1 project uses a version of this.
Word for word · 1
- ice-lfernandes/claude-spring-architect★ 11100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository35 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ai-architectSkill
- arch-adoptSkill
- arch-doctorSkill
- audit-usageSkill
- cache-architectSkill
- claude-code-architect-designerSkill
- docker-architectSkill
- domain-modelingSkill
- git-publishSkill
- gof-design-patternsSkill
- graphql-api-architectSkill
- harness-lessonsSkill
- http-client-architectSkill
- init-projectSkill
- jobs-architectSkill
- messaging-architectSkill
- new-feature-implementSkill
- new-featureSkill
- new-projectSkill
- persistence-architectSkill
- platform-upgradeSkill
- project-bootstrapSkill
- project-configSkill
- report-issueSkill
- rest-api-architectSkill
- search-architectSkill
- security-architectSkill
- sonar-lessonsSkill
- sonarqube-setupSkill
- spikeSkill
- test-architectSkill
- transport-security-setupSkill
- triage-issueSkill
- use-case-designSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 35
Run every command from the repository root.
- Very specific: line 42
Compose: Write or adjust docs/diagrams/<view>/view.json per references/view.schema.json and references/visual-identity.md.
- Distinctive: line 54
Every fact id and selector must resolve against facts extracted now.
- Very specific: line 65
Never hand-edit a rendered file: edit view.json and render again.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Nerviz Diagrams
Draws the harness from its own data, so a diagram cannot say what the pipeline stopped saying. Code extracts the facts, you compose a view that cites them, code validates and renders. A diagram a model drew from memory is wrong the first commit the pipeline changes.
Target
$ARGUMENTS
Empty: every view under docs/diagrams/. A name: only that view, created when absent.
Class: media
Why this is a manual skill
Form 2: rendering writes files the person decides to commit and runs per release or when a
piece is added, never every session. Axis 2 is the manual trigger (disable-model-invocation,
so it never competes with the Mermaid of use-case-design), and axis 9 a write territory no
class has: docs/diagrams/**. The closest rejected form was an ArchHook.java mode, which
export would ship as dead code into every generated project. Record:
@.claude/decisions/0190-nerviz-diagrams-skill-derived-from-data.md.
Procedure
Run every command from the repository root. No network at run time; npm ci in step 5 is the
only download, and nothing is ever npx-ed from an unpinned package.
- Facts.
java .claude/skills/nerviz-diagrams/scripts/Diagrams.java factswritesdocs/diagrams/facts.json(gitignored):layer:*,class:*,agentclass:*,skill:*,agent:*,cmd:*(the modes ofArchHook.java),handoff:*andstep:<skill>:<id>, each with a stable id. Read it to learn what you may cite. - Compose. Write or adjust
docs/diagrams/<view>/view.jsonperreferences/view.schema.jsonandreferences/visual-identity.md. Every entity node is{"fact":"<id>"}or a selector{"from":"<path into facts>"}(step:*, orclass:design.members,step:<skill>:*). Free text lives only intitle,captionand a group's caption label.stepsgives the animation order oflayers,classesandterritoryviews; anorchestratorview takes neitherstepsnoremphasis— its animation follows the written order of the skill's steps. Kinds:layers,classes,territory,orchestrator; the last carriesskill, names only that skill's steps ({"from":"step:<skill>:*"}), picks its layout withderive(sequence: one column with the chips of who runs each step;depends_on: rows with the dependencies) and reads the step contract ofreferences/step-contract.md. - Validate.
java .claude/skills/nerviz-diagrams/scripts/Diagrams.java validate. Every fact id and selector must resolve against facts extracted now. - Render.
java .claude/skills/nerviz-diagrams/scripts/Diagrams.java renderwrites<view>.drawio,<view>.excalidraw,<view>.svgand<view>.animated.svgbeside the view. - Export (optional). Once per machine, copy the skill's
package.jsonandpackage-lock.jsoninto"${XDG_CACHE_HOME:-$HOME/.cache}/nerviz-diagrams"and runnpm ci --prefix "${XDG_CACHE_HOME:-$HOME/.cache}/nerviz-diagrams" --no-update-notifier --no-audit --no-fund. Thennode .claude/skills/nerviz-diagrams/scripts/export.mjs <view> [--video]writesdocs/diagrams/<view>/dist/<view>.png(and.webmwith--video) and a<file>.source-sha256holding the SHA-256 of the SVG it came from. - Check.
java .claude/skills/nerviz-diagrams/scripts/Diagrams.java check— what CI runs.
Never hand-edit a rendered file: edit view.json and render again. Never write under
docs/use-cases/.
Failure modes
Node absent. Steps 1-4 and 6 are Java and still work; only step 5 needs Node.
Playwright browser missing. Video is opt-in. export.mjs stops and names the download
command (playwright install chromium); tell the person, never run it unasked.
A step of a skill a view names breaks the step contract. A ### <id> · <Name> heading with
no **Runs:** line, a **Runs:** ref that is no fact, a gate word outside the vocabulary, a
**Hands over:** command that is no skill or native command, the retired ### Step grammar, a
branch gate word with no **Stops when:** line, a condition or line past its limit, **Reads:**,
**Depends on:** or **To:** naming a step written after the reader, a field line outside the block
under its heading, a **Note:** on a one-phase step:
facts, validate and check exit 2 naming file and line, so CI goes red by name. Fix the
skill's step, or references/step-contract.md and the extractor in the same change.
Unresolved fact id. A piece was renamed or removed: validate names the view, the JSON
path and nearby ids. Update the view.
Stale render. check lists each file that differs from a fresh render, or a dist/ file
whose .source-sha256 is not its SVG's hash. Run render (and export.mjs for dist/).
Contract
Class: media — the territory is skill_classes.media in @.claude/schemas/extensions.json:
docs/diagrams/**, nothing else. ArchHook.java guard enforces it.
Reads .claude/schemas/extensions.json, the SKILL.md of every skill a view names (its
steps, per references/step-contract.md), the switch (mode) dispatch of
.claude/hooks/ArchHook.java, the frontmatter of the skills and agents those steps cite, the
.claude/ tree on disk, .claude/settings.json,
.mcp.json when present, and this skill's references/.
Writes docs/diagrams/** only.
Never writes any other path, and declares no .mcp.json server. The person's own
Excalidraw connector may refine a copy ad hoc, never a rendered file.
Stays out of the generated project — listed in export.skills.exclude.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

