agentsclimarketplace

Mermaid sequence diagrams

Skill msewell/agent-stuff/skills/mermaid-sequence-diagrams

Like everyone else, I'm sharing my agent stuff.

Install
npx -y skills add msewell/agent-stuff --skill mermaid-sequence-diagrams

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Generates, reviews, and fixes Mermaid-only sequence diagrams following syntax rules and best practices. Use when creating Mermaid sequence diagrams from system descriptions, reviewing existing Mermaid sequence diagrams for correctness, fixing parse errors, or refactoring large Mermaid sequence diagrams into focused sub-diagrams. Covers participants, arrows, activations, control flow, notes, styling, and common anti-patterns.

SKILL.md

5.3 KB, as published. Nobody here has run it

Mermaid Sequence Diagrams

Generate, review, and fix Mermaid sequence diagrams that are syntactically correct, visually clear, and follow established best practices.

This skill is intentionally Mermaid-specific: keep the output in Mermaid sequenceDiagram syntax.

Generating a New Diagram

  1. Identify participants. List every system, service, or actor involved. Assign short IDs with descriptive aliases: participant OMS as Order Management Service.
  2. Use actor for human users (renders stick figure), participant for services, database for data stores, queue for message brokers.
  3. Determine the flow type:
    • Synchronous request/response → ->> / -->> arrows.
    • Async fire-and-forget → -) / --) arrows.
    • Failed/rejected → -x / --x arrows.
    • Bidirectional (v11+) → <<->> / <<-->> arrows.
  4. Declare all participants explicitly at the top to control left-to-right ordering. Place the initiator on the far left.
  5. Write messages one per line. Keep message labels concise (e.g., POST /orders, 201 Created). Move payload details to Note blocks.
  6. Add autonumber when the diagram has 5+ messages.
  7. Use +/- shorthand for activations on arrows (e.g., ->>+Server to activate, -->>-Client to deactivate).
  8. Model error paths with alt/else. Never produce a happy-path-only diagram — always include at least one failure branch.
  9. Use control flow blocks as needed — read references/02-control-flow-and-notes.md for alt, opt, loop, par, critical, break, and rect.
  10. Group related participants with box when there are 4+ participants across distinct layers.
  11. Add Note over blocks sparingly for protocol details, SLA info, or phase labels.
  12. Verify the output against the syntax rules below before presenting.
  13. For styling, themes, or configuration directives, read references/03-styling-and-best-practices.md.
  14. For real-world pattern inspiration (OAuth, webhooks, sagas, circuit breakers, retries), read references/04-real-world-examples.md.

Reviewing / Fixing an Existing Diagram

  1. Check for syntax errors using the table below. Fix any found.
  2. Verify every activate has a matching deactivate (or use +/- shorthand consistently).
  3. Verify every alt, opt, loop, par, critical, break, and rect block has a matching end.
  4. Check for design anti-patterns — read references/03-styling-and-best-practices.md for the full list.
  5. If the diagram exceeds 20 messages or 7 participants, recommend splitting into focused sub-diagrams.
  6. Ensure arrow style usage is consistent (don't mix sync and async arrows without clear intent).
  7. Confirm participants are declared explicitly with aliases if any name exceeds ~15 characters.

Refactoring Large Diagrams

  1. Identify logical phases (e.g., authentication, data processing, notification).
  2. Split into one diagram per phase, with a brief prose description connecting them.
  3. Keep shared participant declarations consistent across sub-diagrams.
  4. Each sub-diagram should have ≤ 15-20 messages and ≤ 6-7 participants.

Syntax Rules — Common Errors

MistakeFix
Smart quotes " "Use straight quotes "
Unicode arrows → ⇒Use ASCII arrows ->> -->
Em/en dashes — –Use plain hyphens -
The word end in labelsWrap in quotes: "end", brackets: [end], or parens: (end)
Multiple statements on one lineOne statement per line
Spaces in participant IDsUse CamelCase or snake_case IDs with alias for display name
Semicolons in textEscape as #59;
Unbalanced bracketsEnsure every [ has ], every ( has )

Output Template

Use this skeleton as the starting point for every diagram:

sequenceDiagram
    autonumber
    participant A as Service A
    participant B as Service B

    A->>+B: Request
    B-->>-A: Response

References

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.