agentleFS
AhmedNazihXAhmedNazihX/Strata/SKILL.md

strata

Skill4 starsChanged 45 days agoMITView on GitHub

Create narrated architecture, workflow, sequence, data-flow and lifecycle diagrams as one self-contained interactive HTML file — layered, animated, theme-switchable, exportable to PNG and SVG. The author writes typed JSON and a CLI computes the layout, so coordinates are never guessed. Use when asked to diagram or visualise a system, a service architecture, a request path, a process or runbook, an API call sequence, a data pipeline or lineage, a state machine, or to turn a repository into an explorable map; also for converting Mermaid flowchart, sequenceDiagram or stateDiagram input into something presentable.

  • Installs packages

4 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions4 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 4

    1. momori777/Artemis★ 445same name
    2. SanStone3/agent-strata★ 2same name
    3. alsk1992/strata-agent-skills★ 0same name
    4. rx6ru/strata★ 0same name

    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.

The file

We split this skill into the rules it gives an agent

2 rules. 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If strata is on the PATH, use that instead.

    line 25
  2. Very specific:

    Mermaid input: read it for topology and meaning, then author fresh Strata JSON without its styling.

    line 85

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “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

Strata

A diagram is a claim about how something works. This skill makes that claim checkable: you write typed JSON, a CLI computes the layout, and four gates run before anything is called finished. You never write HTML and you never place coordinates.

Running it

The CLI lives beside this file, at bin/strata.mjs. Resolve it relative to this skill's own directory, which works whether the skill is installed for the user (~/.claude/skills/strata/) or inside a project (<repo>/.claude/skills/strata/):

node <this-skill-dir>/bin/strata.mjs <command> ...

If strata is on the PATH, use that instead; strata doctor says which install answers. Examples below write strata.

The fast path

  1. For a diagram of real code, ask first whether the user wants code mapping — each node and link citing the lines it rests on, embedded so a click opens the code. Ask once, before reading the repository, with a single question (AskUserQuestion where available): with code mapping (slower: exact line citations, --repo-root checks, a reviewer agent) or without (faster: the same tracing, no citations). Skip the question when the user already said, or when the diagram is not of a repository. The choice sets the mode used in steps 2, 4 and 6 and in references/repository-evidence.md.
  2. Pick a type from the router below. One question decides it: what is the reader meant to learn?
  3. Read one example and the authoring reference — examples/<type>.mjs and references/authoring.md — in a single batch. For a diagram of real code, also references/repository-evidence.md. Examples teach shape, never facts: use fresh ids, your own wording, your own structure. Without code mapping, skip the Citations section of that reference; the tracing rules still apply.
  4. Write the candidate JSON straight through. Do not plan coordinates in prose or validate a stub. Give it layers, nodes (with layer, and col except in a workflow), links that all have an id, and — unless the user asked for a still diagram — a steps walkthrough whose ledes explain why, not only what.
  5. Iterate with validate. It runs the schema and geometry gates in about a tenth of a second and writes nothing. Fix what it names and rerun until it exits 0. For a diagram of real code with code mapping, pass --repo-root <path> from the first run so every citation is checked. Without it, write no sources, omit --repo-root, and ignore the "links cite no code" warning.

    strata validate candidate.json --repo-root <path>
  6. Then run finalize once. It repeats those gates, renders the HTML and runs the browser gate, which takes several seconds. A non-zero exit is never success: fix the cause and rerun. Every failure message says what to do; references/troubleshooting.md covers the rare cases it does not.
  7. For a diagram of real code with code mapping, have it reviewed before handing it over. A reviewer agent in a fresh context checks every node, link and label against the code and looks for connections the diagram leaves out (references/repository-evidence.md, step 6). Without code mapping, skip the review and offer it when you hand the diagram over.

Unless the user names a location, put each request in its own folder .strata/<type>-<slug>/ with candidate.json and the HTML beside it, and set meta.output to that HTML's name, so earlier versions survive.

Type router

TypeThe reader learnsLayers are
architecturewhich tier a component lives in and what talks to whattiers, as horizontal rails
workflowwhat happens in what order and where it branchesoptional swimlanes
sequencewho calls whom, in what order, down a time axisparticipants, as columns
dataflowwhere data comes from, what changes it, who consumes itpipeline stages, as columns
lifecyclewhat states a thing can be in and what moves itoptional groups

Boxes that are things make an architecture; boxes that are steps make a workflow. A workflow is done once; a lifecycle is where something sits.

Mermaid input: read it for topology and meaning, then author fresh Strata JSON without its styling. flowchart/graph → workflow (or architecture when the boxes are components), sequenceDiagram → sequence, stateDiagram → lifecycle.

The gates

GateWhat it proves
schemashape, limits and references; with --repo-root, every citation resolves inside the checkout and lands on code, not prose
geometryon the computed layout: nothing overlaps, clips or leaves the canvas; lines keep clear of boxes and of each other; every drawn label reads as naming its own line (the numbers are in authoring.md, under Limits)
renderone self-contained HTML written
browserthe page in real Chromium and WebKit: no script error, text inside its boxes, every step lights something, citations open their code, pulses move, the theme toggles, nothing WebKit will not paint

The browser gate needs Playwright, from the working directory or beside the skill; doctor says what is available, and the receipt names the engines that ran. If it is missing, install it (npm i -D playwright && npx playwright install chromium webkit) or pass --no-browser, which reports the gate as skipped, not passed — say so.

Warnings (~) never fail a run, but read them: a label left off, a label resting on a box, crossings, a node connected to nothing, a link that cites no code.

Other commands

render   candidate.json        write the HTML, skip the browser gate
check    diagram.html          run the browser gate against a file that exists
demo     <dir>                 write and render one example of each type
schema   <dir>                 emit the five JSON Schemas for editor autocomplete
doctor                         what this install can do

What the reader gets

One HTML file with no build step or server. Themes on T, animation on M (it follows the system's reduced-motion setting until overridden); arrow keys, space, 1–9 and the step bars drive the walkthrough, which also autoplays. Clicking a node with a detail or sources opens its panel, which also lists the links leaving it; with --repo-root each citation opens the embedded code with the cited lines marked. Copy, PNG at 2× and SVG are on the toolbar. Deep links: #step=4, #theme=light, #motion=on, #node=<id>. The only network reference is the web-font stylesheet. references/style.md covers the style levers.

Honesty

  • Report the gates as they came back. A skipped gate is not a passed one, and do not claim you looked at the rendered page unless you opened it.
  • Citations are checked and embedded only with --repo-root; without it, say they are unverified. A diagram built without code mapping has none: say so, and that nodes open no code.
  • Passing every gate means the diagram is legible and its citations resolve, not that it is complete or correct. Say whether a reviewer looked for missing connections.
  • A diagram of real code is traced from the code: every claim is something you read, not something the stack implies (references/repository-evidence.md).

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.