Beauty Diagram

Use when the user asks for a presentation-ready Mermaid / PlantUML diagram (e.g. "beautify this flowchart", "make this look like a deck slide", "produce an S...

Security Scan

The skill is internally consistent: it documents and uses the bd CLI via npx to render Mermaid/PlantUML and requests no unrelated credentials or system access.

Purpose & Capability

Name/description match what the skill does. Requiring node/npx and referencing the @beauty-diagram/cli package is appropriate for a CLI-driven diagram renderer. The included scripts and README align with the stated purpose.

Instruction Scope

SKILL.md instructs only diagram-related actions: generating or reading .mmd/.puml files, running bd beautify/export/share, writing outputs to files, and surfacing API errors. It does not direct the agent to read unrelated system files, gather unrelated environment secrets, or post outputs to unexpected endpoints.

Install Mechanism

There is no explicit install spec; the skill expects use of npx to fetch @beauty-diagram/cli at runtime. Fetching an npm package via npx is expected for a Node CLI, but it does entail executing code downloaded from the npm registry—this is traceable but carries the usual remote-code-fetch risk. No suspicious download URLs or extract-to-disk installers are present.

Credentials

The skill requires no environment variables or credentials for basic (watermarked/limited) use. An optional PAT (bd auth login) is clearly documented and justified for share/unwatermarked/export-heavy workflows. There are no unrelated or excessive credential requests.

Persistence & Privilege

The skill does not request always:true and does not modify other skills or system-wide settings. It allows autonomous invocation (disable-model-invocation: false), which is the platform default and acceptable here. The SKILL.md emphasizes keeping zero state in the agent and preserving source files.

Assessment

This skill appears coherent and does what it says: call the bd CLI (via npx) to produce presentation-ready diagrams. Things to consider before installing/using: (1) npx will download and execute @beauty-diagram/cli from the npm registry—if your organization restricts third-party code, prefer a vetted local install or pinned package version. (2) Authenticated features (unwatermarked output, sharing) require a Beauty Diagram API key; only create/use such keys if you accept that sharing produces public URLs. (3) The SKILL.md claims the API does not persist source unless you call share; if you handle sensitive diagrams, verify the service privacy/policy and avoid using share/export in public mode. (4) The provided scripts use npx --yes (automatic fetch/execute); review them or run commands interactively if you want manual control.

Beauty Diagram skill

Beauty Diagram beautifies Mermaid / PlantUML diagrams into presentation-ready SVG or PNG. It runs as a public API; this skill delegates to the bd CLI (npm package @beauty-diagram/cli) so you keep zero state in the agent. (draw.io / SVG import is editor-only — not exposed through /v1/*.)

When to use

• The user asks for a polished, professional, slide-ready version of a diagram source they already have or you can generate.
• The user wants you to render Mermaid or PlantUML from a model-generated source string.
• The user wants to share a diagram link (e.g. paste into Slack / a doc).
• The user has Mermaid in a repo (README, ADR, RFC) and wants to export SVGs alongside.

When NOT to use

• The user only wants the Mermaid source itself, not an export.
• The user wants pixel-precise control over the SVG markup (Beauty Diagram rewrites layout for presentation; it does not preserve raw Mermaid output).
• The user is in an offline environment with no network and no CLI install.

Required tool

The bd binary from @beauty-diagram/cli:

npx @beauty-diagram/cli help
# or, after install:
bd help

If the user has not installed it, prefer npx over a global install — it respects their package manager and avoids polluting PATH.

Workflow

1. Identify or generate the source diagram.

   • If the user has a .mmd / .puml file, use it.
   • If the user wants you to generate a diagram from scratch, write Mermaid source first (you are good at this), save it to a file, then beautify.
   • draw.io and free-form SVG imports are not accepted by /v1/*. If the user has those, ask them to convert via the web editor first.

2. Decide on output type.

   • Need an SVG file: bd beautify <file> --out <file>.svg
   • Need a download URL or to track quota: bd export <file> --out <file>.svg
   • Need a shareable link: bd share <file> --title "..."

3. Run the command. Always write to a file (--out) rather than letting the SVG flood the terminal / chat.

4. Verify the result exists before reporting success. If the command failed, surface the error code (e.g. quota_exhausted, not_authenticated, parse_failed) — those are actionable for the user.

5. Preserve the source. Never replace the original Mermaid / PlantUML file with the generated SVG — keep them side by side.

Auth

• Demo (anonymous): zero setup. Watermarked SVG/PNG. Limits per IP: 20 /v1/beautify requests / minute, 1 /v1/export per 24h (trial budget — enough for an agent to verify the toolchain end-to-end before registering). /v1/share and /v1/usage always require auth.
• Authenticated: the user runs bd auth login once with a key from /account/api-keys. Required for bd share, unwatermarked output, and repeated exports.

If the user hits a not_authenticated, plan_not_allowed, or quota_exhausted error, point them at /account/api-keys (PAT creation) or pricing — don't silently retry. Anonymous error bodies include a hints block with absolute signUpUrl / signInUrl / apiDocsUrl, which is the canonical place to surface to the user.

Commands cheat sheet

# Render a Mermaid file
bd beautify docs/architecture.mmd --theme modern --out docs/architecture.svg

# Same but treat output as a downloadable export (consumes export quota)
bd export docs/architecture.mmd --out docs/architecture.svg

# PNG export. --scale 1 works for everyone; 2 needs pro, 4 needs premium.
# Higher scales than the plan cap are silently clamped (X-BD-Scale-Clamped).
bd export docs/architecture.mmd --format png --scale 2 --out docs/architecture.png

# PlantUML works the same way; .puml / .plantuml / .pu auto-detected,
# otherwise pass --source-format plantuml.
bd export docs/architecture.puml --out docs/architecture.svg

# Create a public share link (returns absolute https://www.beauty-diagram.com/s/... URL)
bd share docs/architecture.mmd --title "Service architecture"
# → prints the URL on stdout

Privacy

The API does NOT persist source unless the user calls bd share. Do not warn about server-side storage when running beautify, export, validate, refine, or import — that is misleading.

Anti-patterns

• ❌ Do NOT output a hand-crafted <svg>...</svg> as a Markdown code block when a Mermaid source exists. Always run Beauty Diagram and reference the file.
• ❌ Do NOT dump the raw SVG into the chat. Use --out <file> and reference the file path.
• ❌ Do NOT install Beauty Diagram engine code locally — the CLI is a thin client; the engine lives behind the public API.
• ❌ Do NOT assume the user wants AI refinement just because their diagram looks rough — ask first; refine consumes paid quota.

Troubleshooting

Symptom	Likely cause	Resolution
not_authenticated	No key, no session	bd auth login
scope_missing	Key lacks scope	Recreate key with required scope
plan_not_allowed	Plan does not include this capability	Upgrade or skip the call
parse_failed	Source not valid Mermaid / PlantUML	Check the source — bd beautify will surface a parse error too
quota_exhausted	Plan limit hit (anon: 1 export/IP/24h; free: 3/mo; pro: 100/mo)	Sign in, wait for reset, or upgrade — hints in the response body has the URLs
rate_limited	Anonymous IP bucket full (20 /v1/beautify requests / minute)	Sign in or wait
source_too_large	Source > 100 KB	Split the diagram
output_too_large	PNG raster exceeds 8192 px	Lower --scale or simplify

Examples

See examples/ for runnable sources you can adapt:

• examples/flowchart.mmd
• examples/sequence.mmd

And scripts/ for shell wrappers you can copy into the user's repo:

• scripts/beautify.sh
• scripts/export.sh