agentleFS
ice-lfernandesice-lfernandes/claude-spring-architect/.claude/skills/nerviz-diagrams/SKILL.md

nerviz-diagrams

Skill11 starsChanged 2 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

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
  1. Very specific:

    Run every command from the repository root.

    line 35
  2. Very specific:

    Compose: Write or adjust docs/diagrams/<view>/view.json per references/view.schema.json and references/visual-identity.md.

    line 42
  3. Distinctive:

    Every fact id and selector must resolve against facts extracted now.

    line 54
  4. Very specific:

    Never hand-edit a rendered file: edit view.json and render again.

    line 65

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

  1. Facts. java .claude/skills/nerviz-diagrams/scripts/Diagrams.java facts writes docs/diagrams/facts.json (gitignored): layer:*, class:*, agentclass:*, skill:*, agent:*, cmd:* (the modes of ArchHook.java), handoff:* and step:<skill>:<id>, each with a stable id. Read it to learn what you may cite.
  2. Compose. Write or adjust docs/diagrams/<view>/view.json per references/view.schema.json and references/visual-identity.md. Every entity node is {"fact":"<id>"} or a selector {"from":"<path into facts>"} (step:*, or class:design.members, step:<skill>:*). Free text lives only in title, caption and a group's caption label. steps gives the animation order of layers, classes and territory views; an orchestrator view takes neither steps nor emphasis — its animation follows the written order of the skill's steps. Kinds: layers, classes, territory, orchestrator; the last carries skill, names only that skill's steps ({"from":"step:<skill>:*"}), picks its layout with derive (sequence: one column with the chips of who runs each step; depends_on: rows with the dependencies) and reads the step contract of references/step-contract.md.
  3. Validate. java .claude/skills/nerviz-diagrams/scripts/Diagrams.java validate. Every fact id and selector must resolve against facts extracted now.
  4. Render. java .claude/skills/nerviz-diagrams/scripts/Diagrams.java render writes <view>.drawio, <view>.excalidraw, <view>.svg and <view>.animated.svg beside the view.
  5. Export (optional). Once per machine, copy the skill's package.json and package-lock.json into "${XDG_CACHE_HOME:-$HOME/.cache}/nerviz-diagrams" and run npm ci --prefix "${XDG_CACHE_HOME:-$HOME/.cache}/nerviz-diagrams" --no-update-notifier --no-audit --no-fund. Then node .claude/skills/nerviz-diagrams/scripts/export.mjs <view> [--video] writes docs/diagrams/<view>/dist/<view>.png (and .webm with --video) and a <file>.source-sha256 holding the SHA-256 of the SVG it came from.
  6. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.