README

Splits an Excalidraw library file (*.excalidrawlib) into individual icon JSON files for efficient token usage by AI assistants.

Prerequisites

• Python 3.6 or higher
• No additional dependencies required (uses only standard library)

Usage

Step-by-Step Workflow

1. Create library directory:

   bashCopy

   mkdir -p skills/excalidraw-diagram-generator/libraries/aws-architecture-icons

2. Download and place library file:

   • Visit: https://libraries.excalidraw.com/ (opens in a new tab)
   • Search for “AWS Architecture Icons” and download the .excalidrawlib file
   • Rename it to match the directory name: aws-architecture-icons.excalidrawlib
   • Place it in the directory created in step 1

3. Run the script:

   bashCopy

   python skills/excalidraw-diagram-generator/scripts/split-excalidraw-library.py skills/excalidraw-diagram-generator/libraries/aws-architecture-icons/

Output Structure

The script creates the following structure in the library directory:

What the Script Does

1. Reads the .excalidrawlib file
2. Extracts each icon from the libraryItems array
3. Sanitizes icon names to create valid filenames (spaces → hyphens, removes special characters)
4. Saves each icon as a separate JSON file in the icons/ directory
5. Generates a reference.md file with a table mapping icon names to filenames

Benefits

• Token Efficiency: AI can first read the lightweight reference.md to find relevant icons, then load only the specific icon files needed
• Organization: Icons are organized in a clear directory structure
• Extensibility: Users can add multiple library sets side-by-side

Recommended Workflow

1. Download desired Excalidraw libraries from https://libraries.excalidraw.com/ (opens in a new tab)
2. Run this script on each library file
3. Move the generated folders to ../libraries/
4. The AI assistant will use reference.md files to locate and use icons efficiently

Library Sources (Examples — verify availability)

• Examples found on https://libraries.excalidraw.com/ (opens in a new tab) may include cloud/service icon sets.
• Availability changes over time; verify the exact library names on the site before use.
• This script works with any valid .excalidrawlib file you provide.

Troubleshooting

Error: File not found

• Check that the file path is correct
• Make sure the file has a .excalidrawlib extension

Error: Invalid library file format

• Ensure the file is a valid Excalidraw library file
• Check that it contains a libraryItems array

License Considerations

When using third-party icon libraries:

• AWS Architecture Icons: Subject to AWS Content License
• GCP Icons: Subject to Google’s terms
• Other libraries: Check each library’s license

This script is for personal/organizational use. Redistribution of split icon files should comply with the original library’s license terms.

add-icon-to-diagram.py

Adds a specific icon from a split Excalidraw library into an existing .excalidraw diagram. The script handles coordinate translation and ID collision avoidance, and can optionally add a label under the icon.

Prerequisites

• Python 3.6 or higher
• A diagram file (.excalidraw)
• A split icon library directory (created by split-excalidraw-library.py)

Usage

Options

• --library-path PATH : Path to the icon library directory (default: aws-architecture-icons)
• --label TEXT : Add a text label below the icon – --use-edit-suffix : Edit via .excalidraw.edit to avoid editor overwrite issues (enabled by default; pass --no-use-edit-suffix to disable)

Examples

What the Script Does

1. Loads the icon JSON from the library’s icons/ directory
2. Calculates the icon’s bounding box
3. Offsets all coordinates to the target position
4. Generates unique IDs for all elements and groups
5. Appends the transformed elements to the diagram
6. (Optional) Adds a label beneath the icon

add-arrow.py

Adds a straight arrow between two points in an existing .excalidraw diagram. Supports optional labels and line styles.

Prerequisites

• Python 3.6 or higher
• A diagram file (.excalidraw)

Usage

Options

• --style {solid|dashed|dotted} : Line style (default: solid)
• --color HEX : Arrow color (default: #1e1e1e)
• --label TEXT : Add a text label on the arrow – --use-edit-suffix : Edit via .excalidraw.edit to avoid editor overwrite issues (enabled by default; pass --no-use-edit-suffix to disable)

Examples

What the Script Does

1. Creates an arrow element from the given coordinates
2. (Optional) Adds a label near the arrow midpoint
3. Appends elements to the diagram
4. Saves the updated file