ESDM Skills

A portable, self-contained bundle of ESDM (Event-Sourced Domain Modeling) skills for AI coding agents (Claude Code, Cursor, Cline, OpenCode, and 70+ others). Install them into any project with one command; the first time you use them, the correct esdm binary for your machine is downloaded automatically into your project.

ESDM is a YAML modeling language + linter by the native web for describing event-sourced, DDD domains. See https://www.esdm.io/.

What's in here

Four cooperating skills (install them together — they reference one another):

Skill	What it does
esdm-model	Write/edit .esdm.yaml models and get them to lint clean. The core skill — it also owns the esdm binary bootstrap and the reference docs.
esdm-diagrams	Generate Mermaid diagrams (technical flow, business storyline, context map, data-model/ER) from a model. Ships a vendored Node generator — no npm install needed.
esdm-business-interview	Build a model by interviewing a business stakeholder in plain language, silently mapping answers onto ESDM constructs. The default modeling entry point.
esdm-event-storming	Explore a process-heavy domain on a visible Event Storming wall, then harvest it into the shared model.

Prerequisites

• Node.js (v18+) — runs the diagram generator and the npx skills installer.
• A shell (bash/sh on Linux/macOS/Git-Bash) or PowerShell (Windows) — runs the one-time binary bootstrap.
• curl or wget (Linux/macOS) — download the esdm binary. PowerShell uses its built-in Invoke-WebRequest.
• Network access to esdm.s3.fr-par.scw.cloud (the official ESDM download host) on first use.

Install

Uses the skills CLI. From the root of the project you want to model in:

# Install all four ESDM skills from this repo
npx skills add esveo/esdm-tools --skill '*'

The skills/ directory sits at the repo root, so the CLI auto-discovers every skill. Any git URL works too, e.g. npx skills add https://github.com/esveo/esdm-tools.

The installer detects your agent(s) and copies (or symlinks) the skills into the right place — e.g. .claude/skills/ for Claude Code, ~/.claude/skills/ for a global install. Install all four so their cross-references resolve.

First use — the esdm binary is set up for you

The skills CLI installs declarative Markdown only; it runs no scripts. So the esdm binary is fetched the first time an ESDM skill actually runs — the esdm-model skill is instructed to run its bundled bootstrap before any esdm command:

• skills/esdm-model/scripts/bootstrap-esdm.sh (Linux/macOS/Git-Bash)
• skills/esdm-model/scripts/bootstrap-esdm.ps1 (Windows PowerShell)

The bootstrap:

1. Detects your OS and CPU architecture.
2. Downloads the matching binary from https://esdm.s3.fr-par.scw.cloud/<version>/esdm-<os>-<arch> — the official download.
3. Places it at .esdm/bin/esdm inside your project — local, not on your PATH — and makes it executable, applying the platform post-download steps (executable bit; clearing the macOS quarantine attribute / Windows mark-of-the-web) so it runs without a warning.
4. Is idempotent: if a working binary is already there, it does nothing.

Nothing is installed system-wide; delete .esdm/ to remove the binary. You'll likely want to add .esdm/ to your project's .gitignore.

The esdm-diagrams skill also does a one-time setup on first use: its generator has a single npm dependency (js-yaml), so the skill runs npm install inside its own generator/ folder once (node_modules/ is not shipped). Both setup steps are handled by the agent when you first use a skill — no manual action needed.

You can run the bootstrap yourself at any time:

sh skills/esdm-model/scripts/bootstrap-esdm.sh   # prints the binary path
.esdm/bin/esdm version

Override the version or location with env vars: ESDM_VERSION, ESDM_INSTALL_DIR, ESDM_BASE_URL.

Using the skills

Once installed, just ask your agent in natural language — the skill descriptions route the request:

• "Model my business — I don't care about the technical terms" → esdm-business-interview
• "Let's storm out this process" → esdm-event-storming
• "Add a returned event to the loan aggregate" → esdm-model
• "Regenerate the diagrams" → esdm-diagrams

Models live in models/<name>/ in your project; each carries its own .esdm.yaml files, generated schemas/, DIAGRAMS.md, and progress files.

Contributing

The repo is the root of the skills bundle — this README.md plus the skills/ directory. No registry or manifest is required: the skills CLI discovers every skills/<name>/SKILL.md automatically, so adding a skill is just adding a skills/<name>/SKILL.md. Issues and PRs welcome at https://github.com/esveo/esdm-tools.

Layout

.
├── README.md
└── skills/
    ├── esdm-model/
    │   ├── SKILL.md
    │   ├── reference/            # bundled background docs (what-is-esdm, message-flow, …)
    │   └── scripts/              # bootstrap-esdm.sh / .ps1 (binary download)
    ├── esdm-diagrams/
    │   ├── SKILL.md
    │   └── generator/            # Node Mermaid generator, deps vendored
    ├── esdm-business-interview/
    │   └── SKILL.md
    └── esdm-event-storming/
        ├── SKILL.md
        └── examples/            # a filled-in session wall