Writing with AI
The Siren repository ships an agent skill: skills/siren. Once it is installed, an AI coding agent such as Claude Code knows which syntax Siren supports, the timeline’s rules and how target ids are formed. After writing a document it runs the validator, fixes what it reports, and hands you a .srn that renders as it is.
The skill follows the open Agent Skills format, so it does not depend on any particular agent or model.
What it does
The agent picks up the skill when you ask for things like “draw an animated architecture diagram”, “add a step-by-step reveal to this Mermaid diagram” or “this .srn won’t render, fix it”. It then works through these steps:
- Find the story: what the diagram explains, and in what order the reader should meet each part. A timeline is a narrative, not a list of elements.
- Choose the diagram type: a flowchart for processes and architecture, a sequence diagram for interactions over time, a class diagram for types, a state diagram for lifecycles, an ER diagram for data models.
- Write the diagram body, using only the Mermaid syntax Siren supports, and leave colors to the theme unless they carry meaning (see below).
- Write the timeline, following Siren’s rules: nothing is highlighted before it is visible, edges exit with their nodes, each target enters only once, and so on.
- Validate: render the document with the bundled script and fix every error and warning.
- Deliver the
.srn, with a short summary of what each step shows.
Given an existing Mermaid diagram, the agent keeps its content and only adds the timeline. A Mermaid frontmatter at the top is kept as well: Siren reads it but applies none of its settings yet, so the skill tells the agent to expect a warning per setting rather than an error (see Getting started).
The skill also carries the rules that trip an agent up most often: only a whole line is a comment, so each %% comment goes on a line of its own (inside a timeline block it may go anywhere); and in a sequence diagram the message right after create participant X must be sent to X, and the one right after destroy X sent by or to X, with nothing in between, or the document is refused. Its table of common errors lists those messages with their fixes.
Because a Siren document with its timeline blocks removed must be a Mermaid document, the skill asks the agent to check every document it produces against real Mermaid as well, with the script the Siren repository runs on its own examples (pnpm --filter siren-core check-examples -- diagram.srn from a Siren checkout). The validator’s OK alone does not prove that.
Color and styling
A diagram is usually viewed under a theme the agent cannot see, such as this site’s dark mode, and a color written into the document overrides it when siren-core draws the diagram on your own page; on this site the chosen Style or Custom theme takes it over instead (see Themes). So the skill tells the agent to write no styling by default, to add color only when it carries meaning the structure cannot, and then to choose colors that work on a light and a dark background: translucent fills (fill:#3b82f633) with opaque mid-tone strokes, never near-black or near-white. It also tells the agent not to style a subgraph, and to give elements the timeline highlights a fill at most, so that the highlight is what the reader sees.
Installing
Copy the skill folder into the directory your agent loads skills from. For Claude Code:
git clone --depth 1 https://github.com/Ginz9013/siren.git
# For every project
cp -r siren/skills/siren ~/.claude/skills/
# For the current project only
cp -r siren/skills/siren .claude/skills/
Other agents that support Agent Skills load them from their own skills directory; see your agent’s documentation for the location.
If your agent doesn’t support skills, give it siren/SKILL.md and siren/references/syntax.md as project instructions or as context in the conversation. It still works, but the agent won’t run the validator on its own.
The skill folder holds three files:
| File | Contents |
|---|---|
SKILL.md |
The workflow, document shape (frontmatter and comment rules included), timeline rules, named timelines, target ids for each diagram type, color and styling guidance, the check against real Mermaid, and common errors with their fixes |
references/syntax.md |
The syntax each of the six diagram types supports, with one complete example each, and what is not supported |
scripts/validate.mjs |
The validator |
What it looks like
Draw a Siren flowchart of how a browser request goes through the API to the cache and the database.
Show only the browser at first, then bring in the API, the cache and the database in turn,
and finish by highlighting the path to the database.
The agent hands back a document like this:
flowchart LR
Client[Browser] --> API[API server]
API --> DB[(Database)]
API --> Cache[(Cache)]
timeline:
enter API fade, enter Client-API fade
enter Cache slide-right, enter API-Cache fade
highlight Cache glow
unhighlight Cache, enter DB slide-right, enter API-DB fade
highlight API-DB outline
Step 0 shows only Client, because every other element has an enter. Then the API and its edge appear, the cache appears, the cache is highlighted, the database appears, and the query path is highlighted.
Paste it into the Playground to play it, or to export it as a PPT from the Export panel.
Validating
The skill’s scripts/validate.mjs renders a document with siren-core and lists every error and warning with its line and column. The agent runs it after writing a document, and you can run it yourself. It needs Node.js 18 or later, and two packages installed in the directory you run it from:
npm install --no-save siren-core jsdom
node ~/.claude/skills/siren/scripts/validate.mjs diagram.srn --ids
diagram.srn: ERRORS (1 error(s), 0 warning(s), 5 step(s))
diagram.srn:12:3 error: timeline: references unknown id "API-Db"
ids: Client, API, DB, Cache, Client-API, API-DB, API-Cache
- Status
OKmeans the document is valid. --idslists every id the timeline can name, including the ones Siren generates, such assubgraph:1andnote:1. In a large diagram these are easy to miscount, so check against this list.- Pass
-to read from stdin. The exit code is 1 when any document has an error.
Passing validation means the document is well-formed, not that it is well-staged: look over step 0 and the order of the steps yourself.