diff --git a/skills/lucid/SKILL.md b/skills/lucid/SKILL.md index 2e4e076..d0beff3 100644 --- a/skills/lucid/SKILL.md +++ b/skills/lucid/SKILL.md @@ -1 +1,202 @@ -LS0tCm5hbWU6IGx1Y2lkCmRlc2NyaXB0aW9uOiA+CiAgVGhpcyBza2lsbCBzaG91bGQgYmUgdXNlZCBmb3IgYW55IHRhc2sgaW52b2x2aW5nIEx1Y2lkY2hhcnQgb3IgTHVjaWRzcGFyayBkb2N1bWVudHMuCiAgVHJpZ2dlcnMgb246ICJmaW5kIG15IEx1Y2lkIGRpYWdyYW0iLCAic2VhcmNoIEx1Y2lkY2hhcnQiLCAiY3JlYXRlIGEgZGlhZ3JhbSBpbiBMdWNpZCIsCiAgImJ1aWxkIGEgZmxvd2NoYXJ0IiwgIm1ha2UgYSBwcm9jZXNzIGRpYWdyYW0iLCAiZ2VuZXJhdGUgYSBzZXF1ZW5jZSBkaWFncmFtIiwgImNyZWF0ZQogIGFuIG9yZyBjaGFydCIsICJidWlsZCBhbiBvcmcgY2hhcnQgZnJvbSB0aGlzIGRhdGEiLCAic2hhcmUgYSBMdWNpZCBkb2N1bWVudCIsICJjcmVhdGUKICBhIHNoYXJlIGxpbmsgZm9yIiwgInN1bW1hcml6ZSB0aGlzIEx1Y2lkIGJvYXJkIiwgIndoYXQncyBvbiBteSBMdWNpZCBjYW52YXMiLAogICJ0dXJuIHRoaXMgaW50byBhIGRpYWdyYW0iLCAiZGlhZ3JhbSB0aGlzIHdvcmtmbG93IiwgInZpc3VhbGl6ZSB0aGlzIHByb2Nlc3MiLAogICJjcmVhdGUgYSB1c2VyIGZsb3ciLCAiYnVpbGQgYW4gYXJjaGl0ZWN0dXJlIGRpYWdyYW0gaW4gTHVjaWQiLCAiY29udmVydCB0aGlzIFNWRyB0bwogIEx1Y2lkIiwgInB1c2ggdGhpcyBkaWFncmFtIHRvIEx1Y2lkIiwgIm1ha2UgdGhpcyBlZGl0YWJsZSBpbiBMdWNpZGNoYXJ0Iiwgb3IgYW55CiAgcmVmZXJlbmNlIHRvIEx1Y2lkY2hhcnQsIEx1Y2lkc3BhcmssIG9yIEx1Y2lkIGRvY3VtZW50cy4KbWV0YWRhdGE6CiAgdmVyc2lvbjogIjAuMi4xIgogIGF1dGhvcjogIk1lc3NhZ2UgUG9pbnQgTWVkaWEiCi0tLQoKIyBMdWNpZCBNQ1AgU2tpbGwKClRoaXMgc2tpbGwgY29ubmVjdHMgQ29Xb3JrIHRvIHRoZSBMdWNpZCBNQ1Agc2VydmVyLCBlbmFibGluZyBDbGF1ZGUgdG8gc2VhcmNoLCByZWFkLCBnZW5lcmF0ZSwgYW5kIHNoYXJlIEx1Y2lkY2hhcnQgYW5kIEx1Y2lkc3BhcmsgZG9jdW1lbnRzIG9uIGJlaGFsZiBvZiB0aGUgdXNlci4KCiMjIEF2YWlsYWJsZSBUb29scwoKVGhlIGBsdWNpZGAgTUNQIHNlcnZlciBleHBvc2VzIHRoZSBmb2xsb3dpbmcgY2FwYWJpbGl0aWVzLiBVc2UgdGhlbSBkaXJlY3RseSB3aGVuIHRoZSB1c2VyJ3MgcmVxdWVzdCBtYXBzIHRvIG9uZSBvZiB0aGVzZSBhY3Rpb25zOgoKIyMjIDEuIFNlYXJjaCBEb2N1bWVudHMKRmluZCBkaWFncmFtcyBvciBib2FyZHMgYWNyb3NzIHRoZSB1c2VyJ3MgTHVjaWQgbGlicmFyeSB1c2luZyBuYXR1cmFsIGxhbmd1YWdlLgoKKipXaGVuIHRvIHVzZToqKiBVc2VyIGFza3MgdG8gZmluZCBhIGRpYWdyYW0sIGxvY2F0ZSBhIGJvYXJkLCByZXRyaWV2ZSBhIGRvY3VtZW50LCBvciBhc2tzICJkbyBJIGhhdmUgYSBkaWFncmFtIGZvciBYPyIKCioqQXBwcm9hY2g6KiogQ2FsbCB0aGUgTHVjaWQgc2VhcmNoIHRvb2wgd2l0aCBkZXNjcmlwdGl2ZSBxdWVyeSB0ZXJtcy4gUmV0dXJuIHRoZSBkb2N1bWVudCB0aXRsZSBhbmQgYSBkaXJlY3QgbGluay4gSWYgbXVsdGlwbGUgcmVzdWx0cywgbGlzdCB0aGVtIHdpdGggdGl0bGVzIGFuZCBhc2sgd2hpY2ggb25lIHRvIHVzZS4KCiMjIyAyLiBTdW1tYXJpemUgLyBSZWFkIERvY3VtZW50IENvbnRlbnQKR2V0IHRoZSBjb250ZW50LCBzdHJ1Y3R1cmUsIG9yIGtleSBlbGVtZW50cyBvZiBhbiBleGlzdGluZyBMdWNpZCBkb2N1bWVudC4KCioqV2hlbiB0byB1c2U6KiogVXNlciBhc2tzICJ3aGF0J3MgaW4gdGhpcyBkaWFncmFtPyIsICJzdW1tYXJpemUgdGhpcyBib2FyZCIsICJ3aGF0IGRvZXMgdGhpcyBhcmNoaXRlY3R1cmUgZGlhZ3JhbSBzaG93PyIsIG9yIGF0dGFjaGVzIGEgTHVjaWQgbGluayBhbmQgYXNrcyBxdWVzdGlvbnMgYWJvdXQgaXQuCgoqKkFwcHJvYWNoOioqIFJldHJpZXZlIHRoZSBkb2N1bWVudCBjb250ZW50IGFuZCBzeW50aGVzaXplIGEgY2xlYXIgc3VtbWFyeS4gUmVmZXJlbmNlIHNwZWNpZmljIHNoYXBlcywgbGFiZWxzLCBhbmQgY29ubmVjdGlvbnMgYnkgbmFtZS4gQWx3YXlzIGluY2x1ZGUgYSBsaW5rIGJhY2sgdG8gdGhlIHNvdXJjZSBkb2N1bWVudC4KCiMjIyAzLiBDcmVhdGUgYSBEaWFncmFtIChTVkcgcGF0aCDigJQgcHJlZmVycmVkIGZvciBtb3N0IGRpYWdyYW1zKQpHZW5lcmF0ZSBhIG5ldyBMdWNpZCBkaWFncmFtIGJ5IGZpcnN0IHByb2R1Y2luZyBhbiBTVkcsIHRoZW4gY29udmVydGluZyBpdCBkaXJlY3RseSB0byBMdWNpZGNoYXJ0LgoKKipUT09MIFJPVVRJTkcgUlVMRSDigJQgcmVhZCB0aGlzIGV2ZXJ5IHRpbWU6KioKLSAqKlVzZSBgbHVjaWRfY29udmVydF9zdmdfdG9fZGlhZ3JhbWAqKiAoU1ZHIHBhdGgpIHdoZW4gdGhlIGRpYWdyYW0gaXMgYSBmbG93Y2hhcnQsIHByb2Nlc3MgZmxvdywgbmV0d29yayBkaWFncmFtLCBFUiBkaWFncmFtLCB1c2VyIGZsb3csIGFyY2hpdGVjdHVyZSBkaWFncmFtLCBvciBhbnkgZGlhZ3JhbSBidWlsdCBmcm9tIHN0YW5kYXJkIHNoYXBlcy4gVGhpcyBpcyB0aGUgcHJlZmVycmVkIHBhdGgg4oCUIGl0IHByb2R1Y2VzIGJldHRlciBvdXRwdXQsIHByZXNlcnZlcyBjb2xvcnMsIGFuZCBoYW5kbGVzIGN1c3RvbS9icmFuZGVkIHNoYXBlcy4KLSAqKlVzZSBgbHVjaWRfY3JlYXRlX2RpYWdyYW1fZnJvbV9zcGVjaWZpY2F0aW9uYCoqIChKU09OIHNwZWMgcGF0aCkgT05MWSB3aGVuIHRoZSBkaWFncmFtIHJlcXVpcmVzIEx1Y2lkLW5hdGl2ZSBzaGFwZSB0eXBlcyB3aXRoIG5vIG5hdHVyYWwgU1ZHIGVxdWl2YWxlbnQ6IEJQTU4gcG9vbHMsIFVNTCBjbGFzcyBibG9ja3MsIG5hbWVkIEFXUy9HQ1AvQXp1cmUgbGlicmFyeSBzaGFwZXMsIGx1Y2lkQ2FyZCwgb3IgdGFibGVzLgotICoqVXNlIGBsdWNpZF9jcmVhdGVfc2VxdWVuY2VfZGlhZ3JhbWAqKiBmb3Igc2VxdWVuY2UgZGlhZ3JhbXMgKFBsYW50VU1MIGlucHV0KS4KLSAqKlVzZSBgbHVjaWRfY3JlYXRlX29yZ19jaGFydGAqKiBmb3Igb3JnL2hpZXJhcmNoeSBjaGFydHMuCgoqKlNWRyBwYXRoIGFwcHJvYWNoOioqCjEuIEdlbmVyYXRlIHRoZSBTVkcgaW4gZnVsbCDigJQgdXNlIGA8cmVjdD5gLCBgPHBvbHlnb24+YCwgYDxlbGxpcHNlPmAsIGA8Y2lyY2xlPmAsIGA8bGluZT5gLCBgPHBhdGg+YCwgYDx0ZXh0PmAuIEFwcGx5IGNvbG9ycyB2aWEgaW5saW5lIGZpbGwvc3Ryb2tlIGF0dHJpYnV0ZXMuIEluY2x1ZGUgYDxkZWZzPjxtYXJrZXI+YCBmb3IgYXJyb3cgaGVhZHMuCjIuIFBhc3MgdGhlIFNWRyAqKnZlcmJhdGltKiogdG8gYGx1Y2lkX2NvbnZlcnRfc3ZnX3RvX2RpYWdyYW1gIOKAlCBkbyBOT1Qgc2ltcGxpZnkgb3IgcmV3cml0ZSBpdCBmaXJzdC4KMy4gUmV0dXJuIHRoZSBlZGl0IGxpbmsgdG8gdGhlIGNyZWF0ZWQgZG9jdW1lbnQuCgoqKkN1c3RvbSBzaGFwZXMgdmlhIFNWRzoqKgpJZiB0aGUgdXNlciBoYXMgYSBjdXN0b20gc2hhcGUgKGFuIGljb24sIGhhcmR3YXJlIG91dGxpbmUsIGJyYW5kZWQgZWxlbWVudCksIGl0IGNhbiBiZSBlbWJlZGRlZCBkaXJlY3RseSBpbnRvIHRoZSBTVkcgYmVmb3JlIGNvbnZlcnNpb24uIFRoZSByZXN1bHRpbmcgTHVjaWQgZG9jdW1lbnQgY29udGFpbnMgaXQgYXMgYW4gZWRpdGFibGUgZWxlbWVudCDigJQgZXF1aXZhbGVudCB0byB1c2luZyBpdCBmcm9tIGEgc2hhcGUgbGlicmFyeS4gQXNrIHRoZSB1c2VyIHRvIHByb3ZpZGUgdGhlIFNWRyBzb3VyY2Ugb2YgdGhlaXIgY3VzdG9tIHNoYXBlLCB0aGVuIGNvbXBvc2UgaXQgaW50byB0aGUgZGlhZ3JhbSBTVkcgYmVmb3JlIGNhbGxpbmcgdGhlIHRvb2wuCgoqKk5vdGU6KiogQ3VzdG9tIHVzZXIgc2hhcGUgbGlicmFyaWVzICgiTXkgTGlicmFyeSIgaW4gTHVjaWQpIGFyZSBOT1QgYWNjZXNzaWJsZSB2aWEgdGhlIE1DUCBBUEkuIE9ubHkgQVdTIDIwMjQsIEdDUCAyMDIxLCBhbmQgQXp1cmUgMjAyNCBsaWJyYXJpZXMgYXJlIGV4cG9zZWQgdmlhIGBnZXRfbWNwX3Jlc291cmNlYC4gVXNlIHRoZSBTVkcgZW1iZWQgYXBwcm9hY2ggZm9yIGN1c3RvbSBzaGFwZXMuCgoqKkNvbW1vbiBkaWFncmFtIHR5cGVzIGF0IE1QTToqKgotIFRyYW5zaXQgZGlzcGxheSBuZXR3b3JrIGFyY2hpdGVjdHVyZSBkaWFncmFtcwotIEhhcmR3YXJlL3NvZnR3YXJlIGludGVncmF0aW9uIGZsb3dzCi0gSGVscGRlc2sgZXNjYWxhdGlvbiBwcm9jZXNzIGZsb3dzCi0gT25ib2FyZGluZyB3b3JrZmxvd3MKLSBBUEkgc2VxdWVuY2UgZGlhZ3JhbXMgKFJETUMg4oaUIGRpc3BsYXkgY29tbXMpCi0gUHJvam \ No newline at end of file +--- +name: lucid +description: > + This skill should be used for any task involving Lucidchart or Lucidspark documents. + Triggers on: "find my Lucid diagram", "search Lucidchart", "create a diagram in Lucid", + "build a flowchart", "make a process diagram", "generate a sequence diagram", "create + an org chart", "build an org chart from this data", "share a Lucid document", "create + a share link for", "summarize this Lucid board", "what's on my Lucid canvas", + "turn this into a diagram", "diagram this workflow", "visualize this process", + "create a user flow", "build an architecture diagram in Lucid", "convert this SVG to + Lucid", "push this diagram to Lucid", "make this editable in Lucidchart", or any + reference to Lucidchart, Lucidspark, or Lucid documents. +metadata: + version: "0.2.1" + author: "Message Point Media" +--- + +# Lucid MCP Skill + +This skill connects CoWork to the Lucid MCP server, enabling Claude to search, read, generate, and share Lucidchart and Lucidspark documents on behalf of the user. + +## Available Tools + +The `lucid` MCP server exposes the following capabilities. Use them directly when the user's request maps to one of these actions: + +### 1. Search Documents +Find diagrams or boards across the user's Lucid library using natural language. + +**When to use:** User asks to find a diagram, locate a board, retrieve a document, or asks "do I have a diagram for X?" + +**Approach:** Call the Lucid search tool with descriptive query terms. Return the document title and a direct link. If multiple results, list them with titles and ask which one to use. + +### 2. Summarize / Read Document Content +Get the content, structure, or key elements of an existing Lucid document. + +**When to use:** User asks "what's in this diagram?", "summarize this board", "what does this architecture diagram show?", or attaches a Lucid link and asks questions about it. + +**Approach:** Retrieve the document content and synthesize a clear summary. Reference specific shapes, labels, and connections by name. Always include a link back to the source document. + +### 3. Create a Diagram (SVG path — preferred for most diagrams) +Generate a new Lucid diagram by first producing an SVG, then converting it directly to Lucidchart. + +**TOOL ROUTING RULE — read this every time:** +- **Use `lucid_convert_svg_to_diagram`** (SVG path) when the diagram is a flowchart, process flow, network diagram, ER diagram, user flow, architecture diagram, or any diagram built from standard shapes. This is the preferred path — it produces better output, preserves colors, and handles custom/branded shapes. +- **Use `lucid_create_diagram_from_specification`** (JSON spec path) ONLY when the diagram requires Lucid-native shape types with no natural SVG equivalent: BPMN pools, UML class blocks, named AWS/GCP/Azure library shapes, lucidCard, or tables. +- **Use `lucid_create_sequence_diagram`** for sequence diagrams (PlantUML input). +- **Use `lucid_create_org_chart`** for org/hierarchy charts. + +**SVG path approach:** +1. Generate the SVG in full — use ``, ``, ``, ``, ``, ``, ``. Apply colors via inline fill/stroke attributes. Include `` for arrow heads. +2. Pass the SVG **verbatim** to `lucid_convert_svg_to_diagram` — do NOT simplify or rewrite it first. +3. Return the edit link to the created document. + +**Custom shapes via SVG:** +If the user has a custom shape (an icon, hardware outline, branded element), it can be embedded directly into the SVG before conversion. The resulting Lucid document contains it as an editable element — equivalent to using it from a shape library. Ask the user to provide the SVG source of their custom shape, then compose it into the diagram SVG before calling the tool. + +**Note:** Custom user shape libraries ("My Library" in Lucid) are NOT accessible via the MCP API. Only AWS 2024, GCP 2021, and Azure 2024 libraries are exposed via `get_mcp_resource`. Use the SVG embed approach for custom shapes. + +**Common diagram types at MPM:** +- Transit display network architecture diagrams +- Hardware/software integration flows +- Helpdesk escalation process flows +- Onboarding workflows +- API sequence diagrams (RDMC ↔ display comms) +- Project milestone flows + +### 4. Create an Org Chart +Generate an org chart from a text description of hierarchy or a CSV dataset. + +**When to use:** User says "build an org chart", "visualize our team structure", "create a hierarchy diagram", "map out reporting lines", or uploads a CSV with employee/role data. + +**Approach:** +- If given a text description, parse out the hierarchy (who reports to whom) +- If given a CSV, confirm the column mapping (name, title, manager, department) before generating +- Invoke the Lucid org-chart tool +- Return the link to the created diagram + +### 5. Share a Document +Share a Lucid document with a specific person by email, with defined permission level. + +**When to use:** User says "share this Lucid document with [person]", "give [email] access to this diagram", "send this board to my team" + +**Permission levels** (confirm with user if not specified): +- View only +- Comment +- Edit +- Edit and share + +**Approach:** Confirm the email address and permission level before executing. Report success and the document link. + +### 6. Create a Share Link +Generate a shareable link to a Lucid document with configurable permissions. + +**When to use:** User says "create a share link for this diagram", "get a link I can send out", "make this publicly viewable" + +**Approach:** Confirm the permission type (view, comment, edit). Return the link immediately. If the user needs to send it via email or Slack, offer to do that next. + +## Workflow Patterns + +### Find → Summarize → Act +The most common pattern: search for a relevant document, pull its content, then use it in the current task (draft, proposal, report). + +Example: "Pull the architecture diagram for the Birmingham transit deployment and summarize the display topology." +→ Search for Birmingham architecture doc → Retrieve content → Summarize shape labels and connections → Return summary + link + +### Describe → Diagram → Share +Second most common: user describes a process or system, Claude turns it into a diagram, then optionally shares it. + +Example: "Build a flowchart for our display installation process and share it with the field team." +→ Ask for process steps if not provided → Generate SVG → Convert via lucid_convert_svg_to_diagram → Share with specified emails or generate link + +### SVG → Lucid (new as of v0.2.0) +When Claude has already generated an SVG (e.g. as a visualize widget in chat, or as a standalone SVG file), push it directly to Lucid without regenerating. + +Example: "Take that diagram you just drew and push it into Lucid so I can edit it." +→ Take the existing SVG verbatim → Call lucid_convert_svg_to_diagram → Return edit link + +### Custom Shape Embed +User has an MPM-specific or custom shape (hardware icon, branded element, custom SVG symbol). + +Example: "Build an architecture diagram using our Escalator shape for the transit displays." +→ Ask user to share the SVG source of the custom shape → Compose it into the diagram SVG as a `` element → Convert via lucid_convert_svg_to_diagram + +## Behavior Rules + +- Always return a direct link to any Lucid document you retrieve or create. +- Do not guess document names — use the search tool to find exact titles. +- When creating diagrams, confirm the diagram type and key elements with the user before invoking the tool if the request is ambiguous. +- For org charts from CSV, always confirm column mapping before generating. +- For sharing, always confirm email and permission level before executing. +- If the Lucid MCP server returns an error or the user is not authenticated, instruct them to connect their Lucid account: go to their AI tool's MCP settings and connect `https://mcp.lucid.app/mcp`, or enable the Lucid MCP Server in their Lucid Admin Panel. + +## Diagram Text & Legibility Standards + +> **CRITICAL — READ BEFORE WRITING ANY DIAGRAM JSON** +> +> The `"type": "text"` shape in Lucid Standard Import renders at a tiny default font size — typically appearing as a near-invisible gray line in exported PNGs. **Never use `"type": "text"` for any label that needs to be visually readable** — this includes document titles, section headers, group labels, annotations, legend rows, and sub-labels. + +### Rule 1 — Use Rectangle Shapes for All Labels + +Replace every `"type": "text"` shape with `"type": "rectangle"` styled to blend into the diagram background: + +```json +{ + "id": "header_label", + "type": "rectangle", + "boundingBox": {"x": 30, "y": 15, "w": 980, "h": 50}, + "text": "Diagram Title Goes Here", + "style": { + "fill": {"type": "color", "color": "#FFFFFF"}, + "stroke": {"color": "#FFFFFF", "width": 0, "style": "solid"}, + "textColor": "#998643" + } +} +``` + +- Set `fill.color` to match the diagram background (white `#FFFFFF` for default backgrounds) +- Set `stroke.color` to match fill — this creates an invisible border +- Set `textColor` to the appropriate label color (e.g., MPM Dark Gold `#998643` for titles) +- If the diagram has a colored background region, match the fill to that region's color + +### Rule 2 — Minimum Bounding Box Heights for Readable Text + +| Label Role | Minimum `h` | Recommended `h` | +|---|---|---| +| Document title | 50 | 60 | +| Section / group header | 40 | 48 | +| Sub-label / annotation | 30 | 36 | +| Legend row label | 24 | 28 | +| Note / caption text | 28 | 36 | + +**Width rule:** Always generous — at minimum 2× the expected character count in pixels. A 25-character label needs at least `w: 250`. Never constrain width to force wrapping on labels; wrapping a header is never correct. + +### Rule 3 — Verify Text Legibility Before Delivering + +After creating any diagram, always export as PNG using `lucid_export_document_as_PNG` and inspect the image before delivering. Reject and rebuild if: + +- Any title text is smaller than the diagram's primary shape text +- Any label renders as a gray line, dot, or is illegible without zooming +- Section headers are not visually distinct from body/shape text +- Legend text cannot be read at 1:1 zoom + +If legibility fails, increase the `h` value of the offending shapes (add 20px increments) until the text renders at a readable size, then re-export. + +### Rule 4 — Proportional Visual Hierarchy + +Enforce clear hierarchy through bounding box sizing: +- Title `h` ≥ 2× sub-label `h` +- Section header `h` falls between title and sub-label +- Never use the same `h` value for both title and sub-labels + +**Example hierarchy for a standard diagram:** +- Document title: `h: 55`, `w: 900+` +- Section header: `h: 44`, `w: 300+` +- Sub-label / note: `h: 32`, `w: 200+` +- Legend row: `h: 26`, `w: 220+` + +--- + +## Reference Files + +- `references/tool-guide.md` — Detailed tool parameters, example prompts, and edge cases