{"id":"4a691fe9-4561-48e6-84ad-81715c84fb71","entityType":"agent","slug":"clawhub-levi840714-beauty-diagram","name":"beauty-diagram","canonicalUrl":"https://www.xpersona.co/agent/clawhub-levi840714-beauty-diagram","canonicalPath":"/agent/clawhub-levi840714-beauty-diagram","generatedAt":"2026-10-10T10:48:41.106Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:09:11.055Z","emptyReason":null},"description":"Use when the user asks for a sleek, modern Mermaid / PlantUML diagram (e.g. \"beautify this flowchart\", \"make this look like a deck slide\", \"produce an SVG of this architecture\"), wants AI to generate a diagram from a text description, wants a public share link for a diagram, wants to render every diagram file in a folder, or wants to render Mermaid / PlantUML fenced code blocks inside a Markdown file (README, docs) into images. This skill teaches you to call the Beauty Diagram CLI (`bd`) — never to hand-author SVG when a source diagram exists.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.6K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s174zrsbbkkxp2t8xyf8sbpca185mwa6:beauty-diagram","sourceUrl":"https://clawhub.ai/levi840714/beauty-diagram","homepage":"https://clawhub.ai/levi840714/skills/beauty-diagram","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/levi840714/beauty-diagram","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/levi840714/skills/beauty-diagram","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":64,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"beauty-diagram technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:09:11.055Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:09:11.055Z","emptyReason":null},"stars":null,"forks":null,"downloads":1600,"packageName":null,"latestVersion":"1.7.0","tractionLabel":"1.6K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:09:11.055Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T07:09:11.055Z","lastCrawledAt":"2026-10-10T07:09:11.055Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T07:09:11.055Z","lastVerifiedAt":null,"highlights":[{"version":"1.7.0","createdAt":"2026-08-04T09:09:19.687Z","changelog":"inline","fileCount":9,"zipByteSize":14811},{"version":"1.6.1","createdAt":"2026-06-15T19:10:44.183Z","changelog":"add bd:bg comment","fileCount":9,"zipByteSize":14794},{"version":"1.6.0","createdAt":"2026-05-22T17:01:35.412Z","changelog":"document bd extract --share watermark-free mode","fileCount":8,"zipByteSize":14210},{"version":"1.5.0","createdAt":"2026-05-19T05:56:45.965Z","changelog":"enhance theme tier","fileCount":7,"zipByteSize":10946},{"version":"1.4.0","createdAt":"2026-05-05T06:38:13.025Z","changelog":"add embed feature","fileCount":7,"zipByteSize":10018},{"version":"1.3.0","createdAt":"2026-05-04T15:51:26.222Z","changelog":"modify /export qualify params","fileCount":7,"zipByteSize":8593},{"version":"1.2.0","createdAt":"2026-05-04T09:27:42.384Z","changelog":"new batch, extract feature","fileCount":7,"zipByteSize":8577},{"version":"1.1.0","createdAt":"2026-04-30T06:37:42.511Z","changelog":"new ai generate feature","fileCount":7,"zipByteSize":7664}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s174zrsbbkkxp2t8xyf8sbpca185mwa6:beauty-diagram","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s174zrsbbkkxp2t8xyf8sbpca185mwa6:beauty-diagram` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/levi840714/beauty-diagram before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-levi840714-beauty-diagram/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-levi840714-beauty-diagram/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-levi840714-beauty-diagram/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-levi840714-beauty-diagram/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-levi840714-beauty-diagram/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-levi840714-beauty-diagram/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T10:48:41.093Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-levi840714-beauty-diagram/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-levi840714-beauty-diagram/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-levi840714-beauty-diagram/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-levi840714-beauty-diagram/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:09:11.055Z","emptyReason":null},"readme":"Skill: beauty-diagram\n\nOwner: levi840714\n\nSummary: Use when the user asks for a sleek, modern Mermaid / PlantUML diagram (e.g. \"beautify this flowchart\", \"make this look like a deck slide\", \"produce an SVG of this architecture\"), wants AI to generate a diagram from a text description, wants a public share link for a diagram, wants to render every diagram file in a folder, or wants to render Mermaid / PlantUML fenced code blocks inside a Markdown file (README, docs) into images. This skill teaches you to call the Beauty Diagram CLI (`bd`) — never to hand-author SVG when a source diagram exists.\n\nTags: latest:1.7.0\n\nVersion history:\n\nv1.7.0 | 2026-08-04T09:09:19.687Z | user\n\ninline\n\nv1.6.1 | 2026-06-15T19:10:44.183Z | user\n\nadd bd:bg comment\n\nv1.6.0 | 2026-05-22T17:01:35.412Z | user\n\ndocument bd extract --share watermark-free mode\n\nv1.5.0 | 2026-05-19T05:56:45.965Z | user\n\nenhance theme tier\n\nv1.4.0 | 2026-05-05T06:38:13.025Z | user\n\nadd embed feature\n\nv1.3.0 | 2026-05-04T15:51:26.222Z | user\n\nmodify /export qualify params\n\nv1.2.0 | 2026-05-04T09:27:42.384Z | user\n\nnew batch, extract feature\n\nv1.1.0 | 2026-04-30T06:37:42.511Z | user\n\nnew ai generate feature\n\nv1.0.0 | 2026-04-27T09:29:33.994Z | user\n\nInitial release\n\nArchive index:\n\nArchive v1.7.0: 9 files, 14811 bytes\n\nFiles: CHANGELOG.md (535b), package.json (381b), README.md (5764b), scripts/ai-generate.sh (805b), scripts/beautify.sh (361b), scripts/export.sh (300b), skill-card.md (2611b), SKILL.md (19624b), _meta.json (133b)\n\nFile v1.7.0:SKILL.md\n\n---\nname: beauty-diagram\ndescription: Use when the user asks for a sleek, modern Mermaid / PlantUML diagram (e.g. \"beautify this flowchart\", \"make this look like a deck slide\", \"produce an SVG of this architecture\"), wants AI to generate a diagram from a text description, wants a public share link for a diagram, wants to render every diagram file in a folder, or wants to render Mermaid / PlantUML fenced code blocks inside a Markdown file (README, docs) into images. This skill teaches you to call the Beauty Diagram CLI (`bd`) — never to hand-author SVG when a source diagram exists.\nversion: 1.7.0\nmetadata:\n openclaw:\n requires:\n bins:\n - node\n - npx\n---\n\n# Beauty Diagram skill\n\nBeauty Diagram beautifies Mermaid / PlantUML diagrams into\nsleek, modern SVG or PNG. It runs as a public API; this skill\ndelegates to the `bd` CLI (npm package `@beauty-diagram/cli`) so you\nkeep zero state in the agent. (draw.io / SVG import is editor-only —\nnot exposed through `/v1/*`.)\n\n## When to use\n\n- The user asks for a **polished, professional, slide-ready** version of a\n diagram source they already have or you can generate.\n- The user wants you to **render Mermaid or PlantUML** from a model-generated\n source string.\n- The user wants the server to **generate a diagram from a text description**\n (\"draw me a signup flow\", \"diagram our deploy pipeline\") — use\n `bd ai generate` for this; it returns Mermaid source you then beautify.\n- The user wants to **share a diagram link** (e.g. paste into Slack / a doc).\n- The user has Mermaid in a repo (README, ADR, RFC) and wants to **export\n SVGs** alongside.\n- The user has a **directory full of diagram source files** and wants every one\n of them rendered (e.g. \"render all the .mmd files in docs/diagrams\"). Use\n `bd batch`.\n- The user wants their **Markdown files (README, ADR, blog post) to display the\n diagrams inline** on GitHub / their static site, not just show the source\n code block. Use `bd extract` — three modes available:\n - **Default (inline)**: no flags. Injects `/v1/beautify.svg?source=...` URLs\n after each fence. No API calls during extract, no files written, no quota\n consumed. Always watermarked (anonymous endpoint).\n - **Share (`--share`)**: mints a `/v1/share/.svg` URL per unique fence.\n **Watermark-free for Pro/Premium**. Requires an API key. Each unique\n source consumes 1 share quota the first time; identical fences are\n deduplicated; per-owner local cache means re-runs cost zero quota.\n - **Sidecar (`--assets-dir ./img`)**: writes local SVG files via `/v1/export`.\n Watermark-free for Pro/Premium, consumes export quota.\n GitHub strips raw inline ``, so any of these modes' `![](...)`\n reference is the correct embed strategy.\n\n## When NOT to use\n\n- The user only wants the Mermaid source itself, not an export.\n- The user wants pixel-precise control over the SVG markup (Beauty Diagram\n rewrites layout for presentation; it does not preserve raw Mermaid output).\n- The user wants the AI to \"change the colors / theme / font / layout\" of an\n existing diagram. `bd ai generate` only does **text → diagram**; visual\n styling is controlled by `--theme` on `bd beautify`, not by the AI.\n- The user is in an offline environment with no network and no CLI install.\n\n## Required tool\n\nThe `bd` binary from `@beauty-diagram/cli`:\n\n```bash\nnpx @beauty-diagram/cli help\n# or, after install:\nbd help\n```\n\nIf the user has not installed it, prefer `npx` over a global install — it\nrespects their package manager and avoids polluting `PATH`.\n\n## Workflow\n\n1. **Identify or generate the source diagram.**\n - If the user has a `.mmd` / `.puml` file, use it.\n - If the user describes the diagram in words and is on a paid plan, use\n `bd ai generate \"\" --out .mmd` — the server returns\n Mermaid source, which you can then beautify. Always write the source\n to a file so the user can edit it; the first AI draft rarely lands.\n - If the user describes the diagram and is **not** on a paid plan (or\n prefers not to pay), write Mermaid source yourself (you are good at\n this), save it to a file, then beautify.\n - draw.io and free-form SVG imports are not accepted by `/v1/*`. If\n the user has those, ask them to convert via the web editor first.\n\n2. **Decide on output type.**\n - Need an SVG file: `bd beautify --out .svg`\n - Need a download URL or to track quota: `bd export --out .svg`\n - Need a shareable link: `bd share --title \"...\"`\n\n3. **Run the command.** Always write to a file (`--out`) rather than letting\n the SVG flood the terminal / chat. AI generation can also pipe directly\n into beautify: `bd ai generate \"...\" | bd beautify - --out flow.svg`.\n\n4. **Verify the result exists** before reporting success. If the command\n failed, surface the error code (e.g. `quota_exhausted`, `not_authenticated`,\n `parse_failed`, `prompt_injection`) — those are actionable for the user.\n\n5. **Preserve the source.** Never replace the original Mermaid / PlantUML file\n with the generated SVG — keep them side by side. For AI-generated diagrams,\n keep the `.mmd` file too: it is the editable artifact, the SVG is not.\n\n## Auth\n\n- **Demo (anonymous):** zero setup. Watermarked SVG/PNG. Limits per IP:\n 20 `/v1/beautify` requests / minute, **1 `/v1/export` per 24h** (trial\n budget — enough for an agent to verify the toolchain end-to-end before\n registering). `/v1/share`, `/v1/usage`, and **`bd ai generate` always\n require auth** — anonymous AI calls are rejected before any model\n invocation.\n- **Authenticated:** the user runs `bd auth login` once with a key from\n [`/account/api-keys`](https://www.beauty-diagram.com/account/api-keys).\n Required for `bd share`, `bd ai generate`, unwatermarked output, and\n repeated exports. `bd ai generate` additionally requires a Pro or\n Premium plan and an API key with the `ai:write` scope.\n\nIf the user hits a `not_authenticated`, `plan_not_allowed`, or\n`quota_exhausted` error, point them at `/account/api-keys` (PAT creation)\nor pricing — don't silently retry. Anonymous error bodies include a\n`hints` block with absolute `signUpUrl` / `signInUrl` / `apiDocsUrl`,\nwhich is the canonical place to surface to the user.\n\n## Themes & tiers\n\n`--theme` selects the visual style. Theme tier is enforced on **all `bd`\ncommands that hit a `/v1/*` endpoint with a PAT** — this includes\n`bd beautify`, `bd export`, `bd share`, `bd embed-url --share`,\n`bd batch`, `bd extract --share`, and sidecar mode of `bd extract`. If the request includes a\nPAT and specifies a theme above that token's plan tier, the server returns\nHTTP 403 `theme_tier_required`.\n\nThe only path that bypasses the tier check is the **anonymous fallback**\n(no token, or the `GET /v1/beautify.svg` inline embed endpoint). Anonymous\ncallers may request any theme, but always receive watermarked output — there\nis no tier-free, watermark-free path.\n\n| Tier | Themes |\n|---|---|\n| Free | `classic`, `modern`, `slate` |\n| Pro | + `atlas`, `obsidian`, `brutalist`, `atelier` |\n| Premium | + `blueprint`, `memphis` |\n\nWhen the user's plan is unknown, default to `modern` (Free, broadly\nslide-friendly). Run `bd themes` to introspect what the current token\ncan use — locked themes are marked with `✗`. Premium signature themes\n(`blueprint`, `memphis`) are subscriber-only and cannot be unlocked\nwith credit packs.\n\nAnimations are not currently selectable via the CLI — animation choice\nis a web-editor concept; CLI export paths ignore animation.\n\n## Source-level directives\n\nInstead of (or in addition to) CLI flags, you can embed `bd:` directives at\nthe **very top** of the source file. Both the `bd` CLI and the Obsidian plugin\nparse them; the API server ignores them as native comments (graceful\ndegradation — the source still renders, just without the directive).\n\n**Mermaid** — use `%%` comment syntax:\n\n```\n%% bd:theme=classic\n%% bd:bg=transparent\nflowchart LR\n A --> B\n```\n\n**PlantUML** — use `'` comment syntax:\n\n```\n' bd:theme=classic\n' bd:bg=transparent\n@startuml\nA -> B\n@enduml\n```\n\nSupported keys:\n\n| Key | Values | Effect |\n|---|---|---|\n| `theme` | `classic modern slate atlas obsidian brutalist atelier blueprint memphis` | Override render theme. Tier gating still applies. |\n| `bg` | `theme white dark transparent` | Canvas background. `dark` hue-lifts ink so it stays legible; `transparent` for overlay. Unknown → `theme`. |\n\nMultiple directives stack, one per line. Blank lines between directives are\ntolerated. The first non-directive non-blank line ends the directive block.\n\n**Override priority:** CLI flag > source directive > server default.\n\nWhen generating source for the user, prefer directives over CLI flags when:\n- The source file will be re-used (Obsidian vault, shared repo) — the\n directive travels with the file.\n- The user asks for a \"memphis theme\" diagram without CLI context (write\n `%% bd:theme=memphis` at the top of the `.mmd` file).\n\nDirectives are stripped before the source reaches the renderer — they do not\nappear in the SVG output.\n\n## Commands cheat sheet\n\n```bash\n# Render a Mermaid file\nbd beautify docs/architecture.mmd --theme modern --out docs/architecture.svg\n\n# Same but treat output as a downloadable export (consumes export quota)\nbd export docs/architecture.mmd --out docs/architecture.svg\n\n# PNG export. --quality standard works for everyone; high needs pro, max needs premium.\n# Higher tiers than the plan cap are silently clamped (X-BD-Scale-Clamped).\nbd export docs/architecture.mmd --format png --quality high --out docs/architecture.png\n\n# PlantUML works the same way; .puml / .plantuml / .pu auto-detected,\n# otherwise pass --source-format plantuml.\nbd export docs/architecture.puml --out docs/architecture.svg\n\n# Create a public share link (returns absolute https://www.beauty-diagram.com/s/... URL)\nbd share docs/architecture.mmd --title \"Service architecture\"\n# → prints the URL on stdout\n\n# Get an embeddable -friendly URL for a diagram source.\n# Default: anonymous inline URL (always watermarked) + a hint about --share.\nbd embed-url docs/architecture.mmd --theme atlas\n# One-shot saved share embed (clean output for pro/premium owners).\n# Saves the diagram via /v1/share AND prints the embed URL in one step.\nbd embed-url docs/architecture.mmd --share\n# → prints https://api.beauty-diagram.com/v1/share/.svg\n\n# AI: generate a diagram from a text prompt. Output is Mermaid source —\n# always write to a file so the user can iterate. Paid-only.\nbd ai generate \"user signup with email verification\" --out docs/signup.mmd\n\n# Optional shape hint when the prompt is ambiguous about diagram type.\nbd ai generate \"request lifecycle\" --hint sequence --out docs/lifecycle.mmd\n\n# One-shot pipeline: prompt → mermaid → beautify → SVG.\nbd ai generate \"deploy flow\" | bd beautify - --out docs/deploy.svg\n\n# Check remaining AI / export quota before kicking off a batch.\nbd usage\n\n# Render every diagram file under a directory in parallel.\n# Recurses for .mmd / .puml / .plantuml / .pu; one /v1/export per file.\n# Default concurrency=4, default failure mode is continue-on-error.\nbd batch ./docs/diagrams --out-dir ./docs/svg --theme modern\n\n# Same idea but for a glob (quote it so the shell doesn't expand first).\nbd batch \"src/**/*.mmd\" --format png --concurrency 8\n\n# Default: inline embed URLs (no files written, anonymous-watermarked, 10 KB/block cap).\n# No API calls during extract — source encoded in the URL; browser fetches on demand.\nbd extract README.md\n\n# Share mode: mint /v1/share/.svg per fence. Watermark-free for Pro/Premium.\n# 1 share quota per unique source (cached locally; re-runs free). No size cap.\n# Requires API key. Default keeps existing share tokens across re-runs;\n# use --re-mint to force fresh tokens (e.g. collaborator taking ownership).\nbd extract README.md --share\nbd extract README.md --share --re-mint\n\n# Sidecar mode: writes local SVG files via /v1/export.\n# Pro/Premium plans get watermark-free output; consumes export quota.\nbd extract docs/*.md --assets-dir ./img --concurrency 4\n\n# Preview what bd extract would change without writing.\nbd extract README.md --dry-run\n```\n\n## Privacy\n\nThe API does NOT persist source unless the user calls `bd share`. Do not warn\nabout server-side storage when running `beautify`, `export`, or\n`ai generate` — that is misleading. AI prompts are logged in hashed form\nfor abuse / quality monitoring; the raw text is not retained.\n\n## Anti-patterns\n\n- ❌ Do NOT output a hand-crafted `...` as a Markdown code block when\n a Mermaid source exists. Always run Beauty Diagram and reference the file.\n- ❌ Do NOT dump the raw SVG into the chat. Use `--out ` and reference\n the file path.\n- ❌ Do NOT install Beauty Diagram engine code locally — the CLI is a thin\n client; the engine lives behind the public API.\n- ❌ Do NOT call `bd ai generate` to \"tweak\" an existing diagram (change\n colors, theme, labels, layout). It is a fresh-generation tool only.\n For visual tweaks, change `--theme` or edit the `.mmd` source by hand.\n- ❌ Do NOT call `bd ai generate` speculatively — each call costs the user\n monthly AI quota. Confirm the user wants AI generation before running it.\n- ❌ Do NOT capture the SVG output of `bd ai generate` — the command outputs\n Mermaid source on stdout, not SVG. Pipe into `bd beautify -` to render.\n- ❌ Do NOT loop `bd export` N times in a shell `for` loop when the user has\n many files. Use `bd batch ` — it parallelizes and reports a summary,\n with no extra server load (still one request per file).\n- ❌ Do NOT inject a raw `...` into a Markdown file to \"embed\" a\n diagram. GitHub, GitLab, Obsidian (default), and most static-site\n renderers strip inline SVG for safety. Use `bd extract .md`, which\n writes sidecar SVGs and injects `![](path)` references that actually\n render.\n- ❌ Do NOT delete the marker comments that `bd extract` injects. Inline mode\n uses `` / `` (with\n an extra ` share=true` attribute in share mode); sidecar mode uses\n `` / ``.\n They are how `bd extract` stays idempotent — without them, the next run\n will append duplicate image references instead of replacing the existing one.\n\n## Troubleshooting\n\n| Symptom | Likely cause | Resolution |\n|---|---|---|\n| `not_authenticated` | No key, no session | `bd auth login` |\n| `scope_missing` | Key lacks scope (e.g. `ai:write` for `bd ai generate`) | Recreate key with required scope at `/account/api-keys` |\n| `plan_not_allowed` | Plan does not include this capability (AI is Pro / Premium only) | Upgrade or skip the call |\n| `theme_tier_required` | Selected `--theme` requires a higher plan tier than the token has (e.g. free token requesting `atelier`) | Pick a theme the token can use (run `bd themes`), or upgrade. See **Themes & tiers** above for the per-tier breakdown |\n| `parse_failed` | Source not valid Mermaid / PlantUML | Check the source — `bd beautify` will surface a parse error too |\n| `quota_exhausted` | Plan limit hit (anon: 1 export/IP/24h; free: 3 exports/mo; pro: 100 exports + 100 AI gens/mo; premium: ∞ exports + 500 AI gens/mo) | Sign in, wait for reset, or upgrade — `hints` in the response body has the URLs |\n| `rate_limited` | Anonymous IP bucket full (20 `/v1/beautify` requests / minute) or AI per-key bucket (30 `/min`) | Sign in or wait |\n| `source_too_large` | Source > 100 KB | Split the diagram |\n| `output_too_large` | PNG raster exceeds 8192 px | Lower `--quality` or simplify |\n| `prompt_injection` | AI prompt looked like an injection attempt | Rephrase as a plain diagram description (\"a flowchart of …\") |\n| `instruction_rejected` | AI judged the prompt was not about a diagram | Rephrase to describe a concrete diagram. Quota was NOT consumed |\n| `parse_failed_after_retry` | AI output was unparseable Mermaid even after one retry | Rephrase, or write Mermaid by hand. Quota was NOT consumed |\n| `safety_blocked` | Provider safety filter rejected the request | Rephrase the prompt |\n| `upstream_timeout` / `upstream_error` | AI provider was slow or failed | Retry after a moment |\n\n## Triggering on embed requests\n\nWhen the user asks for \"a GitHub README diagram\", \"embed in Notion\", \"embed in my blog post\", \"an `` of this diagram\", or \"a URL that renders my diagram\", route to the embed flow rather than emitting raw mermaid:\n\n1. If the diagram is unsaved, run `bd share ` to save it.\n2. Construct the embed URL: `https://api.beauty-diagram.com/v1/share/.svg`.\n3. For one-off / quick embeds without saving, use `bd embed-url ` and recommend the inline URL (note that anonymous embeds carry a \"Powered by Beauty Diagram\" watermark).\n\n**Easier one-shot path:** `bd embed-url --share` saves the diagram AND prints the embed URL in one command — no need to run `bd share` separately and then construct the URL by hand. Prefer this when the user wants a clean share embed.\n\n**Style fidelity:** Per-node colors, edge presets, and font overrides set by the user in the web canvas editor ARE faithfully rendered in share-mode embeds (`/v1/share/.svg`). Encourage a \"tweak in editor → save → embed\" workflow when the user wants brand colors or custom styling — they do not need to re-run `bd embed-url` after editing in the web UI, just re-save the diagram there.\n\n**Propagation timing:** Saved diagram edits show up in direct `` embeds within ~5 minutes (browser ETag revalidation + 5-min CDN edge TTL). GitHub README embeds may lag a few hours due to GitHub's image proxy cache — that is a GitHub-side cache, not something we can purge.\n\n**Animations:** Animations do NOT play in ``-loaded SVGs in any browser. Do not tell the user their animated diagram will appear animated in a README or Notion embed.\n\n**Slack / Discord / Twitter / iMessage previews**: share links (`https://www.beauty-diagram.com/s/`) auto-unfurl with a diagram thumbnail card on these platforms — no need to manually attach a screenshot. The OG image is generated server-side from the diagram itself.\n\n**Owner-tier fallback on embed URLs**: if the share's owner downgraded their plan AFTER saving the diagram (e.g. saved with Atelier on Pro, then downgraded to Free), `GET /v1/share/.svg` returns a 200 response with a brand-fallback SVG instead of the real content. Embeds must stay 200 for ``-mounted unfurls to render at all, so 403 is not used here. The owner can restore the original render by re-upgrading or switching to a free-tier theme and re-saving.\n\n## Example\n\nUser: \"Add a beautified version of this mermaid block to my README.\"\n\nAgent steps:\n1. Use the one-step path: `bd embed-url ./architecture.mmd --share`\n → saves the diagram and prints the embed URL, e.g.\n `https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg`\n2. Replace the raw mermaid block in README with:\n `![Architecture](https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg)`\n3. (Optional) Confirm with the user that watermark behavior matches their plan\n (free owner → watermarked; pro/premium owner → clean).\n\n## Examples\n\nSee `examples/` for runnable sources you can adapt:\n\n- `examples/flowchart.mmd`\n- `examples/sequence.mmd`\n\nAnd `scripts/` for shell wrappers you can copy into the user's repo:\n\n- `scripts/beautify.sh`\n- `scripts/export.sh`\n- `scripts/ai-generate.sh` — prompt → `.mmd` source → `.svg` render\n\nFile v1.7.0:README.md\n\n# Beauty Diagram skill\n\nTurn Mermaid / PlantUML source into sleek, modern SVG or PNG — straight\nfrom your agent. This skill teaches Claude (or any compatible agent) to call\nthe [`bd` CLI](https://www.npmjs.com/package/@beauty-diagram/cli) instead of\nhand-authoring SVG, so you get consistent, slide-quality diagrams without\nleaving the conversation.\n\n## What it does\n\n- Beautifies existing Mermaid / PlantUML files into polished SVG/PNG\n- Renders model-generated diagram source on demand\n- **Generates a diagram from a text prompt** via `bd ai generate`\n (Pro / Premium plans only)\n- Produces shareable `https://www.beauty-diagram.com/s/...` links\n- **Generates direct embed URLs** for README / Notion / blog use: runs\n `bd share` and returns `https://api.beauty-diagram.com/v1/share/.svg`\n rather than emitting raw Mermaid — the URL works as a plain ``\n anywhere that renders images. Anonymous (watermarked) embeds are also\n available via `bd embed-url` with no sign-in required.\n- Surfaces actionable error codes (`quota_exhausted`, `parse_failed`,\n `prompt_injection`, …) instead of silently retrying\n\n## Requirements\n\n- **Node.js** (for `npx @beauty-diagram/cli`); no global install needed\n- **Optional**: a Beauty Diagram API key for unwatermarked output, share\n links, and higher quotas — anonymous demo mode works out of the box\n (1 export per IP per 24h)\n- **For AI generation**: an API key with the `ai:write` scope on a Pro\n or Premium plan. Anonymous and free plans cannot call `bd ai generate`.\n\nGet a key at .\n\n## Triggering\n\nThe skill activates when a user asks for things like:\n\n- \"beautify this flowchart\"\n- \"make this Mermaid diagram look like a deck slide\"\n- \"give me an SVG of this architecture\"\n- \"draw me a diagram of the signup flow\"\n- \"share this diagram as a link\"\n\n## Example\n\n```\nYou: Here's our service flow in Mermaid — make it slide-ready and give me a share link.\n\nAgent (uses skill):\n $ bd beautify flow.mmd --theme modern --out flow.svg\n $ bd share flow.mmd --title \"Service flow\"\n → https://www.beauty-diagram.com/s/abc123\n```\n\n```\nYou: Draw me a deploy pipeline diagram and beautify it.\n\nAgent (uses skill, Pro plan):\n $ bd ai generate \"deploy pipeline with build, test, staging, prod\" --out deploy.mmd\n $ bd beautify deploy.mmd --out deploy.svg\n → wrote deploy.mmd (editable) + deploy.svg (presentation)\n```\n\n```\nYou: Add this architecture diagram to my README as an embedded image.\n\nAgent (uses skill, Pro/Premium plan):\n $ bd embed-url ./architecture.mmd --share\n → https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg\n Injects into README: ![Architecture](https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg)\n```\n\nSee `examples/` for runnable diagram sources and `scripts/` for shell\nwrappers you can drop into a repo.\n\n## Source-level directives\n\nBoth the `bd` CLI and the Obsidian plugin support `bd:KEY=VALUE` directives\nembedded at the **start of your diagram source** as native comments. The API\nserver does not parse them, but because they are valid comment syntax for both\nMermaid and PlantUML, the source renders normally everywhere — graceful\ndegradation at no cost.\n\n### Grammar\n\n**Mermaid** — one directive per `%%` comment line:\n\n```\n%% bd:theme=classic\n%% bd:bg=transparent\nflowchart LR\n A --> B\n```\n\n**PlantUML** — one directive per `'` comment line:\n\n```\n' bd:theme=classic\n' bd:bg=transparent\n@startuml\nA -> B\n@enduml\n```\n\nRules:\n- All `bd:` lines must appear **before the first non-blank, non-directive line**.\n- Blank lines between directives are tolerated.\n- Multiple directives stack — both `theme` and `bg` can be set together.\n\n### Supported keys\n\n| Key | Accepted values | Notes |\n|---|---|---|\n| `theme` | `classic`, `modern`, `slate`, `atlas`, `obsidian`, `brutalist`, `atelier`, `blueprint`, `memphis` | Overrides the render theme. Tier gating still applies — anonymous callers get watermarked output regardless of theme. |\n| `bg` | `theme`, `white`, `dark`, `transparent` | Canvas background. `dark` automatically hue-lifts the diagram's ink so edges and labels stay legible; `transparent` is useful for overlaying on coloured slide backgrounds. Unknown values fall back to `theme`. |\n\nTheme tiers: **Free** — `classic`, `modern`, `slate`; **Pro** — adds `atlas`,\n`obsidian`, `brutalist`, `atelier`; **Premium** — adds `blueprint`, `memphis`.\n\n### Override priority\n\n```\nCLI flag > source directive > server default\n```\n\nA `--theme atlas` flag always wins over a `%% bd:theme=classic` directive in\nthe source. Directives are useful when the file is the single source of truth\n(shared repos, Obsidian vaults) and the CLI flags aren't part of the workflow.\n\n### Why use directives instead of CLI flags?\n\n- The theme intent **travels with the file** — anyone who opens the `.mmd` in\n the Obsidian plugin, or runs `bd beautify` without `--theme`, still gets the\n right style.\n- Works transparently in the Obsidian plugin, where there is no CLI invocation.\n- Directives are stripped before the source reaches the renderer — they do not\n appear in the SVG output.\n\n## Files\n\n```\nbeauty-diagram-skill/\n├── SKILL.md # agent-facing instructions\n├── examples/ # sample Mermaid sources\n│ ├── flowchart.mmd\n│ └── sequence.mmd\n└── scripts/ # copy-pasteable shell wrappers\n ├── beautify.sh\n ├── export.sh\n └── ai-generate.sh # prompt → .mmd → .svg\n```\n\n## Links\n\n- Site: \n- CLI on npm: \n- API keys: \n\n## License\n\nMIT-0 (per ClawHub publishing terms).\n\nFile v1.7.0:_meta.json\n\n{\n \"ownerId\": \"kn727br5w8gyw9x95hd4cs66ss85nwcg\",\n \"slug\": \"beauty-diagram\",\n \"version\": \"1.7.0\",\n \"publishedAt\": 1785834559687\n}\n\nFile v1.7.0:CHANGELOG.md\n\n# Changelog\n\nAll notable changes to the `beauty-diagram` skill are documented here.\n\n## [1.6.1] - 2026-06-16\n\n### Changed: `bd:bg` now documents the full `white` / `dark` / `transparent` set\n\n- The `bg` directive previously documented `transparent` as the only honoured value. It now documents the full set the CLI and API accept — `theme` (default), `white`, `dark` (the diagram's ink is hue-lifted so edges and labels stay legible), and `transparent` — so the skill suggests the right value. Unknown values fall back to `theme`.\n\nFile v1.7.0:skill-card.md\n\n## Description:\n\nGuides agents to use the Beauty Diagram CLI to generate, beautify, export, share, and embed Mermaid or PlantUML diagrams as polished SVG or PNG outputs.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[levi840714](https://clawhub.ai/user/levi840714)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, technical writers, and agents use this skill to turn Mermaid or PlantUML source into presentation-ready diagram files, share links, or Markdown embeds. It also guides optional text-to-diagram generation through the Beauty Diagram CLI when the user has the required plan and API scope.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The scripts invoke an unpinned npm CLI, so behavior could change when `npx @beauty-diagram/cli` resolves a newer package.\n\nMitigation: Pin or lock the `@beauty-diagram/cli` version before use and review package updates before adopting them.\n\nRisk: Share and share-embed workflows can publish diagrams to public external URLs.\n\nMitigation: Ask for explicit approval before creating hosted URLs, and prefer local sidecar SVG output for private repositories or sensitive diagrams.\n\nRisk: Diagram sources or prompts are sent to Beauty Diagram when workflows call the public API.\n\nMitigation: Use the skill only with content suitable for Beauty Diagram processing and run the CLI with least privilege in workspaces that may contain secrets.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/levi840714/skills/beauty-diagram)\n- [Beauty Diagram site](https://www.beauty-diagram.com)\n- [Beauty Diagram CLI on npm](https://www.npmjs.com/package/@beauty-diagram/cli)\n- [Beauty Diagram API keys](https://www.beauty-diagram.com/account/api-keys)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with shell commands, Mermaid or PlantUML source, file paths, and generated SVG/PNG or share/embed URL references]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May produce local .mmd, .puml, .svg, or .png files and public Beauty Diagram share/embed URLs depending on the selected workflow.]\n\n## Skill Version(s):\n\n1.7.0 (source: ClawHub release, SKILL.md frontmatter, package.json; CHANGELOG top entry is 1.6.1)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.7.0:package.json\n\n{\n \"name\": \"@beauty-diagram/skill\",\n \"version\": \"1.7.0\",\n \"private\": true,\n \"description\": \"Beauty Diagram agent skill — instructs LLM agents how to call the bd CLI for sleek, modern diagrams.\",\n \"files\": [\n \"SKILL.md\",\n \"README.md\",\n \"examples\",\n \"scripts\"\n ],\n \"publishConfig\": {\n \"access\": \"public\"\n },\n \"dependencies\": {\n \"clawhub\": \"^0.9.0\"\n }\n}\n\nArchive v1.6.1: 9 files, 14794 bytes\n\nFiles: CHANGELOG.md (535b), package.json (381b), README.md (5764b), scripts/ai-generate.sh (805b), scripts/beautify.sh (361b), scripts/export.sh (300b), skill-card.md (2748b), SKILL.md (19623b), _meta.json (133b)\n\nFile v1.6.1:SKILL.md\n\n---\nname: beauty-diagram\ndescription: Use when the user asks for a sleek, modern Mermaid / PlantUML diagram (e.g. \"beautify this flowchart\", \"make this look like a deck slide\", \"produce an SVG of this architecture\"), wants AI to generate a diagram from a text description, wants a public share link for a diagram, wants to render every diagram file in a folder, or wants to render Mermaid / PlantUML fenced code blocks inside a Markdown file (README, docs) into images. This skill teaches you to call the Beauty Diagram CLI (`bd`) — never to hand-author SVG when a source diagram exists.\nversion: 1.6.1\nmetadata:\n openclaw:\n requires:\n bins:\n - node\n - npx\n---\n\n# Beauty Diagram skill\n\nBeauty Diagram beautifies Mermaid / PlantUML diagrams into\nsleek, modern SVG or PNG. It runs as a public API; this skill\ndelegates to the `bd` CLI (npm package `@beauty-diagram/cli`) so you\nkeep zero state in the agent. (draw.io / SVG import is editor-only —\nnot exposed through `/v1/*`.)\n\n## When to use\n\n- The user asks for a **polished, professional, slide-ready** version of a\n diagram source they already have or you can generate.\n- The user wants you to **render Mermaid or PlantUML** from a model-generated\n source string.\n- The user wants the server to **generate a diagram from a text description**\n (\"draw me a signup flow\", \"diagram our deploy pipeline\") — use\n `bd ai generate` for this; it returns Mermaid source you then beautify.\n- The user wants to **share a diagram link** (e.g. paste into Slack / a doc).\n- The user has Mermaid in a repo (README, ADR, RFC) and wants to **export\n SVGs** alongside.\n- The user has a **directory full of diagram source files** and wants every one\n of them rendered (e.g. \"render all the .mmd files in docs/diagrams\"). Use\n `bd batch`.\n- The user wants their **Markdown files (README, ADR, blog post) to display the\n diagrams inline** on GitHub / their static site, not just show the source\n code block. Use `bd extract` — three modes available:\n - **Default (inline)**: no flags. Injects `/v1/beautify.svg?source=...` URLs\n after each fence. No API calls during extract, no files written, no quota\n consumed. Always watermarked (anonymous endpoint).\n - **Share (`--share`)**: mints a `/v1/share/.svg` URL per unique fence.\n **Watermark-free for Pro/Premium**. Requires an API key. Each unique\n source consumes 1 share quota the first time; identical fences are\n deduplicated; per-owner local cache means re-runs cost zero quota.\n - **Sidecar (`--assets-dir ./img`)**: writes local SVG files via `/v1/export`.\n Watermark-free for Pro/Premium, consumes export quota.\n GitHub strips raw inline ``, so any of these modes' `![](...)`\n reference is the correct embed strategy.\n\n## When NOT to use\n\n- The user only wants the Mermaid source itself, not an export.\n- The user wants pixel-precise control over the SVG markup (Beauty Diagram\n rewrites layout for presentation; it does not preserve raw Mermaid output).\n- The user wants the AI to \"change the colors / theme / font / layout\" of an\n existing diagram. `bd ai generate` only does **text → diagram**; visual\n styling is controlled by `--theme` on `bd beautify`, not by the AI.\n- The user is in an offline environment with no network and no CLI install.\n\n## Required tool\n\nThe `bd` binary from `@beauty-diagram/cli`:\n\n```bash\nnpx @beauty-diagram/cli help\n# or, after install:\nbd help\n```\n\nIf the user has not installed it, prefer `npx` over a global install — it\nrespects their package manager and avoids polluting `PATH`.\n\n## Workflow\n\n1. **Identify or generate the source diagram.**\n - If the user has a `.mmd` / `.puml` file, use it.\n - If the user describes the diagram in words and is on a paid plan, use\n `bd ai generate \"\" --out .mmd` — the server returns\n Mermaid source, which you can then beautify. Always write the source\n to a file so the user can edit it; the first AI draft rarely lands.\n - If the user describes the diagram and is **not** on a paid plan (or\n prefers not to pay), write Mermaid source yourself (you are good at\n this), save it to a file, then beautify.\n - draw.io and free-form SVG imports are not accepted by `/v1/*`. If\n the user has those, ask them to convert via the web editor first.\n\n2. **Decide on output type.**\n - Need an SVG file: `bd beautify --out .svg`\n - Need a download URL or to track quota: `bd export --out .svg`\n - Need a shareable link: `bd share --title \"...\"`\n\n3. **Run the command.** Always write to a file (`--out`) rather than letting\n the SVG flood the terminal / chat. AI generation can also pipe directly\n into beautify: `bd ai generate \"...\" | bd beautify - --out flow.svg`.\n\n4. **Verify the result exists** before reporting success. If the command\n failed, surface the error code (e.g. `quota_exhausted`, `not_authenticated`,\n `parse_failed`, `prompt_injection`) — those are actionable for the user.\n\n5. **Preserve the source.** Never replace the original Mermaid / PlantUML file\n with the generated SVG — keep them side by side. For AI-generated diagrams,\n keep the `.mmd` file too: it is the editable artifact, the SVG is not.\n\n## Auth\n\n- **Demo (anonymous):** zero setup. Watermarked SVG/PNG. Limits per IP:\n 20 `/v1/beautify` requests / minute, **1 `/v1/export` per 24h** (trial\n budget — enough for an agent to verify the toolchain end-to-end before\n registering). `/v1/share`, `/v1/usage`, and **`bd ai generate` always\n require auth** — anonymous AI calls are rejected before any model\n invocation.\n- **Authenticated:** the user runs `bd auth login` once with a key from\n [`/account/api-keys`](https://www.beauty-diagram.com/account/api-keys).\n Required for `bd share`, `bd ai generate`, unwatermarked output, and\n repeated exports. `bd ai generate` additionally requires a Pro or\n Premium plan and an API key with the `ai:write` scope.\n\nIf the user hits a `not_authenticated`, `plan_not_allowed`, or\n`quota_exhausted` error, point them at `/account/api-keys` (PAT creation)\nor pricing — don't silently retry. Anonymous error bodies include a\n`hints` block with absolute `signUpUrl` / `signInUrl` / `apiDocsUrl`,\nwhich is the canonical place to surface to the user.\n\n## Themes & tiers\n\n`--theme` selects the visual style. Theme tier is enforced on **all `bd`\ncommands that hit a `/v1/*` endpoint with a PAT** — this includes\n`bd beautify`, `bd export`, `bd share`, `bd embed-url --share`,\n`bd batch`, `bd extract --share`, and sidecar mode of `bd extract`. If the request includes a\nPAT and specifies a theme above that token's plan tier, the server returns\nHTTP 403 `theme_tier_required`.\n\nThe only path that bypasses the tier check is the **anonymous fallback**\n(no token, or the `GET /v1/beautify.svg` inline embed endpoint). Anonymous\ncallers may request any theme, but always receive watermarked output — there\nis no tier-free, watermark-free path.\n\n| Tier | Themes |\n|---|---|\n| Free | `classic`, `modern`, `slate` |\n| Pro | + `atlas`, `obsidian`, `brutalist`, `atelier` |\n| Premium | + `blueprint`, `memphis` |\n\nWhen the user's plan is unknown, default to `modern` (Free, broadly\nslide-friendly). Run `bd themes` to introspect what the current token\ncan use — locked themes are marked with `✗`. Premium signature themes\n(`blueprint`, `memphis`) are subscriber-only and cannot be unlocked\nwith credit packs.\n\nAnimations are not currently selectable via the CLI — animation choice\nis a web-editor concept; CLI export paths ignore animation.\n\n## Source-level directives\n\nInstead of (or in addition to) CLI flags, you can embed `bd:` directives at\nthe **very top** of the source file. Both the `bd` CLI and the Obsidian plugin\nparse them; the API server ignores them as native comments (graceful\ndegradation — the source still renders, just without the directive).\n\n**Mermaid** — use `%%` comment syntax:\n\n```\n%% bd:theme=classic\n%% bd:bg=transparent\nflowchart LR\n A --> B\n```\n\n**PlantUML** — use `'` comment syntax:\n\n```\n' bd:theme=classic\n' bd:bg=transparent\n@startuml\nA -> B\n@enduml\n```\n\nSupported keys:\n\n| Key | Values | Effect |\n|---|---|---|\n| `theme` | `classic modern slate atlas obsidian brutalist atelier blueprint memphis` | Override render theme. Tier gating still applies. |\n| `bg` | `theme white dark transparent` | Canvas background. `dark` hue-lifts ink so it stays legible; `transparent` for overlay. Unknown → `theme`. |\n\nMultiple directives stack, one per line. Blank lines between directives are\ntolerated. The first non-directive non-blank line ends the directive block.\n\n**Override priority:** CLI flag > source directive > server default.\n\nWhen generating source for the user, prefer directives over CLI flags when:\n- The source file will be re-used (Obsidian vault, shared repo) — the\n directive travels with the file.\n- The user asks for a \"memphis theme\" diagram without CLI context (write\n `%% bd:theme=memphis` at the top of the `.mmd` file).\n\nDirectives are stripped before the source reaches the renderer — they do not\nappear in the SVG output.\n\n## Commands cheat sheet\n\n```bash\n# Render a Mermaid file\nbd beautify docs/architecture.mmd --theme modern --out docs/architecture.svg\n\n# Same but treat output as a downloadable export (consumes export quota)\nbd export docs/architecture.mmd --out docs/architecture.svg\n\n# PNG export. --quality standard works for everyone; high needs pro, max needs premium.\n# Higher tiers than the plan cap are silently clamped (X-BD-Scale-Clamped).\nbd export docs/architecture.mmd --format png --quality high --out docs/architecture.png\n\n# PlantUML works the same way; .puml / .plantuml / .pu auto-detected,\n# otherwise pass --source-format plantuml.\nbd export docs/architecture.puml --out docs/architecture.svg\n\n# Create a public share link (returns absolute https://www.beauty-diagram.com/s/... URL)\nbd share docs/architecture.mmd --title \"Service architecture\"\n# → prints the URL on stdout\n\n# Get an embeddable -friendly URL for a diagram source.\n# Default: anonymous inline URL (always watermarked) + a hint about --share.\nbd embed-url docs/architecture.mmd --theme atlas\n# One-shot saved share embed (clean output for pro/premium owners).\n# Saves the diagram via /v1/share AND prints the embed URL in one step.\nbd embed-url docs/architecture.mmd --share\n# → prints https://api.beauty-diagram.com/v1/share/.svg\n\n# AI: generate a diagram from a text prompt. Output is Mermaid source —\n# always write to a file so the user can iterate. Paid-only.\nbd ai generate \"user signup with email verification\" --out docs/signup.mmd\n\n# Optional shape hint when the prompt is ambiguous about diagram type.\nbd ai generate \"request lifecycle\" --hint sequence --out docs/lifecycle.mmd\n\n# One-shot pipeline: prompt → mermaid → beautify → SVG.\nbd ai generate \"deploy flow\" | bd beautify - --out docs/deploy.svg\n\n# Check remaining AI / export quota before kicking off a batch.\nbd usage\n\n# Render every diagram file under a directory in parallel.\n# Recurses for .mmd / .puml / .plantuml / .pu; one /v1/export per file.\n# Default concurrency=4, default failure mode is continue-on-error.\nbd batch ./docs/diagrams --out-dir ./docs/svg --theme modern\n\n# Same idea but for a glob (quote it so the shell doesn't expand first).\nbd batch \"src/**/*.mmd\" --format png --concurrency 8\n\n# Default: inline embed URLs (no files written, anonymous-watermarked, 5 KB/block cap).\n# No API calls during extract — source encoded in the URL; browser fetches on demand.\nbd extract README.md\n\n# Share mode: mint /v1/share/.svg per fence. Watermark-free for Pro/Premium.\n# 1 share quota per unique source (cached locally; re-runs free). No 5 KB cap.\n# Requires API key. Default keeps existing share tokens across re-runs;\n# use --re-mint to force fresh tokens (e.g. collaborator taking ownership).\nbd extract README.md --share\nbd extract README.md --share --re-mint\n\n# Sidecar mode: writes local SVG files via /v1/export.\n# Pro/Premium plans get watermark-free output; consumes export quota.\nbd extract docs/*.md --assets-dir ./img --concurrency 4\n\n# Preview what bd extract would change without writing.\nbd extract README.md --dry-run\n```\n\n## Privacy\n\nThe API does NOT persist source unless the user calls `bd share`. Do not warn\nabout server-side storage when running `beautify`, `export`, or\n`ai generate` — that is misleading. AI prompts are logged in hashed form\nfor abuse / quality monitoring; the raw text is not retained.\n\n## Anti-patterns\n\n- ❌ Do NOT output a hand-crafted `...` as a Markdown code block when\n a Mermaid source exists. Always run Beauty Diagram and reference the file.\n- ❌ Do NOT dump the raw SVG into the chat. Use `--out ` and reference\n the file path.\n- ❌ Do NOT install Beauty Diagram engine code locally — the CLI is a thin\n client; the engine lives behind the public API.\n- ❌ Do NOT call `bd ai generate` to \"tweak\" an existing diagram (change\n colors, theme, labels, layout). It is a fresh-generation tool only.\n For visual tweaks, change `--theme` or edit the `.mmd` source by hand.\n- ❌ Do NOT call `bd ai generate` speculatively — each call costs the user\n monthly AI quota. Confirm the user wants AI generation before running it.\n- ❌ Do NOT capture the SVG output of `bd ai generate` — the command outputs\n Mermaid source on stdout, not SVG. Pipe into `bd beautify -` to render.\n- ❌ Do NOT loop `bd export` N times in a shell `for` loop when the user has\n many files. Use `bd batch ` — it parallelizes and reports a summary,\n with no extra server load (still one request per file).\n- ❌ Do NOT inject a raw `...` into a Markdown file to \"embed\" a\n diagram. GitHub, GitLab, Obsidian (default), and most static-site\n renderers strip inline SVG for safety. Use `bd extract .md`, which\n writes sidecar SVGs and injects `![](path)` references that actually\n render.\n- ❌ Do NOT delete the marker comments that `bd extract` injects. Inline mode\n uses `` / `` (with\n an extra ` share=true` attribute in share mode); sidecar mode uses\n `` / ``.\n They are how `bd extract` stays idempotent — without them, the next run\n will append duplicate image references instead of replacing the existing one.\n\n## Troubleshooting\n\n| Symptom | Likely cause | Resolution |\n|---|---|---|\n| `not_authenticated` | No key, no session | `bd auth login` |\n| `scope_missing` | Key lacks scope (e.g. `ai:write` for `bd ai generate`) | Recreate key with required scope at `/account/api-keys` |\n| `plan_not_allowed` | Plan does not include this capability (AI is Pro / Premium only) | Upgrade or skip the call |\n| `theme_tier_required` | Selected `--theme` requires a higher plan tier than the token has (e.g. free token requesting `atelier`) | Pick a theme the token can use (run `bd themes`), or upgrade. See **Themes & tiers** above for the per-tier breakdown |\n| `parse_failed` | Source not valid Mermaid / PlantUML | Check the source — `bd beautify` will surface a parse error too |\n| `quota_exhausted` | Plan limit hit (anon: 1 export/IP/24h; free: 3 exports/mo; pro: 100 exports + 100 AI gens/mo; premium: ∞ exports + 500 AI gens/mo) | Sign in, wait for reset, or upgrade — `hints` in the response body has the URLs |\n| `rate_limited` | Anonymous IP bucket full (20 `/v1/beautify` requests / minute) or AI per-key bucket (30 `/min`) | Sign in or wait |\n| `source_too_large` | Source > 100 KB | Split the diagram |\n| `output_too_large` | PNG raster exceeds 8192 px | Lower `--quality` or simplify |\n| `prompt_injection` | AI prompt looked like an injection attempt | Rephrase as a plain diagram description (\"a flowchart of …\") |\n| `instruction_rejected` | AI judged the prompt was not about a diagram | Rephrase to describe a concrete diagram. Quota was NOT consumed |\n| `parse_failed_after_retry` | AI output was unparseable Mermaid even after one retry | Rephrase, or write Mermaid by hand. Quota was NOT consumed |\n| `safety_blocked` | Provider safety filter rejected the request | Rephrase the prompt |\n| `upstream_timeout` / `upstream_error` | AI provider was slow or failed | Retry after a moment |\n\n## Triggering on embed requests\n\nWhen the user asks for \"a GitHub README diagram\", \"embed in Notion\", \"embed in my blog post\", \"an `` of this diagram\", or \"a URL that renders my diagram\", route to the embed flow rather than emitting raw mermaid:\n\n1. If the diagram is unsaved, run `bd share ` to save it.\n2. Construct the embed URL: `https://api.beauty-diagram.com/v1/share/.svg`.\n3. For one-off / quick embeds without saving, use `bd embed-url ` and recommend the inline URL (note that anonymous embeds carry a \"Powered by Beauty Diagram\" watermark).\n\n**Easier one-shot path:** `bd embed-url --share` saves the diagram AND prints the embed URL in one command — no need to run `bd share` separately and then construct the URL by hand. Prefer this when the user wants a clean share embed.\n\n**Style fidelity:** Per-node colors, edge presets, and font overrides set by the user in the web canvas editor ARE faithfully rendered in share-mode embeds (`/v1/share/.svg`). Encourage a \"tweak in editor → save → embed\" workflow when the user wants brand colors or custom styling — they do not need to re-run `bd embed-url` after editing in the web UI, just re-save the diagram there.\n\n**Propagation timing:** Saved diagram edits show up in direct `` embeds within ~5 minutes (browser ETag revalidation + 5-min CDN edge TTL). GitHub README embeds may lag a few hours due to GitHub's image proxy cache — that is a GitHub-side cache, not something we can purge.\n\n**Animations:** Animations do NOT play in ``-loaded SVGs in any browser. Do not tell the user their animated diagram will appear animated in a README or Notion embed.\n\n**Slack / Discord / Twitter / iMessage previews**: share links (`https://www.beauty-diagram.com/s/`) auto-unfurl with a diagram thumbnail card on these platforms — no need to manually attach a screenshot. The OG image is generated server-side from the diagram itself.\n\n**Owner-tier fallback on embed URLs**: if the share's owner downgraded their plan AFTER saving the diagram (e.g. saved with Atelier on Pro, then downgraded to Free), `GET /v1/share/.svg` returns a 200 response with a brand-fallback SVG instead of the real content. Embeds must stay 200 for ``-mounted unfurls to render at all, so 403 is not used here. The owner can restore the original render by re-upgrading or switching to a free-tier theme and re-saving.\n\n## Example\n\nUser: \"Add a beautified version of this mermaid block to my README.\"\n\nAgent steps:\n1. Use the one-step path: `bd embed-url ./architecture.mmd --share`\n → saves the diagram and prints the embed URL, e.g.\n `https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg`\n2. Replace the raw mermaid block in README with:\n `![Architecture](https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg)`\n3. (Optional) Confirm with the user that watermark behavior matches their plan\n (free owner → watermarked; pro/premium owner → clean).\n\n## Examples\n\nSee `examples/` for runnable sources you can adapt:\n\n- `examples/flowchart.mmd`\n- `examples/sequence.mmd`\n\nAnd `scripts/` for shell wrappers you can copy into the user's repo:\n\n- `scripts/beautify.sh`\n- `scripts/export.sh`\n- `scripts/ai-generate.sh` — prompt → `.mmd` source → `.svg` render\n\nFile v1.6.1:README.md\n\n# Beauty Diagram skill\n\nTurn Mermaid / PlantUML source into sleek, modern SVG or PNG — straight\nfrom your agent. This skill teaches Claude (or any compatible agent) to call\nthe [`bd` CLI](https://www.npmjs.com/package/@beauty-diagram/cli) instead of\nhand-authoring SVG, so you get consistent, slide-quality diagrams without\nleaving the conversation.\n\n## What it does\n\n- Beautifies existing Mermaid / PlantUML files into polished SVG/PNG\n- Renders model-generated diagram source on demand\n- **Generates a diagram from a text prompt** via `bd ai generate`\n (Pro / Premium plans only)\n- Produces shareable `https://www.beauty-diagram.com/s/...` links\n- **Generates direct embed URLs** for README / Notion / blog use: runs\n `bd share` and returns `https://api.beauty-diagram.com/v1/share/.svg`\n rather than emitting raw Mermaid — the URL works as a plain ``\n anywhere that renders images. Anonymous (watermarked) embeds are also\n available via `bd embed-url` with no sign-in required.\n- Surfaces actionable error codes (`quota_exhausted`, `parse_failed`,\n `prompt_injection`, …) instead of silently retrying\n\n## Requirements\n\n- **Node.js** (for `npx @beauty-diagram/cli`); no global install needed\n- **Optional**: a Beauty Diagram API key for unwatermarked output, share\n links, and higher quotas — anonymous demo mode works out of the box\n (1 export per IP per 24h)\n- **For AI generation**: an API key with the `ai:write` scope on a Pro\n or Premium plan. Anonymous and free plans cannot call `bd ai generate`.\n\nGet a key at .\n\n## Triggering\n\nThe skill activates when a user asks for things like:\n\n- \"beautify this flowchart\"\n- \"make this Mermaid diagram look like a deck slide\"\n- \"give me an SVG of this architecture\"\n- \"draw me a diagram of the signup flow\"\n- \"share this diagram as a link\"\n\n## Example\n\n```\nYou: Here's our service flow in Mermaid — make it slide-ready and give me a share link.\n\nAgent (uses skill):\n $ bd beautify flow.mmd --theme modern --out flow.svg\n $ bd share flow.mmd --title \"Service flow\"\n → https://www.beauty-diagram.com/s/abc123\n```\n\n```\nYou: Draw me a deploy pipeline diagram and beautify it.\n\nAgent (uses skill, Pro plan):\n $ bd ai generate \"deploy pipeline with build, test, staging, prod\" --out deploy.mmd\n $ bd beautify deploy.mmd --out deploy.svg\n → wrote deploy.mmd (editable) + deploy.svg (presentation)\n```\n\n```\nYou: Add this architecture diagram to my README as an embedded image.\n\nAgent (uses skill, Pro/Premium plan):\n $ bd embed-url ./architecture.mmd --share\n → https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg\n Injects into README: ![Architecture](https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg)\n```\n\nSee `examples/` for runnable diagram sources and `scripts/` for shell\nwrappers you can drop into a repo.\n\n## Source-level directives\n\nBoth the `bd` CLI and the Obsidian plugin support `bd:KEY=VALUE` directives\nembedded at the **start of your diagram source** as native comments. The API\nserver does not parse them, but because they are valid comment syntax for both\nMermaid and PlantUML, the source renders normally everywhere — graceful\ndegradation at no cost.\n\n### Grammar\n\n**Mermaid** — one directive per `%%` comment line:\n\n```\n%% bd:theme=classic\n%% bd:bg=transparent\nflowchart LR\n A --> B\n```\n\n**PlantUML** — one directive per `'` comment line:\n\n```\n' bd:theme=classic\n' bd:bg=transparent\n@startuml\nA -> B\n@enduml\n```\n\nRules:\n- All `bd:` lines must appear **before the first non-blank, non-directive line**.\n- Blank lines between directives are tolerated.\n- Multiple directives stack — both `theme` and `bg` can be set together.\n\n### Supported keys\n\n| Key | Accepted values | Notes |\n|---|---|---|\n| `theme` | `classic`, `modern`, `slate`, `atlas`, `obsidian`, `brutalist`, `atelier`, `blueprint`, `memphis` | Overrides the render theme. Tier gating still applies — anonymous callers get watermarked output regardless of theme. |\n| `bg` | `theme`, `white`, `dark`, `transparent` | Canvas background. `dark` automatically hue-lifts the diagram's ink so edges and labels stay legible; `transparent` is useful for overlaying on coloured slide backgrounds. Unknown values fall back to `theme`. |\n\nTheme tiers: **Free** — `classic`, `modern`, `slate`; **Pro** — adds `atlas`,\n`obsidian`, `brutalist`, `atelier`; **Premium** — adds `blueprint`, `memphis`.\n\n### Override priority\n\n```\nCLI flag > source directive > server default\n```\n\nA `--theme atlas` flag always wins over a `%% bd:theme=classic` directive in\nthe source. Directives are useful when the file is the single source of truth\n(shared repos, Obsidian vaults) and the CLI flags aren't part of the workflow.\n\n### Why use directives instead of CLI flags?\n\n- The theme intent **travels with the file** — anyone who opens the `.mmd` in\n the Obsidian plugin, or runs `bd beautify` without `--theme`, still gets the\n right style.\n- Works transparently in the Obsidian plugin, where there is no CLI invocation.\n- Directives are stripped before the source reaches the renderer — they do not\n appear in the SVG output.\n\n## Files\n\n```\nbeauty-diagram-skill/\n├── SKILL.md # agent-facing instructions\n├── examples/ # sample Mermaid sources\n│ ├── flowchart.mmd\n│ └── sequence.mmd\n└── scripts/ # copy-pasteable shell wrappers\n ├── beautify.sh\n ├── export.sh\n └── ai-generate.sh # prompt → .mmd → .svg\n```\n\n## Links\n\n- Site: \n- CLI on npm: \n- API keys: \n\n## License\n\nMIT-0 (per ClawHub publishing terms).\n\nFile v1.6.1:_meta.json\n\n{\n \"ownerId\": \"kn727br5w8gyw9x95hd4cs66ss85nwcg\",\n \"slug\": \"beauty-diagram\",\n \"version\": \"1.6.1\",\n \"publishedAt\": 1781550644183\n}\n\nFile v1.6.1:CHANGELOG.md\n\n# Changelog\n\nAll notable changes to the `beauty-diagram` skill are documented here.\n\n## [1.6.1] - 2026-06-16\n\n### Changed: `bd:bg` now documents the full `white` / `dark` / `transparent` set\n\n- The `bg` directive previously documented `transparent` as the only honoured value. It now documents the full set the CLI and API accept — `theme` (default), `white`, `dark` (the diagram's ink is hue-lifted so edges and labels stay legible), and `transparent` — so the skill suggests the right value. Unknown values fall back to `theme`.\n\nFile v1.6.1:skill-card.md\n\n## Description:
\nBeauty Diagram helps agents use the `bd` CLI to render, export, share, or generate polished Mermaid and PlantUML diagrams as SVG, PNG, and hosted diagram links.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[levi840714](https://clawhub.ai/user/levi840714)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers, technical writers, and agents use this skill to convert Mermaid or PlantUML sources into polished diagram assets, create share links, embed diagrams in Markdown, and optionally generate Mermaid source from a text description.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: The npm CLI sends diagram source or AI prompts to the external Beauty Diagram service.
\nMitigation: Review source and prompt sensitivity before invoking the CLI, and use the workflow only when external processing is acceptable.
\nRisk: Share and embed workflows can create externally hosted diagram URLs and may edit Markdown files.
\nMitigation: Prefer local SVG or PNG outputs for sensitive material, confirm share/embed intent before creating hosted URLs, and review repository diffs after Markdown edits.
\nRisk: Authenticated workflows require a Beauty Diagram API key and, for AI generation, an `ai:write` scope on a Pro or Premium plan.
\nMitigation: Use the minimum required credential scope, avoid exposing tokens in command output or files, and surface authentication, plan, or quota errors directly to the user.
\n\n\n## Reference(s):
\n- [Beauty Diagram ClawHub release](https://clawhub.ai/levi840714/beauty-diagram)
\n- [Beauty Diagram website](https://www.beauty-diagram.com)
\n- [Beauty Diagram CLI on npm](https://www.npmjs.com/package/@beauty-diagram/cli)
\n- [Beauty Diagram API keys](https://www.beauty-diagram.com/account/api-keys)
\n\n\n## Skill Output:
\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]
\n**Output Format:** [Markdown guidance with shell commands and generated Mermaid, SVG, PNG, or hosted diagram URLs]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [May write editable diagram source files, rendered image files, Markdown image references, or share/embed URLs depending on the requested workflow.]
\n\n## Skill Version(s):
\n1.6.1 (source: frontmatter, package.json, changelog, ClawHub release)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v1.6.1:package.json\n\n{\n \"name\": \"@beauty-diagram/skill\",\n \"version\": \"1.6.1\",\n \"private\": true,\n \"description\": \"Beauty Diagram agent skill — instructs LLM agents how to call the bd CLI for sleek, modern diagrams.\",\n \"files\": [\n \"SKILL.md\",\n \"README.md\",\n \"examples\",\n \"scripts\"\n ],\n \"publishConfig\": {\n \"access\": \"public\"\n },\n \"dependencies\": {\n \"clawhub\": \"^0.9.0\"\n }\n}\n\nArchive v1.6.0: 8 files, 14210 bytes\n\nFiles: package.json (381b), README.md (5653b), scripts/ai-generate.sh (805b), scripts/beautify.sh (361b), scripts/export.sh (300b), skill-card.md (2619b), SKILL.md (19543b), _meta.json (133b)\n\nFile v1.6.0:SKILL.md\n\n---\nname: beauty-diagram\ndescription: Use when the user asks for a sleek, modern Mermaid / PlantUML diagram (e.g. \"beautify this flowchart\", \"make this look like a deck slide\", \"produce an SVG of this architecture\"), wants AI to generate a diagram from a text description, wants a public share link for a diagram, wants to render every diagram file in a folder, or wants to render Mermaid / PlantUML fenced code blocks inside a Markdown file (README, docs) into images. This skill teaches you to call the Beauty Diagram CLI (`bd`) — never to hand-author SVG when a source diagram exists.\nversion: 1.6.0\nmetadata:\n openclaw:\n requires:\n bins:\n - node\n - npx\n---\n\n# Beauty Diagram skill\n\nBeauty Diagram beautifies Mermaid / PlantUML diagrams into\nsleek, modern SVG or PNG. It runs as a public API; this skill\ndelegates to the `bd` CLI (npm package `@beauty-diagram/cli`) so you\nkeep zero state in the agent. (draw.io / SVG import is editor-only —\nnot exposed through `/v1/*`.)\n\n## When to use\n\n- The user asks for a **polished, professional, slide-ready** version of a\n diagram source they already have or you can generate.\n- The user wants you to **render Mermaid or PlantUML** from a model-generated\n source string.\n- The user wants the server to **generate a diagram from a text description**\n (\"draw me a signup flow\", \"diagram our deploy pipeline\") — use\n `bd ai generate` for this; it returns Mermaid source you then beautify.\n- The user wants to **share a diagram link** (e.g. paste into Slack / a doc).\n- The user has Mermaid in a repo (README, ADR, RFC) and wants to **export\n SVGs** alongside.\n- The user has a **directory full of diagram source files** and wants every one\n of them rendered (e.g. \"render all the .mmd files in docs/diagrams\"). Use\n `bd batch`.\n- The user wants their **Markdown files (README, ADR, blog post) to display the\n diagrams inline** on GitHub / their static site, not just show the source\n code block. Use `bd extract` — three modes available:\n - **Default (inline)**: no flags. Injects `/v1/beautify.svg?source=...` URLs\n after each fence. No API calls during extract, no files written, no quota\n consumed. Always watermarked (anonymous endpoint).\n - **Share (`--share`)**: mints a `/v1/share/.svg` URL per unique fence.\n **Watermark-free for Pro/Premium**. Requires an API key. Each unique\n source consumes 1 share quota the first time; identical fences are\n deduplicated; per-owner local cache means re-runs cost zero quota.\n - **Sidecar (`--assets-dir ./img`)**: writes local SVG files via `/v1/export`.\n Watermark-free for Pro/Premium, consumes export quota.\n GitHub strips raw inline ``, so any of these modes' `![](...)`\n reference is the correct embed strategy.\n\n## When NOT to use\n\n- The user only wants the Mermaid source itself, not an export.\n- The user wants pixel-precise control over the SVG markup (Beauty Diagram\n rewrites layout for presentation; it does not preserve raw Mermaid output).\n- The user wants the AI to \"change the colors / theme / font / layout\" of an\n existing diagram. `bd ai generate` only does **text → diagram**; visual\n styling is controlled by `--theme` on `bd beautify`, not by the AI.\n- The user is in an offline environment with no network and no CLI install.\n\n## Required tool\n\nThe `bd` binary from `@beauty-diagram/cli`:\n\n```bash\nnpx @beauty-diagram/cli help\n# or, after install:\nbd help\n```\n\nIf the user has not installed it, prefer `npx` over a global install — it\nrespects their package manager and avoids polluting `PATH`.\n\n## Workflow\n\n1. **Identify or generate the source diagram.**\n - If the user has a `.mmd` / `.puml` file, use it.\n - If the user describes the diagram in words and is on a paid plan, use\n `bd ai generate \"\" --out .mmd` — the server returns\n Mermaid source, which you can then beautify. Always write the source\n to a file so the user can edit it; the first AI draft rarely lands.\n - If the user describes the diagram and is **not** on a paid plan (or\n prefers not to pay), write Mermaid source yourself (you are good at\n this), save it to a file, then beautify.\n - draw.io and free-form SVG imports are not accepted by `/v1/*`. If\n the user has those, ask them to convert via the web editor first.\n\n2. **Decide on output type.**\n - Need an SVG file: `bd beautify --out .svg`\n - Need a download URL or to track quota: `bd export --out .svg`\n - Need a shareable link: `bd share --title \"...\"`\n\n3. **Run the command.** Always write to a file (`--out`) rather than letting\n the SVG flood the terminal / chat. AI generation can also pipe directly\n into beautify: `bd ai generate \"...\" | bd beautify - --out flow.svg`.\n\n4. **Verify the result exists** before reporting success. If the command\n failed, surface the error code (e.g. `quota_exhausted`, `not_authenticated`,\n `parse_failed`, `prompt_injection`) — those are actionable for the user.\n\n5. **Preserve the source.** Never replace the original Mermaid / PlantUML file\n with the generated SVG — keep them side by side. For AI-generated diagrams,\n keep the `.mmd` file too: it is the editable artifact, the SVG is not.\n\n## Auth\n\n- **Demo (anonymous):** zero setup. Watermarked SVG/PNG. Limits per IP:\n 20 `/v1/beautify` requests / minute, **1 `/v1/export` per 24h** (trial\n budget — enough for an agent to verify the toolchain end-to-end before\n registering). `/v1/share`, `/v1/usage`, and **`bd ai generate` always\n require auth** — anonymous AI calls are rejected before any model\n invocation.\n- **Authenticated:** the user runs `bd auth login` once with a key from\n [`/account/api-keys`](https://www.beauty-diagram.com/account/api-keys).\n Required for `bd share`, `bd ai generate`, unwatermarked output, and\n repeated exports. `bd ai generate` additionally requires a Pro or\n Premium plan and an API key with the `ai:write` scope.\n\nIf the user hits a `not_authenticated`, `plan_not_allowed`, or\n`quota_exhausted` error, point them at `/account/api-keys` (PAT creation)\nor pricing — don't silently retry. Anonymous error bodies include a\n`hints` block with absolute `signUpUrl` / `signInUrl` / `apiDocsUrl`,\nwhich is the canonical place to surface to the user.\n\n## Themes & tiers\n\n`--theme` selects the visual style. Theme tier is enforced on **all `bd`\ncommands that hit a `/v1/*` endpoint with a PAT** — this includes\n`bd beautify`, `bd export`, `bd share`, `bd embed-url --share`,\n`bd batch`, `bd extract --share`, and sidecar mode of `bd extract`. If the request includes a\nPAT and specifies a theme above that token's plan tier, the server returns\nHTTP 403 `theme_tier_required`.\n\nThe only path that bypasses the tier check is the **anonymous fallback**\n(no token, or the `GET /v1/beautify.svg` inline embed endpoint). Anonymous\ncallers may request any theme, but always receive watermarked output — there\nis no tier-free, watermark-free path.\n\n| Tier | Themes |\n|---|---|\n| Free | `classic`, `modern`, `slate` |\n| Pro | + `atlas`, `obsidian`, `brutalist`, `atelier` |\n| Premium | + `blueprint`, `memphis` |\n\nWhen the user's plan is unknown, default to `modern` (Free, broadly\nslide-friendly). Run `bd themes` to introspect what the current token\ncan use — locked themes are marked with `✗`. Premium signature themes\n(`blueprint`, `memphis`) are subscriber-only and cannot be unlocked\nwith credit packs.\n\nAnimations are not currently selectable via the CLI — animation choice\nis a web-editor concept; CLI export paths ignore animation.\n\n## Source-level directives\n\nInstead of (or in addition to) CLI flags, you can embed `bd:` directives at\nthe **very top** of the source file. Both the `bd` CLI and the Obsidian plugin\nparse them; the API server ignores them as native comments (graceful\ndegradation — the source still renders, just without the directive).\n\n**Mermaid** — use `%%` comment syntax:\n\n```\n%% bd:theme=classic\n%% bd:bg=transparent\nflowchart LR\n A --> B\n```\n\n**PlantUML** — use `'` comment syntax:\n\n```\n' bd:theme=classic\n' bd:bg=transparent\n@startuml\nA -> B\n@enduml\n```\n\nSupported keys:\n\n| Key | Values | Effect |\n|---|---|---|\n| `theme` | `classic modern slate atlas obsidian brutalist atelier blueprint memphis` | Override render theme. Tier gating still applies. |\n| `bg` | `transparent` | Transparent canvas. Other values are ignored. |\n\nMultiple directives stack, one per line. Blank lines between directives are\ntolerated. The first non-directive non-blank line ends the directive block.\n\n**Override priority:** CLI flag > source directive > server default.\n\nWhen generating source for the user, prefer directives over CLI flags when:\n- The source file will be re-used (Obsidian vault, shared repo) — the\n directive travels with the file.\n- The user asks for a \"memphis theme\" diagram without CLI context (write\n `%% bd:theme=memphis` at the top of the `.mmd` file).\n\nDirectives are stripped before the source reaches the renderer — they do not\nappear in the SVG output.\n\n## Commands cheat sheet\n\n```bash\n# Render a Mermaid file\nbd beautify docs/architecture.mmd --theme modern --out docs/architecture.svg\n\n# Same but treat output as a downloadable export (consumes export quota)\nbd export docs/architecture.mmd --out docs/architecture.svg\n\n# PNG export. --quality standard works for everyone; high needs pro, max needs premium.\n# Higher tiers than the plan cap are silently clamped (X-BD-Scale-Clamped).\nbd export docs/architecture.mmd --format png --quality high --out docs/architecture.png\n\n# PlantUML works the same way; .puml / .plantuml / .pu auto-detected,\n# otherwise pass --source-format plantuml.\nbd export docs/architecture.puml --out docs/architecture.svg\n\n# Create a public share link (returns absolute https://www.beauty-diagram.com/s/... URL)\nbd share docs/architecture.mmd --title \"Service architecture\"\n# → prints the URL on stdout\n\n# Get an embeddable -friendly URL for a diagram source.\n# Default: anonymous inline URL (always watermarked) + a hint about --share.\nbd embed-url docs/architecture.mmd --theme atlas\n# One-shot saved share embed (clean output for pro/premium owners).\n# Saves the diagram via /v1/share AND prints the embed URL in one step.\nbd embed-url docs/architecture.mmd --share\n# → prints https://api.beauty-diagram.com/v1/share/.svg\n\n# AI: generate a diagram from a text prompt. Output is Mermaid source —\n# always write to a file so the user can iterate. Paid-only.\nbd ai generate \"user signup with email verification\" --out docs/signup.mmd\n\n# Optional shape hint when the prompt is ambiguous about diagram type.\nbd ai generate \"request lifecycle\" --hint sequence --out docs/lifecycle.mmd\n\n# One-shot pipeline: prompt → mermaid → beautify → SVG.\nbd ai generate \"deploy flow\" | bd beautify - --out docs/deploy.svg\n\n# Check remaining AI / export quota before kicking off a batch.\nbd usage\n\n# Render every diagram file under a directory in parallel.\n# Recurses for .mmd / .puml / .plantuml / .pu; one /v1/export per file.\n# Default concurrency=4, default failure mode is continue-on-error.\nbd batch ./docs/diagrams --out-dir ./docs/svg --theme modern\n\n# Same idea but for a glob (quote it so the shell doesn't expand first).\nbd batch \"src/**/*.mmd\" --format png --concurrency 8\n\n# Default: inline embed URLs (no files written, anonymous-watermarked, 5 KB/block cap).\n# No API calls during extract — source encoded in the URL; browser fetches on demand.\nbd extract README.md\n\n# Share mode: mint /v1/share/.svg per fence. Watermark-free for Pro/Premium.\n# 1 share quota per unique source (cached locally; re-runs free). No 5 KB cap.\n# Requires API key. Default keeps existing share tokens across re-runs;\n# use --re-mint to force fresh tokens (e.g. collaborator taking ownership).\nbd extract README.md --share\nbd extract README.md --share --re-mint\n\n# Sidecar mode: writes local SVG files via /v1/export.\n# Pro/Premium plans get watermark-free output; consumes export quota.\nbd extract docs/*.md --assets-dir ./img --concurrency 4\n\n# Preview what bd extract would change without writing.\nbd extract README.md --dry-run\n```\n\n## Privacy\n\nThe API does NOT persist source unless the user calls `bd share`. Do not warn\nabout server-side storage when running `beautify`, `export`, or\n`ai generate` — that is misleading. AI prompts are logged in hashed form\nfor abuse / quality monitoring; the raw text is not retained.\n\n## Anti-patterns\n\n- ❌ Do NOT output a hand-crafted `...` as a Markdown code block when\n a Mermaid source exists. Always run Beauty Diagram and reference the file.\n- ❌ Do NOT dump the raw SVG into the chat. Use `--out ` and reference\n the file path.\n- ❌ Do NOT install Beauty Diagram engine code locally — the CLI is a thin\n client; the engine lives behind the public API.\n- ❌ Do NOT call `bd ai generate` to \"tweak\" an existing diagram (change\n colors, theme, labels, layout). It is a fresh-generation tool only.\n For visual tweaks, change `--theme` or edit the `.mmd` source by hand.\n- ❌ Do NOT call `bd ai generate` speculatively — each call costs the user\n monthly AI quota. Confirm the user wants AI generation before running it.\n- ❌ Do NOT capture the SVG output of `bd ai generate` — the command outputs\n Mermaid source on stdout, not SVG. Pipe into `bd beautify -` to render.\n- ❌ Do NOT loop `bd export` N times in a shell `for` loop when the user has\n many files. Use `bd batch ` — it parallelizes and reports a summary,\n with no extra server load (still one request per file).\n- ❌ Do NOT inject a raw `...` into a Markdown file to \"embed\" a\n diagram. GitHub, GitLab, Obsidian (default), and most static-site\n renderers strip inline SVG for safety. Use `bd extract .md`, which\n writes sidecar SVGs and injects `![](path)` references that actually\n render.\n- ❌ Do NOT delete the marker comments that `bd extract` injects. Inline mode\n uses `` / `` (with\n an extra ` share=true` attribute in share mode); sidecar mode uses\n `` / ``.\n They are how `bd extract` stays idempotent — without them, the next run\n will append duplicate image references instead of replacing the existing one.\n\n## Troubleshooting\n\n| Symptom | Likely cause | Resolution |\n|---|---|---|\n| `not_authenticated` | No key, no session | `bd auth login` |\n| `scope_missing` | Key lacks scope (e.g. `ai:write` for `bd ai generate`) | Recreate key with required scope at `/account/api-keys` |\n| `plan_not_allowed` | Plan does not include this capability (AI is Pro / Premium only) | Upgrade or skip the call |\n| `theme_tier_required` | Selected `--theme` requires a higher plan tier than the token has (e.g. free token requesting `atelier`) | Pick a theme the token can use (run `bd themes`), or upgrade. See **Themes & tiers** above for the per-tier breakdown |\n| `parse_failed` | Source not valid Mermaid / PlantUML | Check the source — `bd beautify` will surface a parse error too |\n| `quota_exhausted` | Plan limit hit (anon: 1 export/IP/24h; free: 3 exports/mo; pro: 100 exports + 100 AI gens/mo; premium: ∞ exports + 500 AI gens/mo) | Sign in, wait for reset, or upgrade — `hints` in the response body has the URLs |\n| `rate_limited` | Anonymous IP bucket full (20 `/v1/beautify` requests / minute) or AI per-key bucket (30 `/min`) | Sign in or wait |\n| `source_too_large` | Source > 100 KB | Split the diagram |\n| `output_too_large` | PNG raster exceeds 8192 px | Lower `--quality` or simplify |\n| `prompt_injection` | AI prompt looked like an injection attempt | Rephrase as a plain diagram description (\"a flowchart of …\") |\n| `instruction_rejected` | AI judged the prompt was not about a diagram | Rephrase to describe a concrete diagram. Quota was NOT consumed |\n| `parse_failed_after_retry` | AI output was unparseable Mermaid even after one retry | Rephrase, or write Mermaid by hand. Quota was NOT consumed |\n| `safety_blocked` | Provider safety filter rejected the request | Rephrase the prompt |\n| `upstream_timeout` / `upstream_error` | AI provider was slow or failed | Retry after a moment |\n\n## Triggering on embed requests\n\nWhen the user asks for \"a GitHub README diagram\", \"embed in Notion\", \"embed in my blog post\", \"an `` of this diagram\", or \"a URL that renders my diagram\", route to the embed flow rather than emitting raw mermaid:\n\n1. If the diagram is unsaved, run `bd share ` to save it.\n2. Construct the embed URL: `https://api.beauty-diagram.com/v1/share/.svg`.\n3. For one-off / quick embeds without saving, use `bd embed-url ` and recommend the inline URL (note that anonymous embeds carry a \"Powered by Beauty Diagram\" watermark).\n\n**Easier one-shot path:** `bd embed-url --share` saves the diagram AND prints the embed URL in one command — no need to run `bd share` separately and then construct the URL by hand. Prefer this when the user wants a clean share embed.\n\n**Style fidelity:** Per-node colors, edge presets, and font overrides set by the user in the web canvas editor ARE faithfully rendered in share-mode embeds (`/v1/share/.svg`). Encourage a \"tweak in editor → save → embed\" workflow when the user wants brand colors or custom styling — they do not need to re-run `bd embed-url` after editing in the web UI, just re-save the diagram there.\n\n**Propagation timing:** Saved diagram edits show up in direct `` embeds within ~5 minutes (browser ETag revalidation + 5-min CDN edge TTL). GitHub README embeds may lag a few hours due to GitHub's image proxy cache — that is a GitHub-side cache, not something we can purge.\n\n**Animations:** Animations do NOT play in ``-loaded SVGs in any browser. Do not tell the user their animated diagram will appear animated in a README or Notion embed.\n\n**Slack / Discord / Twitter / iMessage previews**: share links (`https://www.beauty-diagram.com/s/`) auto-unfurl with a diagram thumbnail card on these platforms — no need to manually attach a screenshot. The OG image is generated server-side from the diagram itself.\n\n**Owner-tier fallback on embed URLs**: if the share's owner downgraded their plan AFTER saving the diagram (e.g. saved with Atelier on Pro, then downgraded to Free), `GET /v1/share/.svg` returns a 200 response with a brand-fallback SVG instead of the real content. Embeds must stay 200 for ``-mounted unfurls to render at all, so 403 is not used here. The owner can restore the original render by re-upgrading or switching to a free-tier theme and re-saving.\n\n## Example\n\nUser: \"Add a beautified version of this mermaid block to my README.\"\n\nAgent steps:\n1. Use the one-step path: `bd embed-url ./architecture.mmd --share`\n → saves the diagram and prints the embed URL, e.g.\n `https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg`\n2. Replace the raw mermaid block in README with:\n `![Architecture](https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg)`\n3. (Optional) Confirm with the user that watermark behavior matches their plan\n (free owner → watermarked; pro/premium owner → clean).\n\n## Examples\n\nSee `examples/` for runnable sources you can adapt:\n\n- `examples/flowchart.mmd`\n- `examples/sequence.mmd`\n\nAnd `scripts/` for shell wrappers you can copy into the user's repo:\n\n- `scripts/beautify.sh`\n- `scripts/export.sh`\n- `scripts/ai-generate.sh` — prompt → `.mmd` source → `.svg` render\n\nFile v1.6.0:README.md\n\n# Beauty Diagram skill\n\nTurn Mermaid / PlantUML source into sleek, modern SVG or PNG — straight\nfrom your agent. This skill teaches Claude (or any compatible agent) to call\nthe [`bd` CLI](https://www.npmjs.com/package/@beauty-diagram/cli) instead of\nhand-authoring SVG, so you get consistent, slide-quality diagrams without\nleaving the conversation.\n\n## What it does\n\n- Beautifies existing Mermaid / PlantUML files into polished SVG/PNG\n- Renders model-generated diagram source on demand\n- **Generates a diagram from a text prompt** via `bd ai generate`\n (Pro / Premium plans only)\n- Produces shareable `https://www.beauty-diagram.com/s/...` links\n- **Generates direct embed URLs** for README / Notion / blog use: runs\n `bd share` and returns `https://api.beauty-diagram.com/v1/share/.svg`\n rather than emitting raw Mermaid — the URL works as a plain ``\n anywhere that renders images. Anonymous (watermarked) embeds are also\n available via `bd embed-url` with no sign-in required.\n- Surfaces actionable error codes (`quota_exhausted`, `parse_failed`,\n `prompt_injection`, …) instead of silently retrying\n\n## Requirements\n\n- **Node.js** (for `npx @beauty-diagram/cli`); no global install needed\n- **Optional**: a Beauty Diagram API key for unwatermarked output, share\n links, and higher quotas — anonymous demo mode works out of the box\n (1 export per IP per 24h)\n- **For AI generation**: an API key with the `ai:write` scope on a Pro\n or Premium plan. Anonymous and free plans cannot call `bd ai generate`.\n\nGet a key at .\n\n## Triggering\n\nThe skill activates when a user asks for things like:\n\n- \"beautify this flowchart\"\n- \"make this Mermaid diagram look like a deck slide\"\n- \"give me an SVG of this architecture\"\n- \"draw me a diagram of the signup flow\"\n- \"share this diagram as a link\"\n\n## Example\n\n```\nYou: Here's our service flow in Mermaid — make it slide-ready and give me a share link.\n\nAgent (uses skill):\n $ bd beautify flow.mmd --theme modern --out flow.svg\n $ bd share flow.mmd --title \"Service flow\"\n → https://www.beauty-diagram.com/s/abc123\n```\n\n```\nYou: Draw me a deploy pipeline diagram and beautify it.\n\nAgent (uses skill, Pro plan):\n $ bd ai generate \"deploy pipeline with build, test, staging, prod\" --out deploy.mmd\n $ bd beautify deploy.mmd --out deploy.svg\n → wrote deploy.mmd (editable) + deploy.svg (presentation)\n```\n\n```\nYou: Add this architecture diagram to my README as an embedded image.\n\nAgent (uses skill, Pro/Premium plan):\n $ bd embed-url ./architecture.mmd --share\n → https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg\n Injects into README: ![Architecture](https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg)\n```\n\nSee `examples/` for runnable diagram sources and `scripts/` for shell\nwrappers you can drop into a repo.\n\n## Source-level directives\n\nBoth the `bd` CLI and the Obsidian plugin support `bd:KEY=VALUE` directives\nembedded at the **start of your diagram source** as native comments. The API\nserver does not parse them, but because they are valid comment syntax for both\nMermaid and PlantUML, the source renders normally everywhere — graceful\ndegradation at no cost.\n\n### Grammar\n\n**Mermaid** — one directive per `%%` comment line:\n\n```\n%% bd:theme=classic\n%% bd:bg=transparent\nflowchart LR\n A --> B\n```\n\n**PlantUML** — one directive per `'` comment line:\n\n```\n' bd:theme=classic\n' bd:bg=transparent\n@startuml\nA -> B\n@enduml\n```\n\nRules:\n- All `bd:` lines must appear **before the first non-blank, non-directive line**.\n- Blank lines between directives are tolerated.\n- Multiple directives stack — both `theme` and `bg` can be set together.\n\n### Supported keys\n\n| Key | Accepted values | Notes |\n|---|---|---|\n| `theme` | `classic`, `modern`, `slate`, `atlas`, `obsidian`, `brutalist`, `atelier`, `blueprint`, `memphis` | Overrides the render theme. Tier gating still applies — anonymous callers get watermarked output regardless of theme. |\n| `bg` | `transparent` | Renders with a transparent canvas. Useful for overlaying on colored slide backgrounds. Any other value is silently ignored. |\n\nTheme tiers: **Free** — `classic`, `modern`, `slate`; **Pro** — adds `atlas`,\n`obsidian`, `brutalist`, `atelier`; **Premium** — adds `blueprint`, `memphis`.\n\n### Override priority\n\n```\nCLI flag > source directive > server default\n```\n\nA `--theme atlas` flag always wins over a `%% bd:theme=classic` directive in\nthe source. Directives are useful when the file is the single source of truth\n(shared repos, Obsidian vaults) and the CLI flags aren't part of the workflow.\n\n### Why use directives instead of CLI flags?\n\n- The theme intent **travels with the file** — anyone who opens the `.mmd` in\n the Obsidian plugin, or runs `bd beautify` without `--theme`, still gets the\n right style.\n- Works transparently in the Obsidian plugin, where there is no CLI invocation.\n- Directives are stripped before the source reaches the renderer — they do not\n appear in the SVG output.\n\n## Files\n\n```\nbeauty-diagram-skill/\n├── SKILL.md # agent-facing instructions\n├── examples/ # sample Mermaid sources\n│ ├── flowchart.mmd\n│ └── sequence.mmd\n└── scripts/ # copy-pasteable shell wrappers\n ├── beautify.sh\n ├── export.sh\n └── ai-generate.sh # prompt → .mmd → .svg\n```\n\n## Links\n\n- Site: \n- CLI on npm: \n- API keys: \n\n## License\n\nMIT-0 (per ClawHub publishing terms).\n\nFile v1.6.0:_meta.json\n\n{\n \"ownerId\": \"kn727br5w8gyw9x95hd4cs66ss85nwcg\",\n \"slug\": \"beauty-diagram\",\n \"version\": \"1.6.0\",\n \"publishedAt\": 1779469295412\n}\n\nFile v1.6.0:skill-card.md\n\n## Description:
\nBeauty Diagram helps agents turn Mermaid and PlantUML diagram source into polished SVG or PNG outputs through the bd CLI, with optional text-to-diagram generation, share links, and embed URLs.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[levi840714](https://clawhub.ai/user/levi840714)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers, engineers, and documentation authors use this skill to render Mermaid or PlantUML diagrams into presentation-ready image files, create share or embed URLs, and optionally generate editable Mermaid source from text prompts when authenticated on an eligible plan.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Share and embed commands can host diagram content on an external Beauty Diagram service, which may expose sensitive architecture or business information if used on private diagrams.
\nMitigation: Confirm the diagram is intended for external hosting before using share or embed commands; use local rendering or checked-in image exports for sensitive internal material.
\nRisk: AI generation and unwatermarked share/export paths require authentication and may consume plan quota.
\nMitigation: Check authentication, plan eligibility, scopes, and quota before running bd ai generate, bd share, or export workflows on behalf of a user.
\n\n\n## Reference(s):
\n- [ClawHub package page](https://clawhub.ai/levi840714/beauty-diagram)
\n- [Beauty Diagram README](README.md)
\n- [Beauty Diagram site](https://www.beauty-diagram.com)
\n- [Beauty Diagram CLI on npm](https://www.npmjs.com/package/@beauty-diagram/cli)
\n\n\n## Skill Output:
\n**Output Type(s):** [text, markdown, code, shell commands, configuration, files]
\n**Output Format:** [Markdown guidance with inline shell commands and file paths; generated agent work may include Mermaid or PlantUML source plus SVG or PNG files.]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Requires Node.js and npx. Optional authenticated Beauty Diagram API use is required for share links, unwatermarked output, higher quotas, and AI generation.]
\n\n## Skill Version(s):
\n1.6.0 (source: frontmatter, package.json, server release metadata)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v1.6.0:package.json\n\n{\n \"name\": \"@beauty-diagram/skill\",\n \"version\": \"1.6.0\",\n \"private\": true,\n \"description\": \"Beauty Diagram agent skill — instructs LLM agents how to call the bd CLI for sleek, modern diagrams.\",\n \"files\": [\n \"SKILL.md\",\n \"README.md\",\n \"examples\",\n \"scripts\"\n ],\n \"publishConfig\": {\n \"access\": \"public\"\n },\n \"dependencies\": {\n \"clawhub\": \"^0.9.0\"\n }\n}\n\nArchive v1.5.0: 7 files, 10946 bytes\n\nFiles: package.json (386b), README.md (3475b), scripts/ai-generate.sh (805b), scripts/beautify.sh (361b), scripts/export.sh (300b), SKILL.md (17182b), _meta.json (133b)\n\nFile v1.5.0:SKILL.md\n\n---\nname: beauty-diagram\ndescription: 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 SVG of this architecture\"), wants AI to generate a diagram from a text description, wants a public share link for a diagram, wants to render every diagram file in a folder, or wants to render Mermaid / PlantUML fenced code blocks inside a Markdown file (README, docs) into images. This skill teaches you to call the Beauty Diagram CLI (`bd`) — never to hand-author SVG when a source diagram exists.\nversion: 1.5.0\nmetadata:\n openclaw:\n requires:\n bins:\n - node\n - npx\n---\n\n# Beauty Diagram skill\n\nBeauty Diagram beautifies Mermaid / PlantUML diagrams into\npresentation-ready SVG or PNG. It runs as a public API; this skill\ndelegates to the `bd` CLI (npm package `@beauty-diagram/cli`) so you\nkeep zero state in the agent. (draw.io / SVG import is editor-only —\nnot exposed through `/v1/*`.)\n\n## When to use\n\n- The user asks for a **polished, professional, slide-ready** version of a\n diagram source they already have or you can generate.\n- The user wants you to **render Mermaid or PlantUML** from a model-generated\n source string.\n- The user wants the server to **generate a diagram from a text description**\n (\"draw me a signup flow\", \"diagram our deploy pipeline\") — use\n `bd ai generate` for this; it returns Mermaid source you then beautify.\n- The user wants to **share a diagram link** (e.g. paste into Slack / a doc).\n- The user has Mermaid in a repo (README, ADR, RFC) and wants to **export\n SVGs** alongside.\n- The user has a **directory full of diagram source files** and wants every one\n of them rendered (e.g. \"render all the .mmd files in docs/diagrams\"). Use\n `bd batch`.\n- The user wants their **Markdown files (README, ADR, blog post) to display the\n diagrams inline** on GitHub / their static site, not just show the source\n code block. Use `bd extract` — by default it injects inline embed URLs\n (no API calls, no files, anonymous-watermarked) after each fenced block.\n Pass `--assets-dir ./img` to write local SVG files instead (sidecar mode,\n Pro/Premium get watermark-free output). GitHub strips raw inline ``, so\n either mode's `![](...)` reference is the correct embed strategy.\n\n## When NOT to use\n\n- The user only wants the Mermaid source itself, not an export.\n- The user wants pixel-precise control over the SVG markup (Beauty Diagram\n rewrites layout for presentation; it does not preserve raw Mermaid output).\n- The user wants the AI to \"change the colors / theme / font / layout\" of an\n existing diagram. `bd ai generate` only does **text → diagram**; visual\n styling is controlled by `--theme` on `bd beautify`, not by the AI.\n- The user is in an offline environment with no network and no CLI install.\n\n## Required tool\n\nThe `bd` binary from `@beauty-diagram/cli`:\n\n```bash\nnpx @beauty-diagram/cli help\n# or, after install:\nbd help\n```\n\nIf the user has not installed it, prefer `npx` over a global install — it\nrespects their package manager and avoids polluting `PATH`.\n\n## Workflow\n\n1. **Identify or generate the source diagram.**\n - If the user has a `.mmd` / `.puml` file, use it.\n - If the user describes the diagram in words and is on a paid plan, use\n `bd ai generate \"\" --out .mmd` — the server returns\n Mermaid source, which you can then beautify. Always write the source\n to a file so the user can edit it; the first AI draft rarely lands.\n - If the user describes the diagram and is **not** on a paid plan (or\n prefers not to pay), write Mermaid source yourself (you are good at\n this), save it to a file, then beautify.\n - draw.io and free-form SVG imports are not accepted by `/v1/*`. If\n the user has those, ask them to convert via the web editor first.\n\n2. **Decide on output type.**\n - Need an SVG file: `bd beautify --out .svg`\n - Need a download URL or to track quota: `bd export --out .svg`\n - Need a shareable link: `bd share --title \"...\"`\n\n3. **Run the command.** Always write to a file (`--out`) rather than letting\n the SVG flood the terminal / chat. AI generation can also pipe directly\n into beautify: `bd ai generate \"...\" | bd beautify - --out flow.svg`.\n\n4. **Verify the result exists** before reporting success. If the command\n failed, surface the error code (e.g. `quota_exhausted`, `not_authenticated`,\n `parse_failed`, `prompt_injection`) — those are actionable for the user.\n\n5. **Preserve the source.** Never replace the original Mermaid / PlantUML file\n with the generated SVG — keep them side by side. For AI-generated diagrams,\n keep the `.mmd` file too: it is the editable artifact, the SVG is not.\n\n## Auth\n\n- **Demo (anonymous):** zero setup. Watermarked SVG/PNG. Limits per IP:\n 20 `/v1/beautify` requests / minute, **1 `/v1/export` per 24h** (trial\n budget — enough for an agent to verify the toolchain end-to-end before\n registering). `/v1/share`, `/v1/usage`, and **`bd ai generate` always\n require auth** — anonymous AI calls are rejected before any model\n invocation.\n- **Authenticated:** the user runs `bd auth login` once with a key from\n [`/account/api-keys`](https://www.beauty-diagram.com/account/api-keys).\n Required for `bd share`, `bd ai generate`, unwatermarked output, and\n repeated exports. `bd ai generate` additionally requires a Pro or\n Premium plan and an API key with the `ai:write` scope.\n\nIf the user hits a `not_authenticated`, `plan_not_allowed`, or\n`quota_exhausted` error, point them at `/account/api-keys` (PAT creation)\nor pricing — don't silently retry. Anonymous error bodies include a\n`hints` block with absolute `signUpUrl` / `signInUrl` / `apiDocsUrl`,\nwhich is the canonical place to surface to the user.\n\n## Themes & tiers\n\n`--theme` selects the visual style. Theme tier is enforced on **all `bd`\ncommands that hit a `/v1/*` endpoint with a PAT** — this includes\n`bd beautify`, `bd export`, `bd share`, `bd embed-url --share`,\n`bd batch`, and sidecar mode of `bd extract`. If the request includes a\nPAT and specifies a theme above that token's plan tier, the server returns\nHTTP 403 `theme_tier_required`.\n\nThe only path that bypasses the tier check is the **anonymous fallback**\n(no token, or the `GET /v1/beautify.svg` inline embed endpoint). Anonymous\ncallers may request any theme, but always receive watermarked output — there\nis no tier-free, watermark-free path.\n\n| Tier | Themes |\n|---|---|\n| Free | `classic`, `modern`, `slate` |\n| Pro | + `atlas`, `obsidian`, `brutalist`, `atelier` |\n| Premium | + `blueprint`, `memphis` |\n\nWhen the user's plan is unknown, default to `modern` (Free, broadly\nslide-friendly). Run `bd themes` to introspect what the current token\ncan use — locked themes are marked with `✗`. Premium signature themes\n(`blueprint`, `memphis`) are subscriber-only and cannot be unlocked\nwith credit packs.\n\nAnimations are not currently selectable via the CLI — animation choice\nis a web-editor concept; CLI export paths ignore animation.\n\n## Commands cheat sheet\n\n```bash\n# Render a Mermaid file\nbd beautify docs/architecture.mmd --theme modern --out docs/architecture.svg\n\n# Same but treat output as a downloadable export (consumes export quota)\nbd export docs/architecture.mmd --out docs/architecture.svg\n\n# PNG export. --quality standard works for everyone; high needs pro, max needs premium.\n# Higher tiers than the plan cap are silently clamped (X-BD-Scale-Clamped).\nbd export docs/architecture.mmd --format png --quality high --out docs/architecture.png\n\n# PlantUML works the same way; .puml / .plantuml / .pu auto-detected,\n# otherwise pass --source-format plantuml.\nbd export docs/architecture.puml --out docs/architecture.svg\n\n# Create a public share link (returns absolute https://www.beauty-diagram.com/s/... URL)\nbd share docs/architecture.mmd --title \"Service architecture\"\n# → prints the URL on stdout\n\n# Get an embeddable -friendly URL for a diagram source.\n# Default: anonymous inline URL (always watermarked) + a hint about --share.\nbd embed-url docs/architecture.mmd --theme atlas\n# One-shot saved share embed (clean output for pro/premium owners).\n# Saves the diagram via /v1/share AND prints the embed URL in one step.\nbd embed-url docs/architecture.mmd --share\n# → prints https://api.beauty-diagram.com/v1/share/.svg\n\n# AI: generate a diagram from a text prompt. Output is Mermaid source —\n# always write to a file so the user can iterate. Paid-only.\nbd ai generate \"user signup with email verification\" --out docs/signup.mmd\n\n# Optional shape hint when the prompt is ambiguous about diagram type.\nbd ai generate \"request lifecycle\" --hint sequence --out docs/lifecycle.mmd\n\n# One-shot pipeline: prompt → mermaid → beautify → SVG.\nbd ai generate \"deploy flow\" | bd beautify - --out docs/deploy.svg\n\n# Check remaining AI / export quota before kicking off a batch.\nbd usage\n\n# Render every diagram file under a directory in parallel.\n# Recurses for .mmd / .puml / .plantuml / .pu; one /v1/export per file.\n# Default concurrency=4, default failure mode is continue-on-error.\nbd batch ./docs/diagrams --out-dir ./docs/svg --theme modern\n\n# Same idea but for a glob (quote it so the shell doesn't expand first).\nbd batch \"src/**/*.mmd\" --format png --concurrency 8\n\n# Default: inline embed URLs (no files written, anonymous-watermarked, 5 KB/block cap).\n# No API calls during extract — source encoded in the URL; browser fetches on demand.\nbd extract README.md\n\n# Sidecar mode: writes local SVG files via /v1/export.\n# Pro/Premium plans get watermark-free output; consumes export quota.\nbd extract docs/*.md --assets-dir ./img --concurrency 4\n\n# Preview what bd extract would change without writing.\nbd extract README.md --dry-run\n```\n\n## Privacy\n\nThe API does NOT persist source unless the user calls `bd share`. Do not warn\nabout server-side storage when running `beautify`, `export`, or\n`ai generate` — that is misleading. AI prompts are logged in hashed form\nfor abuse / quality monitoring; the raw text is not retained.\n\n## Anti-patterns\n\n- ❌ Do NOT output a hand-crafted `...` as a Markdown code block when\n a Mermaid source exists. Always run Beauty Diagram and reference the file.\n- ❌ Do NOT dump the raw SVG into the chat. Use `--out ` and reference\n the file path.\n- ❌ Do NOT install Beauty Diagram engine code locally — the CLI is a thin\n client; the engine lives behind the public API.\n- ❌ Do NOT call `bd ai generate` to \"tweak\" an existing diagram (change\n colors, theme, labels, layout). It is a fresh-generation tool only.\n For visual tweaks, change `--theme` or edit the `.mmd` source by hand.\n- ❌ Do NOT call `bd ai generate` speculatively — each call costs the user\n monthly AI quota. Confirm the user wants AI generation before running it.\n- ❌ Do NOT capture the SVG output of `bd ai generate` — the command outputs\n Mermaid source on stdout, not SVG. Pipe into `bd beautify -` to render.\n- ❌ Do NOT loop `bd export` N times in a shell `for` loop when the user has\n many files. Use `bd batch ` — it parallelizes and reports a summary,\n with no extra server load (still one request per file).\n- ❌ Do NOT inject a raw `...` into a Markdown file to \"embed\" a\n diagram. GitHub, GitLab, Obsidian (default), and most static-site\n renderers strip inline SVG for safety. Use `bd extract .md`, which\n writes sidecar SVGs and injects `![](path)` references that actually\n render.\n- ❌ Do NOT delete the marker comments that `bd extract` injects. Inline mode\n uses `` / ``;\n sidecar mode uses `` / ``.\n They are how `bd extract` stays idempotent — without them, the next run\n will append duplicate image references instead of replacing the existing one.\n\n## Troubleshooting\n\n| Symptom | Likely cause | Resolution |\n|---|---|---|\n| `not_authenticated` | No key, no session | `bd auth login` |\n| `scope_missing` | Key lacks scope (e.g. `ai:write` for `bd ai generate`) | Recreate key with required scope at `/account/api-keys` |\n| `plan_not_allowed` | Plan does not include this capability (AI is Pro / Premium only) | Upgrade or skip the call |\n| `theme_tier_required` | Selected `--theme` requires a higher plan tier than the token has (e.g. free token requesting `atelier`) | Pick a theme the token can use (run `bd themes`), or upgrade. See **Themes & tiers** above for the per-tier breakdown |\n| `parse_failed` | Source not valid Mermaid / PlantUML | Check the source — `bd beautify` will surface a parse error too |\n| `quota_exhausted` | Plan limit hit (anon: 1 export/IP/24h; free: 3 exports/mo; pro: 100 exports + 100 AI gens/mo; premium: ∞ exports + 500 AI gens/mo) | Sign in, wait for reset, or upgrade — `hints` in the response body has the URLs |\n| `rate_limited` | Anonymous IP bucket full (20 `/v1/beautify` requests / minute) or AI per-key bucket (30 `/min`) | Sign in or wait |\n| `source_too_large` | Source > 100 KB | Split the diagram |\n| `output_too_large` | PNG raster exceeds 8192 px | Lower `--quality` or simplify |\n| `prompt_injection` | AI prompt looked like an injection attempt | Rephrase as a plain diagram description (\"a flowchart of …\") |\n| `instruction_rejected` | AI judged the prompt was not about a diagram | Rephrase to describe a concrete diagram. Quota was NOT consumed |\n| `parse_failed_after_retry` | AI output was unparseable Mermaid even after one retry | Rephrase, or write Mermaid by hand. Quota was NOT consumed |\n| `safety_blocked` | Provider safety filter rejected the request | Rephrase the prompt |\n| `upstream_timeout` / `upstream_error` | AI provider was slow or failed | Retry after a moment |\n\n## Triggering on embed requests\n\nWhen the user asks for \"a GitHub README diagram\", \"embed in Notion\", \"embed in my blog post\", \"an `` of this diagram\", or \"a URL that renders my diagram\", route to the embed flow rather than emitting raw mermaid:\n\n1. If the diagram is unsaved, run `bd share ` to save it.\n2. Construct the embed URL: `https://api.beauty-diagram.com/v1/share/.svg`.\n3. For one-off / quick embeds without saving, use `bd embed-url ` and recommend the inline URL (note that anonymous embeds carry a \"Powered by Beauty Diagram\" watermark).\n\n**Easier one-shot path:** `bd embed-url --share` saves the diagram AND prints the embed URL in one command — no need to run `bd share` separately and then construct the URL by hand. Prefer this when the user wants a clean share embed.\n\n**Style fidelity:** Per-node colors, edge presets, and font overrides set by the user in the web canvas editor ARE faithfully rendered in share-mode embeds (`/v1/share/.svg`). Encourage a \"tweak in editor → save → embed\" workflow when the user wants brand colors or custom styling — they do not need to re-run `bd embed-url` after editing in the web UI, just re-save the diagram there.\n\n**Propagation timing:** Saved diagram edits show up in direct `` embeds within ~5 minutes (browser ETag revalidation + 5-min CDN edge TTL). GitHub README embeds may lag a few hours due to GitHub's image proxy cache — that is a GitHub-side cache, not something we can purge.\n\n**Animations:** Animations do NOT play in ``-loaded SVGs in any browser. Do not tell the user their animated diagram will appear animated in a README or Notion embed.\n\n**Slack / Discord / Twitter / iMessage previews**: share links (`https://www.beauty-diagram.com/s/`) auto-unfurl with a diagram thumbnail card on these platforms — no need to manually attach a screenshot. The OG image is generated server-side from the diagram itself.\n\n**Owner-tier fallback on embed URLs**: if the share's owner downgraded their plan AFTER saving the diagram (e.g. saved with Atelier on Pro, then downgraded to Free), `GET /v1/share/.svg` returns a 200 response with a brand-fallback SVG instead of the real content. Embeds must stay 200 for ``-mounted unfurls to render at all, so 403 is not used here. The owner can restore the original render by re-upgrading or switching to a free-tier theme and re-saving.\n\n## Example\n\nUser: \"Add a beautified version of this mermaid block to my README.\"\n\nAgent steps:\n1. Use the one-step path: `bd embed-url ./architecture.mmd --share`\n → saves the diagram and prints the embed URL, e.g.\n `https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg`\n2. Replace the raw mermaid block in README with:\n `![Architecture](https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg)`\n3. (Optional) Confirm with the user that watermark behavior matches their plan\n (free owner → watermarked; pro/premium owner → clean).\n\n## Examples\n\nSee `examples/` for runnable sources you can adapt:\n\n- `examples/flowchart.mmd`\n- `examples/sequence.mmd`\n\nAnd `scripts/` for shell wrappers you can copy into the user's repo:\n\n- `scripts/beautify.sh`\n- `scripts/export.sh`\n- `scripts/ai-generate.sh` — prompt → `.mmd` source → `.svg` render\n\nFile v1.5.0:README.md\n\n# Beauty Diagram skill\n\nTurn Mermaid / PlantUML source into presentation-ready SVG or PNG — straight\nfrom your agent. This skill teaches Claude (or any compatible agent) to call\nthe [`bd` CLI](https://www.npmjs.com/package/@beauty-diagram/cli) instead of\nhand-authoring SVG, so you get consistent, slide-quality diagrams without\nleaving the conversation.\n\n## What it does\n\n- Beautifies existing Mermaid / PlantUML files into polished SVG/PNG\n- Renders model-generated diagram source on demand\n- **Generates a diagram from a text prompt** via `bd ai generate`\n (Pro / Premium plans only)\n- Produces shareable `https://www.beauty-diagram.com/s/...` links\n- **Generates direct embed URLs** for README / Notion / blog use: runs\n `bd share` and returns `https://api.beauty-diagram.com/v1/share/.svg`\n rather than emitting raw Mermaid — the URL works as a plain ``\n anywhere that renders images. Anonymous (watermarked) embeds are also\n available via `bd embed-url` with no sign-in required.\n- Surfaces actionable error codes (`quota_exhausted`, `parse_failed`,\n `prompt_injection`, …) instead of silently retrying\n\n## Requirements\n\n- **Node.js** (for `npx @beauty-diagram/cli`); no global install needed\n- **Optional**: a Beauty Diagram API key for unwatermarked output, share\n links, and higher quotas — anonymous demo mode works out of the box\n (1 export per IP per 24h)\n- **For AI generation**: an API key with the `ai:write` scope on a Pro\n or Premium plan. Anonymous and free plans cannot call `bd ai generate`.\n\nGet a key at .\n\n## Triggering\n\nThe skill activates when a user asks for things like:\n\n- \"beautify this flowchart\"\n- \"make this Mermaid diagram look like a deck slide\"\n- \"give me an SVG of this architecture\"\n- \"draw me a diagram of the signup flow\"\n- \"share this diagram as a link\"\n\n## Example\n\n```\nYou: Here's our service flow in Mermaid — make it slide-ready and give me a share link.\n\nAgent (uses skill):\n $ bd beautify flow.mmd --theme modern --out flow.svg\n $ bd share flow.mmd --title \"Service flow\"\n → https://www.beauty-diagram.com/s/abc123\n```\n\n```\nYou: Draw me a deploy pipeline diagram and beautify it.\n\nAgent (uses skill, Pro plan):\n $ bd ai generate \"deploy pipeline with build, test, staging, prod\" --out deploy.mmd\n $ bd beautify deploy.mmd --out deploy.svg\n → wrote deploy.mmd (editable) + deploy.svg (presentation)\n```\n\n```\nYou: Add this architecture diagram to my README as an embedded image.\n\nAgent (uses skill, Pro/Premium plan):\n $ bd embed-url ./architecture.mmd --share\n → https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg\n Injects into README: ![Architecture](https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg)\n```\n\nSee `examples/` for runnable diagram sources and `scripts/` for shell\nwrappers you can drop into a repo.\n\n## Files\n\n```\nbeauty-diagram-skill/\n├── SKILL.md # agent-facing instructions\n├── examples/ # sample Mermaid sources\n│ ├── flowchart.mmd\n│ └── sequence.mmd\n└── scripts/ # copy-pasteable shell wrappers\n ├── beautify.sh\n ├── export.sh\n └── ai-generate.sh # prompt → .mmd → .svg\n```\n\n## Links\n\n- Site: \n- CLI on npm: \n- API keys: \n\n## License\n\nMIT-0 (per ClawHub publishing terms).\n\nFile v1.5.0:_meta.json\n\n{\n \"ownerId\": \"kn727br5w8gyw9x95hd4cs66ss85nwcg\",\n \"slug\": \"beauty-diagram\",\n \"version\": \"1.5.0\",\n \"publishedAt\": 1779170205965\n}\n\nFile v1.5.0:package.json\n\n{\n \"name\": \"@beauty-diagram/skill\",\n \"version\": \"1.5.0\",\n \"private\": true,\n \"description\": \"Beauty Diagram agent skill — instructs LLM agents how to call the bd CLI for presentation-ready diagrams.\",\n \"files\": [\n \"SKILL.md\",\n \"README.md\",\n \"examples\",\n \"scripts\"\n ],\n \"publishConfig\": {\n \"access\": \"public\"\n },\n \"dependencies\": {\n \"clawhub\": \"^0.9.0\"\n }\n}\n\nArchive v1.4.0: 7 files, 10018 bytes\n\nFiles: package.json (386b), README.md (3475b), scripts/ai-generate.sh (805b), scripts/beautify.sh (361b), scripts/export.sh (300b), SKILL.md (14915b), _meta.json (133b)\n\nFile v1.4.0:SKILL.md\n\n---\nname: beauty-diagram\ndescription: 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 SVG of this architecture\"), wants AI to generate a diagram from a text description, wants a public share link for a diagram, wants to render every diagram file in a folder, or wants to render Mermaid / PlantUML fenced code blocks inside a Markdown file (README, docs) into images. This skill teaches you to call the Beauty Diagram CLI (`bd`) — never to hand-author SVG when a source diagram exists.\nversion: 1.4.0\nmetadata:\n openclaw:\n requires:\n bins:\n - node\n - npx\n---\n\n# Beauty Diagram skill\n\nBeauty Diagram beautifies Mermaid / PlantUML diagrams into\npresentation-ready SVG or PNG. It runs as a public API; this skill\ndelegates to the `bd` CLI (npm package `@beauty-diagram/cli`) so you\nkeep zero state in the agent. (draw.io / SVG import is editor-only —\nnot exposed through `/v1/*`.)\n\n## When to use\n\n- The user asks for a **polished, professional, slide-ready** version of a\n diagram source they already have or you can generate.\n- The user wants you to **render Mermaid or PlantUML** from a model-generated\n source string.\n- The user wants the server to **generate a diagram from a text description**\n (\"draw me a signup flow\", \"diagram our deploy pipeline\") — use\n `bd ai generate` for this; it returns Mermaid source you then beautify.\n- The user wants to **share a diagram link** (e.g. paste into Slack / a doc).\n- The user has Mermaid in a repo (README, ADR, RFC) and wants to **export\n SVGs** alongside.\n- The user has a **directory full of diagram source files** and wants every one\n of them rendered (e.g. \"render all the .mmd files in docs/diagrams\"). Use\n `bd batch`.\n- The user wants their **Markdown files (README, ADR, blog post) to display the\n diagrams inline** on GitHub / their static site, not just show the source\n code block. Use `bd extract` — by default it injects inline embed URLs\n (no API calls, no files, anonymous-watermarked) after each fenced block.\n Pass `--assets-dir ./img` to write local SVG files instead (sidecar mode,\n Pro/Premium get watermark-free output). GitHub strips raw inline ``, so\n either mode's `![](...)` reference is the correct embed strategy.\n\n## When NOT to use\n\n- The user only wants the Mermaid source itself, not an export.\n- The user wants pixel-precise control over the SVG markup (Beauty Diagram\n rewrites layout for presentation; it does not preserve raw Mermaid output).\n- The user wants the AI to \"change the colors / theme / font / layout\" of an\n existing diagram. `bd ai generate` only does **text → diagram**; visual\n styling is controlled by `--theme` on `bd beautify`, not by the AI.\n- The user is in an offline environment with no network and no CLI install.\n\n## Required tool\n\nThe `bd` binary from `@beauty-diagram/cli`:\n\n```bash\nnpx @beauty-diagram/cli help\n# or, after install:\nbd help\n```\n\nIf the user has not installed it, prefer `npx` over a global install — it\nrespects their package manager and avoids polluting `PATH`.\n\n## Workflow\n\n1. **Identify or generate the source diagram.**\n - If the user has a `.mmd` / `.puml` file, use it.\n - If the user describes the diagram in words and is on a paid plan, use\n `bd ai generate \"\" --out .mmd` — the server returns\n Mermaid source, which you can then beautify. Always write the source\n to a file so the user can edit it; the first AI draft rarely lands.\n - If the user describes the diagram and is **not** on a paid plan (or\n prefers not to pay), write Mermaid source yourself (you are good at\n this), save it to a file, then beautify.\n - draw.io and free-form SVG imports are not accepted by `/v1/*`. If\n the user has those, ask them to convert via the web editor first.\n\n2. **Decide on output type.**\n - Need an SVG file: `bd beautify --out .svg`\n - Need a download URL or to track quota: `bd export --out .svg`\n - Need a shareable link: `bd share --title \"...\"`\n\n3. **Run the command.** Always write to a file (`--out`) rather than letting\n the SVG flood the terminal / chat. AI generation can also pipe directly\n into beautify: `bd ai generate \"...\" | bd beautify - --out flow.svg`.\n\n4. **Verify the result exists** before reporting success. If the command\n failed, surface the error code (e.g. `quota_exhausted`, `not_authenticated`,\n `parse_failed`, `prompt_injection`) — those are actionable for the user.\n\n5. **Preserve the source.** Never replace the original Mermaid / PlantUML file\n with the generated SVG — keep them side by side. For AI-generated diagrams,\n keep the `.mmd` file too: it is the editable artifact, the SVG is not.\n\n## Auth\n\n- **Demo (anonymous):** zero setup. Watermarked SVG/PNG. Limits per IP:\n 20 `/v1/beautify` requests / minute, **1 `/v1/export` per 24h** (trial\n budget — enough for an agent to verify the toolchain end-to-end before\n registering). `/v1/share`, `/v1/usage`, and **`bd ai generate` always\n require auth** — anonymous AI calls are rejected before any model\n invocation.\n- **Authenticated:** the user runs `bd auth login` once with a key from\n [`/account/api-keys`](https://www.beauty-diagram.com/account/api-keys).\n Required for `bd share`, `bd ai generate`, unwatermarked output, and\n repeated exports. `bd ai generate` additionally requires a Pro or\n Premium plan and an API key with the `ai:write` scope.\n\nIf the user hits a `not_authenticated`, `plan_not_allowed`, or\n`quota_exhausted` error, point them at `/account/api-keys` (PAT creation)\nor pricing — don't silently retry. Anonymous error bodies include a\n`hints` block with absolute `signUpUrl` / `signInUrl` / `apiDocsUrl`,\nwhich is the canonical place to surface to the user.\n\n## Commands cheat sheet\n\n```bash\n# Render a Mermaid file\nbd beautify docs/architecture.mmd --theme modern --out docs/architecture.svg\n\n# Same but treat output as a downloadable export (consumes export quota)\nbd export docs/architecture.mmd --out docs/architecture.svg\n\n# PNG export. --quality standard works for everyone; high needs pro, max needs premium.\n# Higher tiers than the plan cap are silently clamped (X-BD-Scale-Clamped).\nbd export docs/architecture.mmd --format png --quality high --out docs/architecture.png\n\n# PlantUML works the same way; .puml / .plantuml / .pu auto-detected,\n# otherwise pass --source-format plantuml.\nbd export docs/architecture.puml --out docs/architecture.svg\n\n# Create a public share link (returns absolute https://www.beauty-diagram.com/s/... URL)\nbd share docs/architecture.mmd --title \"Service architecture\"\n# → prints the URL on stdout\n\n# Get an embeddable -friendly URL for a diagram source.\n# Default: anonymous inline URL (always watermarked) + a hint about --share.\nbd embed-url docs/architecture.mmd --theme atlas\n# One-shot saved share embed (clean output for pro/premium owners).\n# Saves the diagram via /v1/share AND prints the embed URL in one step.\nbd embed-url docs/architecture.mmd --share\n# → prints https://api.beauty-diagram.com/v1/share/.svg\n\n# AI: generate a diagram from a text prompt. Output is Mermaid source —\n# always write to a file so the user can iterate. Paid-only.\nbd ai generate \"user signup with email verification\" --out docs/signup.mmd\n\n# Optional shape hint when the prompt is ambiguous about diagram type.\nbd ai generate \"request lifecycle\" --hint sequence --out docs/lifecycle.mmd\n\n# One-shot pipeline: prompt → mermaid → beautify → SVG.\nbd ai generate \"deploy flow\" | bd beautify - --out docs/deploy.svg\n\n# Check remaining AI / export quota before kicking off a batch.\nbd usage\n\n# Render every diagram file under a directory in parallel.\n# Recurses for .mmd / .puml / .plantuml / .pu; one /v1/export per file.\n# Default concurrency=4, default failure mode is continue-on-error.\nbd batch ./docs/diagrams --out-dir ./docs/svg --theme modern\n\n# Same idea but for a glob (quote it so the shell doesn't expand first).\nbd batch \"src/**/*.mmd\" --format png --concurrency 8\n\n# Default: inline embed URLs (no files written, anonymous-watermarked, 5 KB/block cap).\n# No API calls during extract — source encoded in the URL; browser fetches on demand.\nbd extract README.md\n\n# Sidecar mode: writes local SVG files via /v1/export.\n# Pro/Premium plans get watermark-free output; consumes export quota.\nbd extract docs/*.md --assets-dir ./img --concurrency 4\n\n# Preview what bd extract would change without writing.\nbd extract README.md --dry-run\n```\n\n## Privacy\n\nThe API does NOT persist source unless the user calls `bd share`. Do not warn\nabout server-side storage when running `beautify`, `export`, or\n`ai generate` — that is misleading. AI prompts are logged in hashed form\nfor abuse / quality monitoring; the raw text is not retained.\n\n## Anti-patterns\n\n- ❌ Do NOT output a hand-crafted `...` as a Markdown code block when\n a Mermaid source exists. Always run Beauty Diagram and reference the file.\n- ❌ Do NOT dump the raw SVG into the chat. Use `--out ` and reference\n the file path.\n- ❌ Do NOT install Beauty Diagram engine code locally — the CLI is a thin\n client; the engine lives behind the public API.\n- ❌ Do NOT call `bd ai generate` to \"tweak\" an existing diagram (change\n colors, theme, labels, layout). It is a fresh-generation tool only.\n For visual tweaks, change `--theme` or edit the `.mmd` source by hand.\n- ❌ Do NOT call `bd ai generate` speculatively — each call costs the user\n monthly AI quota. Confirm the user wants AI generation before running it.\n- ❌ Do NOT capture the SVG output of `bd ai generate` — the command outputs\n Mermaid source on stdout, not SVG. Pipe into `bd beautify -` to render.\n- ❌ Do NOT loop `bd export` N times in a shell `for` loop when the user has\n many files. Use `bd batch ` — it parallelizes and reports a summary,\n with no extra server load (still one request per file).\n- ❌ Do NOT inject a raw `...` into a Markdown file to \"embed\" a\n diagram. GitHub, GitLab, Obsidian (default), and most static-site\n renderers strip inline SVG for safety. Use `bd extract .md`, which\n writes sidecar SVGs and injects `![](path)` references that actually\n render.\n- ❌ Do NOT delete the marker comments that `bd extract` injects. Inline mode\n uses `` / ``;\n sidecar mode uses `` / ``.\n They are how `bd extract` stays idempotent — without them, the next run\n will append duplicate image references instead of replacing the existing one.\n\n## Troubleshooting\n\n| Symptom | Likely cause | Resolution |\n|---|---|---|\n| `not_authenticated` | No key, no session | `bd auth login` |\n| `scope_missing` | Key lacks scope (e.g. `ai:write` for `bd ai generate`) | Recreate key with required scope at `/account/api-keys` |\n| `plan_not_allowed` | Plan does not include this capability (AI is Pro / Premium only) | Upgrade or skip the call |\n| `parse_failed` | Source not valid Mermaid / PlantUML | Check the source — `bd beautify` will surface a parse error too |\n| `quota_exhausted` | Plan limit hit (anon: 1 export/IP/24h; free: 3 exports/mo; pro: 100 exports + 100 AI gens/mo; premium: ∞ exports + 500 AI gens/mo) | Sign in, wait for reset, or upgrade — `hints` in the response body has the URLs |\n| `rate_limited` | Anonymous IP bucket full (20 `/v1/beautify` requests / minute) or AI per-key bucket (30 `/min`) | Sign in or wait |\n| `source_too_large` | Source > 100 KB | Split the diagram |\n| `output_too_large` | PNG raster exceeds 8192 px | Lower `--quality` or simplify |\n| `prompt_injection` | AI prompt looked like an injection attempt | Rephrase as a plain diagram description (\"a flowchart of …\") |\n| `instruction_rejected` | AI judged the prompt was not about a diagram | Rephrase to describe a concrete diagram. Quota was NOT consumed |\n| `parse_failed_after_retry` | AI output was unparseable Mermaid even after one retry | Rephrase, or write Mermaid by hand. Quota was NOT consumed |\n| `safety_blocked` | Provider safety filter rejected the request | Rephrase the prompt |\n| `upstream_timeout` / `upstream_error` | AI provider was slow or failed | Retry after a moment |\n\n## Triggering on embed requests\n\nWhen the user asks for \"a GitHub README diagram\", \"embed in Notion\", \"embed in my blog post\", \"an `` of this diagram\", or \"a URL that renders my diagram\", route to the embed flow rather than emitting raw mermaid:\n\n1. If the diagram is unsaved, run `bd share ` to save it.\n2. Construct the embed URL: `https://api.beauty-diagram.com/v1/share/.svg`.\n3. For one-off / quick embeds without saving, use `bd embed-url ` and recommend the inline URL (note that anonymous embeds carry a \"Powered by Beauty Diagram\" watermark).\n\n**Easier one-shot path:** `bd embed-url --share` saves the diagram AND prints the embed URL in one command — no need to run `bd share` separately and then construct the URL by hand. Prefer this when the user wants a clean share embed.\n\n**Style fidelity:** Per-node colors, edge presets, and font overrides set by the user in the web canvas editor ARE faithfully rendered in share-mode embeds (`/v1/share/.svg`). Encourage a \"tweak in editor → save → embed\" workflow when the user wants brand colors or custom styling — they do not need to re-run `bd embed-url` after editing in the web UI, just re-save the diagram there.\n\n**Propagation timing:** Saved diagram edits show up in direct `` embeds within ~5 minutes (browser ETag revalidation + 5-min CDN edge TTL). GitHub README embeds may lag a few hours due to GitHub's image proxy cache — that is a GitHub-side cache, not something we can purge.\n\n**Animations:** Animations do NOT play in ``-loaded SVGs in any browser. Do not tell the user their animated diagram will appear animated in a README or Notion embed.\n\n## Example\n\nUser: \"Add a beautified version of this mermaid block to my README.\"\n\nAgent steps:\n1. Use the one-step path: `bd embed-url ./architecture.mmd --share`\n → saves the diagram and prints the embed URL, e.g.\n `https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg`\n2. Replace the raw mermaid block in README with:\n `![Architecture](https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg)`\n3. (Optional) Confirm with the user that watermark behavior matches their plan\n (free owner → watermarked; pro/premium owner → clean).\n\n## Examples\n\nSee `examples/` for runnable sources you can adapt:\n\n- `examples/flowchart.mmd`\n- `examples/sequence.mmd`\n\nAnd `scripts/` for shell wrappers you can copy into the user's repo:\n\n- `scripts/beautify.sh`\n- `scripts/export.sh`\n- `scripts/ai-generate.sh` — prompt → `.mmd` source → `.svg` render\n\nFile v1.4.0:README.md\n\n# Beauty Diagram skill\n\nTurn Mermaid / PlantUML source into presentation-ready SVG or PNG — straight\nfrom your agent. This skill teaches Claude (or any compatible agent) to call\nthe [`bd` CLI](https://www.npmjs.com/package/@beauty-diagram/cli) instead of\nhand-authoring SVG, so you get consistent, slide-quality diagrams without\nleaving the conversation.\n\n## What it does\n\n- Beautifies existing Mermaid / PlantUML files into polished SVG/PNG\n- Renders model-generated diagram source on demand\n- **Generates a diagram from a text prompt** via `bd ai generate`\n (Pro / Premium plans only)\n- Produces shareable `https://www.beauty-diagram.com/s/...` links\n- **Generates direct embed URLs** for README / Notion / blog use: runs\n `bd share` and returns `https://api.beauty-diagram.com/v1/share/.svg`\n rather than emitting raw Mermaid — the URL works as a plain ``\n anywhere that renders images. Anonymous (watermarked) embeds are also\n available via `bd embed-url` with no sign-in required.\n- Surfaces actionable error codes (`quota_exhausted`, `parse_failed`,\n `prompt_injection`, …) instead of silently retrying\n\n## Requirements\n\n- **Node.js** (for `npx @beauty-diagram/cli`); no global install needed\n- **Optional**: a Beauty Diagram API key for unwatermarked output, share\n links, and higher quotas — anonymous demo mode works out of the box\n (1 export per IP per 24h)\n- **For AI generation**: an API key with the `ai:write` scope on a Pro\n or Premium plan. Anonymous and free plans cannot call `bd ai generate`.\n\nGet a key at .\n\n## Triggering\n\nThe skill activates when a user asks for things like:\n\n- \"beautify this flowchart\"\n- \"make this Mermaid diagram look like a deck slide\"\n- \"give me an SVG of this architecture\"\n- \"draw me a diagram of the signup flow\"\n- \"share this diagram as a link\"\n\n## Example\n\n```\nYou: Here's our service flow in Mermaid — make it slide-ready and give me a share link.\n\nAgent (uses skill):\n $ bd beautify flow.mmd --theme modern --out flow.svg\n $ bd share flow.mmd --title \"Service flow\"\n → https://www.beauty-diagram.com/s/abc123\n```\n\n```\nYou: Draw me a deploy pipeline diagram and beautify it.\n\nAgent (uses skill, Pro plan):\n $ bd ai generate \"deploy pipeline with build, test, staging, prod\" --out deploy.mmd\n $ bd beautify deploy.mmd --out deploy.svg\n → wrote deploy.mmd (editable) + deploy.svg (presentation)\n```\n\n```\nYou: Add this architecture diagram to my README as an embedded image.\n\nAgent (uses skill, Pro/Premium plan):\n $ bd embed-url ./architecture.mmd --share\n → https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg\n Injects into README: ![Architecture](https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg)\n```\n\nSee `examples/` for runnable diagram sources and `scripts/` for shell\nwrappers you can drop into a repo.\n\n## Files\n\n```\nbeauty-diagram-skill/\n├── SKILL.md # agent-facing instructions\n├── examples/ # sample Mermaid sources\n│ ├── flowchart.mmd\n│ └── sequence.mmd\n└── scripts/ # copy-pasteable shell wrappers\n ├── beautify.sh\n ├── export.sh\n └── ai-generate.sh # prompt → .mmd → .svg\n```\n\n## Links\n\n- Site: \n- CLI on npm: \n- API keys: \n\n## License\n\nMIT-0 (per ClawHub publishing terms).\n\nFile v1.4.0:_meta.json\n\n{\n \"ownerId\": \"kn727br5w8gyw9x95hd4cs66ss85nwcg\",\n \"slug\": \"beauty-diagram\",\n \"version\": \"1.4.0\",\n \"publishedAt\": 1777963093025\n}\n\nFile v1.4.0:package.json\n\n{\n \"name\": \"@beauty-diagram/skill\",\n \"version\": \"1.4.0\",\n \"private\": true,\n \"description\": \"Beauty Diagram agent skill — instructs LLM agents how to call the bd CLI for presentation-ready diagrams.\",\n \"files\": [\n \"SKILL.md\",\n \"README.md\",\n \"examples\",\n \"scripts\"\n ],\n \"publishConfig\": {\n \"access\": \"public\"\n },\n \"dependencies\": {\n \"clawhub\": \"^0.9.0\"\n }\n}\n\nArchive v1.3.0: 7 files, 8593 bytes\n\nFiles: package.json (386b), README.md (2801b), scripts/ai-generate.sh (805b), scripts/beautify.sh (361b), scripts/export.sh (300b), SKILL.md (11880b), _meta.json (133b)\n\nFile v1.3.0:SKILL.md\n\n---\nname: beauty-diagram\ndescription: 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 SVG of this architecture\"), wants AI to generate a diagram from a text description, wants a public share link for a diagram, wants to render every diagram file in a folder, or wants to render Mermaid / PlantUML fenced code blocks inside a Markdown file (README, docs) into images. This skill teaches you to call the Beauty Diagram CLI (`bd`) — never to hand-author SVG when a source diagram exists.\nversion: 1.3.0\nmetadata:\n openclaw:\n requires:\n bins:\n - node\n - npx\n---\n\n# Beauty Diagram skill\n\nBeauty Diagram beautifies Mermaid / PlantUML diagrams into\npresentation-ready SVG or PNG. It runs as a public API; this skill\ndelegates to the `bd` CLI (npm package `@beauty-diagram/cli`) so you\nkeep zero state in the agent. (draw.io / SVG import is editor-only —\nnot exposed through `/v1/*`.)\n\n## When to use\n\n- The user asks for a **polished, professional, slide-ready** version of a\n diagram source they already have or you can generate.\n- The user wants you to **render Mermaid or PlantUML** from a model-generated\n source string.\n- The user wants the server to **generate a diagram from a text description**\n (\"draw me a signup flow\", \"diagram our deploy pipeline\") — use\n `bd ai generate` for this; it returns Mermaid source you then beautify.\n- The user wants to **share a diagram link** (e.g. paste into Slack / a doc).\n- The user has Mermaid in a repo (README, ADR, RFC) and wants to **export\n SVGs** alongside.\n- The user has a **directory full of diagram source files** and wants every one\n of them rendered (e.g. \"render all the .mmd files in docs/diagrams\"). Use\n `bd batch`.\n- The user wants their **Markdown files (README, ADR, blog post) to display the\n diagrams inline** on GitHub / their static site, not just show the source\n code block. Use `bd extract` — it renders each fenced block to a sidecar\n SVG and injects an image reference. GitHub strips raw inline ``, so\n this is the only embed that survives.\n\n## When NOT to use\n\n- The user only wants the Mermaid source itself, not an export.\n- The user wants pixel-precise control over the SVG markup (Beauty Diagram\n rewrites layout for presentation; it does not preserve raw Mermaid output).\n- The user wants the AI to \"change the colors / theme / font / layout\" of an\n existing diagram. `bd ai generate` only does **text → diagram**; visual\n styling is controlled by `--theme` on `bd beautify`, not by the AI.\n- The user is in an offline environment with no network and no CLI install.\n\n## Required tool\n\nThe `bd` binary from `@beauty-diagram/cli`:\n\n```bash\nnpx @beauty-diagram/cli help\n# or, after install:\nbd help\n```\n\nIf the user has not installed it, prefer `npx` over a global install — it\nrespects their package manager and avoids polluting `PATH`.\n\n## Workflow\n\n1. **Identify or generate the source diagram.**\n - If the user has a `.mmd` / `.puml` file, use it.\n - If the user describes the diagram in words and is on a paid plan, use\n `bd ai generate \"\" --out .mmd` — the server returns\n Mermaid source, which you can then beautify. Always write the source\n to a file so the user can edit it; the first AI draft rarely lands.\n - If the user describes the diagram and is **not** on a paid plan (or\n prefers not to pay), write Mermaid source yourself (you are good at\n this), save it to a file, then beautify.\n - draw.io and free-form SVG imports are not accepted by `/v1/*`. If\n the user has those, ask them to convert via the web editor first.\n\n2. **Decide on output type.**\n - Need an SVG file: `bd beautify --out .svg`\n - Need a download URL or to track quota: `bd export --out .svg`\n - Need a shareable link: `bd share --title \"...\"`\n\n3. **Run the command.** Always write to a file (`--out`) rather than letting\n the SVG flood the terminal / chat. AI generation can also pipe directly\n into beautify: `bd ai generate \"...\" | bd beautify - --out flow.svg`.\n\n4. **Verify the result exists** before reporting success. If the command\n failed, surface the error code (e.g. `quota_exhausted`, `not_authenticated`,\n `parse_failed`, `prompt_injection`) — those are actionable for the user.\n\n5. **Preserve the source.** Never replace the original Mermaid / PlantUML file\n with the generated SVG — keep them side by side. For AI-generated diagrams,\n keep the `.mmd` file too: it is the editable artifact, the SVG is not.\n\n## Auth\n\n- **Demo (anonymous):** zero setup. Watermarked SVG/PNG. Limits per IP:\n 20 `/v1/beautify` requests / minute, **1 `/v1/export` per 24h** (trial\n budget — enough for an agent to verify the toolchain end-to-end before\n registering). `/v1/share`, `/v1/usage`, and **`bd ai generate` always\n require auth** — anonymous AI calls are rejected before any model\n invocation.\n- **Authenticated:** the user runs `bd auth login` once with a key from\n [`/account/api-keys`](https://www.beauty-diagram.com/account/api-keys).\n Required for `bd share`, `bd ai generate`, unwatermarked output, and\n repeated exports. `bd ai generate` additionally requires a Pro or\n Premium plan and an API key with the `ai:write` scope.\n\nIf the user hits a `not_authenticated`, `plan_not_allowed`, or\n`quota_exhausted` error, point them at `/account/api-keys` (PAT creation)\nor pricing — don't silently retry. Anonymous error bodies include a\n`hints` block with absolute `signUpUrl` / `signInUrl` / `apiDocsUrl`,\nwhich is the canonical place to surface to the user.\n\n## Commands cheat sheet\n\n```bash\n# Render a Mermaid file\nbd beautify docs/architecture.mmd --theme modern --out docs/architecture.svg\n\n# Same but treat output as a downloadable export (consumes export quota)\nbd export docs/architecture.mmd --out docs/architecture.svg\n\n# PNG export. --quality standard works for everyone; high needs pro, max needs premium.\n# Higher tiers than the plan cap are silently clamped (X-BD-Scale-Clamped).\nbd export docs/architecture.mmd --format png --quality high --out docs/architecture.png\n\n# PlantUML works the same way; .puml / .plantuml / .pu auto-detected,\n# otherwise pass --source-format plantuml.\nbd export docs/architecture.puml --out docs/architecture.svg\n\n# Create a public share link (returns absolute https://www.beauty-diagram.com/s/... URL)\nbd share docs/architecture.mmd --title \"Service architecture\"\n# → prints the URL on stdout\n\n# AI: generate a diagram from a text prompt. Output is Mermaid source —\n# always write to a file so the user can iterate. Paid-only.\nbd ai generate \"user signup with email verification\" --out docs/signup.mmd\n\n# Optional shape hint when the prompt is ambiguous about diagram type.\nbd ai generate \"request lifecycle\" --hint sequence --out docs/lifecycle.mmd\n\n# One-shot pipeline: prompt → mermaid → beautify → SVG.\nbd ai generate \"deploy flow\" | bd beautify - --out docs/deploy.svg\n\n# Check remaining AI / export quota before kicking off a batch.\nbd usage\n\n# Render every diagram file under a directory in parallel.\n# Recurses for .mmd / .puml / .plantuml / .pu; one /v1/export per file.\n# Default concurrency=4, default failure mode is continue-on-error.\nbd batch ./docs/diagrams --out-dir ./docs/svg --theme modern\n\n# Same idea but for a glob (quote it so the shell doesn't expand first).\nbd batch \"src/**/*.mmd\" --format png --concurrency 8\n\n# Render every ```mermaid / ```plantuml fenced block inside a Markdown file\n# to a sidecar SVG and inject an image reference right below the fence.\n# Idempotent: re-running skips unchanged blocks (content-hashed filenames).\nbd extract README.md\nbd extract docs/*.md --assets-dir ./img --concurrency 4\n\n# Preview what bd extract would change without writing.\nbd extract README.md --dry-run\n```\n\n## Privacy\n\nThe API does NOT persist source unless the user calls `bd share`. Do not warn\nabout server-side storage when running `beautify`, `export`, or\n`ai generate` — that is misleading. AI prompts are logged in hashed form\nfor abuse / quality monitoring; the raw text is not retained.\n\n## Anti-patterns\n\n- ❌ Do NOT output a hand-crafted `...` as a Markdown code block when\n a Mermaid source exists. Always run Beauty Diagram and reference the file.\n- ❌ Do NOT dump the raw SVG into the chat. Use `--out ` and reference\n the file path.\n- ❌ Do NOT install Beauty Diagram engine code locally — the CLI is a thin\n client; the engine lives behind the public API.\n- ❌ Do NOT call `bd ai generate` to \"tweak\" an existing diagram (change\n colors, theme, labels, layout). It is a fresh-generation tool only.\n For visual tweaks, change `--theme` or edit the `.mmd` source by hand.\n- ❌ Do NOT call `bd ai generate` speculatively — each call costs the user\n monthly AI quota. Confirm the user wants AI generation before running it.\n- ❌ Do NOT capture the SVG output of `bd ai generate` — the command outputs\n Mermaid source on stdout, not SVG. Pipe into `bd beautify -` to render.\n- ❌ Do NOT loop `bd export` N times in a shell `for` loop when the user has\n many files. Use `bd batch ` — it parallelizes and reports a summary,\n with no extra server load (still one request per file).\n- ❌ Do NOT inject a raw `...` into a Markdown file to \"embed\" a\n diagram. GitHub, GitLab, Obsidian (default), and most static-site\n renderers strip inline SVG for safety. Use `bd extract .md`, which\n writes sidecar SVGs and injects `![](path)` references that actually\n render.\n- ❌ Do NOT delete the marker comments (`` /\n ``) that `bd extract` injects. They are how it stays\n idempotent — without them, the next run will append duplicate image\n references instead of replacing the existing one.\n\n## Troubleshooting\n\n| Symptom | Likely cause | Resolution |\n|---|---|---|\n| `not_authenticated` | No key, no session | `bd auth login` |\n| `scope_missing` | Key lacks scope (e.g. `ai:write` for `bd ai generate`) | Recreate key with required scope at `/account/api-keys` |\n| `plan_not_allowed` | Plan does not include this capability (AI is Pro / Premium only) | Upgrade or skip the call |\n| `parse_failed` | Source not valid Mermaid / PlantUML | Check the source — `bd beautify` will surface a parse error too |\n| `quota_exhausted` | Plan limit hit (anon: 1 export/IP/24h; free: 3 exports/mo; pro: 100 exports + 100 AI gens/mo; premium: ∞ exports + 500 AI gens/mo) | Sign in, wait for reset, or upgrade — `hints` in the response body has the URLs |\n| `rate_limited` | Anonymous IP bucket full (20 `/v1/beautify` requests / minute) or AI per-key bucket (30 `/min`) | Sign in or wait |\n| `source_too_large` | Source > 100 KB | Split the diagram |\n| `output_too_large` | PNG raster exceeds 8192 px | Lower `--quality` or simplify |\n| `prompt_injection` | AI prompt looked like an injection attempt | Rephrase as a plain diagram description (\"a flowchart of …\") |\n| `instruction_rejected` | AI judged the prompt was not about a diagram | Rephrase to describe a concrete diagram. Quota was NOT consumed |\n| `parse_failed_after_retry` | AI output was unparseable Mermaid even after one retry | Rephrase, or write Mermaid by hand. Quota was NOT consumed |\n| `safety_blocked` | Provider safety filter rejected the request | Rephrase the prompt |\n| `upstream_timeout` / `upstream_error` | AI provider was slow or failed | Retry after a moment |\n\n## Examples\n\nSee `examples/` for runnable sources you can adapt:\n\n- `examples/flowchart.mmd`\n- `examples/sequence.mmd`\n\nAnd `scripts/` for shell wrappers you can copy into the user's repo:\n\n- `scripts/beautify.sh`\n- `scripts/export.sh`\n- `scripts/ai-generate.sh` — prompt → `.mmd` source → `.svg` render\n\nFile v1.3.0:README.md\n\n# Beauty Diagram skill\n\nTurn Mermaid / PlantUML source into presentation-ready SVG or PNG — straight\nfrom your agent. This skill teaches Claude (or any compatible agent) to call\nthe [`bd` CLI](https://www.npmjs.com/package/@beauty-diagram/cli) instead of\nhand-authoring SVG, so you get consistent, slide-quality diagrams without\nleaving the conversation.\n\n## What it does\n\n- Beautifies existing Mermaid / PlantUML files into polished SVG/PNG\n- Renders model-generated diagram source on demand\n- **Generates a diagram from a text prompt** via `bd ai generate`\n (Pro / Premium plans only)\n- Produces shareable `https://www.beauty-diagram.com/s/...` links\n- Surfaces actionable error codes (`quota_exhausted`, `parse_failed`,\n `prompt_injection`, …) instead of silently retrying\n\n## Requirements\n\n- **Node.js** (for `npx @beauty-diagram/cli`); no global install needed\n- **Optional**: a Beauty Diagram API key for unwatermarked output, share\n links, and higher quotas — anonymous demo mode works out of the box\n (1 export per IP per 24h)\n- **For AI generation**: an API key with the `ai:write` scope on a Pro\n or Premium plan. Anonymous and free plans cannot call `bd ai generate`.\n\nGet a key at .\n\n## Triggering\n\nThe skill activates when a user asks for things like:\n\n- \"beautify this flowchart\"\n- \"make this Mermaid diagram look like a deck slide\"\n- \"give me an SVG of this architecture\"\n- \"draw me a diagram of the signup flow\"\n- \"share this diagram as a link\"\n\n## Example\n\n```\nYou: Here's our service flow in Mermaid — make it slide-ready and give me a share link.\n\nAgent (uses skill):\n $ bd beautify flow.mmd --theme modern --out flow.svg\n $ bd share flow.mmd --title \"Service flow\"\n → https://www.beauty-diagram.com/s/abc123\n```\n\n```\nYou: Draw me a deploy pipeline diagram and beautify it.\n\nAgent (uses skill, Pro plan):\n $ bd ai generate \"deploy pipeline with build, test, staging, prod\" --out deploy.mmd\n $ bd beautify deploy.mmd --out deploy.svg\n → wrote deploy.mmd (editable) + deploy.svg (presentation)\n```\n\nSee `examples/` for runnable diagram sources and `scripts/` for shell\nwrappers you can drop into a repo.\n\n## Files\n\n```\nbeauty-diagram-skill/\n├── SKILL.md # agent-facing instructions\n├── examples/ # sample Mermaid sources\n│ ├── flowchart.mmd\n│ └── sequence.mmd\n└── scripts/ # copy-pasteable shell wrappers\n ├── beautify.sh\n ├── export.sh\n └── ai-generate.sh # prompt → .mmd → .svg\n```\n\n## Links\n\n- Site: \n- CLI on npm: B"},{"language":"text","snippet":"' bd:theme=classic\n' bd:bg=transparent\n@startuml\nA -> B\n@enduml"},{"language":"bash","snippet":"# Render a Mermaid file\nbd beautify docs/architecture.mmd --theme modern --out docs/architecture.svg\n\n# Same but treat output as a downloadable export (consumes export quota)\nbd export docs/architecture.mmd --out docs/architecture.svg\n\n# PNG export. --quality standard works for everyone; high needs pro, max needs premium.\n# Higher tiers than the plan cap are silently clamped (X-BD-Scale-Clamped).\nbd export docs/architecture.mmd --format png --quality high --out docs/architecture.png\n\n# PlantUML works the same way; .puml / .plantuml / .pu auto-detected,\n# otherwise pass --source-format plantuml.\nbd export docs/architecture.puml --out docs/architecture.svg\n\n# Create a public share link (returns absolute https://www.beauty-diagram.com/s/... URL)\nbd share docs/architecture.mmd --title \"Service architecture\"\n# → prints the URL on stdout\n\n# Get an embeddable -friendly URL for a diagram source.\n# Default: anonymous inline URL (always watermarked) + a hint about --share.\nbd embed-url docs/architecture.mmd --theme atlas\n# One-shot saved share embed (clean output for pro/premium owners).\n# Saves the diagram via /v1/share AND prints the embed URL in one step.\nbd embed-url docs/architecture.mmd --share\n# → prints https://api.beauty-diagram.com/v1/share/.svg\n\n# AI: generate a diagram from a text prompt. Output is Mermaid source —\n# always write to a file so the user can iterate. Paid-only.\nbd ai generate \"user signup with email verification\" --out docs/signup.mmd\n\n# Optional shape hint when the prompt is ambiguous about diagram type.\nbd ai generate \"request lifecycle\" --hint sequence --out docs/lifecycle.mmd\n\n# One-shot pipeline: prompt → mermaid → beautify → SVG.\nbd ai generate \"deploy flow\" | bd beautify - --out docs/deploy.svg\n\n# Check remaining AI / export quota before kicking off a batch.\nbd usage\n\n# Render every diagram file under a directory in parallel.\n# Recurses for .mmd / .puml / .plantuml / .pu; one /v1/export per file.\n# Default concurrency=4, default fa"},{"language":"text","snippet":"You: Here's our service flow in Mermaid — make it slide-ready and give me a share link.\n\nAgent (uses skill):\n $ bd beautify flow.mmd --theme modern --out flow.svg\n $ bd share flow.mmd --title \"Service flow\"\n → https://www.beauty-diagram.com/s/abc123"},{"language":"text","snippet":"You: Draw me a deploy pipeline diagram and beautify it.\n\nAgent (uses skill, Pro plan):\n $ bd ai generate \"deploy pipeline with build, test, staging, prod\" --out deploy.mmd\n $ bd beautify deploy.mmd --out deploy.svg\n → wrote deploy.mmd (editable) + deploy.svg (presentation)"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: beauty-diagram\ndescription: Use when the user asks for a sleek, modern Mermaid / PlantUML diagram (e.g. \"beautify this flowchart\", \"make this look like a deck slide\", \"produce an SVG of this architecture\"), wants AI to generate a diagram from a text description, wants a public share link for a diagram, wants to render every diagram file in a folder, or wants to render Mermaid / PlantUML fenced code blocks inside a Markdown file (README, docs) into images. This skill teaches you to call the Beauty Diagram CLI (`bd`) — never to hand-author SVG when a source diagram exists.\nversion: 1.7.0\nmetadata:\n openclaw:\n requires:\n bins:\n - node\n - npx\n---\n\n# Beauty Diagram skill\n\nBeauty Diagram beautifies Mermaid / PlantUML diagrams into\nsleek, modern SVG or PNG. It runs as a public API; this skill\ndelegates to the `bd` CLI (npm package `@beauty-diagram/cli`) so you\nkeep zero state in the agent. (draw.io / SVG import is editor-only —\nnot exposed through `/v1/*`.)\n\n## When to use\n\n- The user asks for a **polished, professional, slide-ready** version of a\n diagram source they already have or you can generate.\n- The user wants you to **render Mermaid or PlantUML** from a model-generated\n source string.\n- The user wants the server to **generate a diagram from a text description**\n (\"draw me a signup flow\", \"diagram our deploy pipeline\") — use\n `bd ai generate` for this; it returns Mermaid source you then beautify.\n- The user wants to **share a diagram link** (e.g. paste into Slack / a doc).\n- The user has Mermaid in a repo (README, ADR, RFC) and wants to **export\n SVGs** alongside.\n- The user has a **directory full of diagram source files** and wants every one\n of them rendered (e.g. \"render all the .mmd files in docs/diagrams\"). Use\n `bd batch`.\n- The user wants their **Markdown files (README, ADR, blog post) to display the\n diagrams inline** on GitHub / their static site, not just show the source\n code block. Use `bd extract` — three modes available:\n - **Default (inline)**: no flags. Injects `/v1/beautify.svg?source=...` URLs\n after each fence. No API calls during extract, no files written, no quota\n consumed. Always watermarked (anonymous endpoint).\n - **Share (`--share`)**: mints a `/v1/share/.svg` URL per unique fence.\n **Watermark-free for Pro/Premium**. Requires an API key. Each unique\n source consumes 1 share quota the first time; identical fences are\n deduplicated; per-owner local cache means re-runs cost zero quota.\n - **Sidecar (`--assets-dir ./img`)**: writes local SVG files via `/v1/export`.\n Watermark-free for Pro/Premium, consumes export quota.\n GitHub strips raw inline ``, so any of these modes' `![](...)`\n reference is the correct embed strategy.\n\n## When NOT to use\n\n- The user only wants the Mermaid source itself, not an export.\n- The user wants pixel-precise control over the SVG markup (Beauty Diagram\n rewrites layout for presentation; it does not preserve raw Mermai"},{"path":"README.md","content":"# Beauty Diagram skill\n\nTurn Mermaid / PlantUML source into sleek, modern SVG or PNG — straight\nfrom your agent. This skill teaches Claude (or any compatible agent) to call\nthe [`bd` CLI](https://www.npmjs.com/package/@beauty-diagram/cli) instead of\nhand-authoring SVG, so you get consistent, slide-quality diagrams without\nleaving the conversation.\n\n## What it does\n\n- Beautifies existing Mermaid / PlantUML files into polished SVG/PNG\n- Renders model-generated diagram source on demand\n- **Generates a diagram from a text prompt** via `bd ai generate`\n (Pro / Premium plans only)\n- Produces shareable `https://www.beauty-diagram.com/s/...` links\n- **Generates direct embed URLs** for README / Notion / blog use: runs\n `bd share` and returns `https://api.beauty-diagram.com/v1/share/.svg`\n rather than emitting raw Mermaid — the URL works as a plain ``\n anywhere that renders images. Anonymous (watermarked) embeds are also\n available via `bd embed-url` with no sign-in required.\n- Surfaces actionable error codes (`quota_exhausted`, `parse_failed`,\n `prompt_injection`, …) instead of silently retrying\n\n## Requirements\n\n- **Node.js** (for `npx @beauty-diagram/cli`); no global install needed\n- **Optional**: a Beauty Diagram API key for unwatermarked output, share\n links, and higher quotas — anonymous demo mode works out of the box\n (1 export per IP per 24h)\n- **For AI generation**: an API key with the `ai:write` scope on a Pro\n or Premium plan. Anonymous and free plans cannot call `bd ai generate`.\n\nGet a key at .\n\n## Triggering\n\nThe skill activates when a user asks for things like:\n\n- \"beautify this flowchart\"\n- \"make this Mermaid diagram look like a deck slide\"\n- \"give me an SVG of this architecture\"\n- \"draw me a diagram of the signup flow\"\n- \"share this diagram as a link\"\n\n## Example\n\n```\nYou: Here's our service flow in Mermaid — make it slide-ready and give me a share link.\n\nAgent (uses skill):\n $ bd beautify flow.mmd --theme modern --out flow.svg\n $ bd share flow.mmd --title \"Service flow\"\n → https://www.beauty-diagram.com/s/abc123\n```\n\n```\nYou: Draw me a deploy pipeline diagram and beautify it.\n\nAgent (uses skill, Pro plan):\n $ bd ai generate \"deploy pipeline with build, test, staging, prod\" --out deploy.mmd\n $ bd beautify deploy.mmd --out deploy.svg\n → wrote deploy.mmd (editable) + deploy.svg (presentation)\n```\n\n```\nYou: Add this architecture diagram to my README as an embedded image.\n\nAgent (uses skill, Pro/Premium plan):\n $ bd embed-url ./architecture.mmd --share\n → https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg\n Injects into README: ![Architecture](https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg)\n```\n\nSee `examples/` for runnable diagram sources and `scripts/` for shell\nwrappers you can drop into a repo.\n\n## Source-level directives\n\nBoth the `bd` CLI and the Obsidian plugin support `bd:KEY=VALUE` directives\nembedded at the **start of your diagram source** "},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn727br5w8gyw9x95hd4cs66ss85nwcg\",\n \"slug\": \"beauty-diagram\",\n \"version\": \"1.7.0\",\n \"publishedAt\": 1785834559687\n}"},{"path":"CHANGELOG.md","content":"# Changelog\n\nAll notable changes to the `beauty-diagram` skill are documented here.\n\n## [1.6.1] - 2026-06-16\n\n### Changed: `bd:bg` now documents the full `white` / `dark` / `transparent` set\n\n- The `bg` directive previously documented `transparent` as the only honoured value. It now documents the full set the CLI and API accept — `theme` (default), `white`, `dark` (the diagram's ink is hue-lifted so edges and labels stay legible), and `transparent` — so the skill suggests the right value. Unknown values fall back to `theme`."},{"path":"skill-card.md","content":"## Description:\n\nGuides agents to use the Beauty Diagram CLI to generate, beautify, export, share, and embed Mermaid or PlantUML diagrams as polished SVG or PNG outputs.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[levi840714](https://clawhub.ai/user/levi840714)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, technical writers, and agents use this skill to turn Mermaid or PlantUML source into presentation-ready diagram files, share links, or Markdown embeds. It also guides optional text-to-diagram generation through the Beauty Diagram CLI when the user has the required plan and API scope.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The scripts invoke an unpinned npm CLI, so behavior could change when `npx @beauty-diagram/cli` resolves a newer package.\n\nMitigation: Pin or lock the `@beauty-diagram/cli` version before use and review package updates before adopting them.\n\nRisk: Share and share-embed workflows can publish diagrams to public external URLs.\n\nMitigation: Ask for explicit approval before creating hosted URLs, and prefer local sidecar SVG output for private repositories or sensitive diagrams.\n\nRisk: Diagram sources or prompts are sent to Beauty Diagram when workflows call the public API.\n\nMitigation: Use the skill only with content suitable for Beauty Diagram processing and run the CLI with least privilege in workspaces that may contain secrets.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/levi840714/skills/beauty-diagram)\n- [Beauty Diagram site](https://www.beauty-diagram.com)\n- [Beauty Diagram CLI on npm](https://www.npmjs.com/package/@beauty-diagram/cli)\n- [Beauty Diagram API keys](https://www.beauty-diagram.com/account/api-keys)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with shell commands, Mermaid or PlantUML source, file paths, and generated SVG/PNG or share/embed URL references]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May produce local .mmd, .puml, .svg, or .png files and public Beauty Diagram share/embed URLs depending on the selected workflow.]\n\n## Skill Version(s):\n\n1.7.0 (source: ClawHub release, SKILL.md frontmatter, package.json; CHANGELOG top entry is 1.6.1)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1666,"uniquenessScore":42,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T07:09:11.055Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T07:09:11.055Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T10:48:41.106Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}