docs(mermaid): 更新所有图表类型的文档示例和语法说明

- 完善了架构图的语法说明，增加了兼容性注释和多个实际应用示例
- 扩展了块状图的详细语法和多列布局、连接关系等示例
- 更新了C4图的完整语法说明，包括系统边界、部署节点等高级特性
- 增加了类图的可见性修饰符、泛型、命名空间等复杂用法示例
- 补充了实体关系图的基数标记、别名、样式等完整功能说明
- 优化了流程图的各种节点形状、边线样式、子图和交互功能示例
- 为每种图表类型提供了向后兼容的替代方案
- 添加了详细的官方文档链接和版本兼容性说明

IMPLEMENTATION.md

@@ -13,7 +13,7 @@
 例如：
 ```
 /plugin marketplace add anthropics/skills
-/plugin marketplace add teaching-ai/skills
+/plugin marketplace add https://github.com/teachingai/agent-skills.git
 ```
 
 ### 2. 工作原理
@@ -142,7 +142,7 @@ license: 许可证信息（可选）
 
 ### 1. 创建 GitHub 仓库
 
-1. 在 GitHub 上创建新仓库（例如：`teaching-ai/skills`）
+1. 在 GitHub 上创建新仓库（例如：`teachingai/agent-skills`）
 2. 确保仓库是公开的（public），这样 Claude Code 才能访问
 
 ### 2. 创建目录结构
@@ -171,7 +171,7 @@ git push origin main
 ### 6. 在 Claude Code 中使用
 
 ```
-/plugin marketplace add teaching-ai/skills
+/plugin marketplace add https://github.com/teachingai/agent-skills.git
 ```
 
 ## 技术细节

PLATFORM_GUIDE.md

@@ -26,7 +26,7 @@ Claude Code 完全支持 Agent Skills 标准，可以直接使用 marketplace
 
 **安装方式：**
 ```bash
-/plugin marketplace add teaching-ai/skills
+/plugin marketplace add https://github.com/teachingai/agent-skills.git
 /plugin install teaching-skills@teaching-ai-skills
 ```
 

README.md

@@ -37,10 +37,16 @@ Skills 是由说明、脚本和资源组成的文件夹，Claude 会按需动态
 在 Claude Code 中运行以下命令，将本仓库注册为 Claude Code 的插件市场：
 
 ```
-/plugin marketplace add teaching-ai/skills
+/plugin marketplace add https://github.com/teachingai/agent-skills.git
 ```
 
-> **注意**: 请将 `teaching-ai/skills` 替换为您的实际 GitHub 仓库路径（格式：`用户名/仓库名`）
+![add_marketplace.png](./media/add_marketplace.png)
+
+或者使用简写形式：
+
+```
+/plugin marketplace add teachingai/agent-skills
+```
 
 #### 2. 安装插件
 
@@ -67,6 +73,8 @@ Skills 是由说明、脚本和资源组成的文件夹，Claude 会按需动态
 /plugin install utility-skills@teaching-ai-skills
 ```
 
+![install-teaching-ai-skills.png](media/install-teaching-ai-skills.png)
+
 #### 3. 使用技能
 
 安装插件后，您只需提到该技能即可使用。Claude 会根据技能描述自动判断何时使用该技能。
@@ -509,7 +517,7 @@ git push
 
 ## 工作原理
 
-1. **Marketplace 注册**: 当您运行 `/plugin marketplace add teaching-ai/skills` 时，Claude Code 会：
+1. **Marketplace 注册**: 当您运行 `/plugin marketplace add https://github.com/teachingai/agent-skills.git` 时，Claude Code 会：
    - 从 GitHub 仓库获取 `.claude-plugin/marketplace.json` 文件
    - 解析 marketplace 配置
    - 将 marketplace 添加到可用列表

README_EN.md

@@ -37,10 +37,14 @@ Many skills in this repo are open source (Apache 2.0). We've also included the d
 Run the following command in Claude Code to register this repository as a Claude Code plugin marketplace:
 
 ```
-/plugin marketplace add teaching-ai/skills
+/plugin marketplace add https://github.com/teachingai/agent-skills.git
 ```
 
-> **Note**: Replace `teaching-ai/skills` with your actual GitHub repository path (format: `username/repository-name`)
+Or use the short form:
+
+```
+/plugin marketplace add teachingai/agent-skills
+```
 
 #### 2. Install Plugins
 
@@ -498,7 +502,7 @@ The `.claude-plugin/marketplace.json` file defines the marketplace metadata and
 
 ## How It Works
 
-1. **Marketplace Registration**: When you run `/plugin marketplace add teaching-ai/skills`, Claude Code will:
+1. **Marketplace Registration**: When you run `/plugin marketplace add https://github.com/teachingai/agent-skills.git`, Claude Code will:
    - Fetch the `.claude-plugin/marketplace.json` file from the GitHub repository
    - Parse the marketplace configuration
    - Add the marketplace to the available list

skills/mermaid/SKILL.md

@@ -76,11 +76,23 @@ To create a Mermaid diagram:
 
 3. **Follow the specific instructions** in that example file for syntax, structure, and best practices
 
-4. **Generate the Mermaid code** wrapped in a code block:
+4. **Generate the Mermaid code** wrapped in a Markdown code block with proper syntax highlighting:
+   
+   **IMPORTANT**: Always wrap the Mermaid code in a Markdown code block with `mermaid` language tag. This ensures the format is preserved when users copy the content.
+   
+   **Example format** (use actual Mermaid syntax, not placeholders):
    ```mermaid
-   <diagram-type>
-   ...diagram content...
+   flowchart TD
+       A[Start] --> B[Process]
+       B --> C[End]
    ```
+   
+   **Output Format Requirements**:
+   - Always use triple backticks (```) with `mermaid` language tag
+   - Never output raw Mermaid code without code block markers
+   - The code block must be complete and properly formatted
+   - Use actual valid Mermaid syntax, not placeholders like `<diagram-type>` or `...diagram content...`
+   - This ensures users can copy the code without losing formatting
 
 5. **Include styling and configuration** when needed:
    - Use `%%{ init: { theme: 'base' } }%%` for theme configuration
@@ -93,6 +105,42 @@ To create a Mermaid diagram:
    - Verify date formats for Gantt charts
    - Confirm data formats for charts (pie, quadrant, etc.)
 
+7. **Save the diagram to project directory**:
+   - **Default behavior**: When generating a Mermaid diagram, save it to the current project directory
+   - **Recommended locations**:
+     - `docs/diagrams/` - For documentation diagrams
+     - `docs/` - For general documentation
+     - `diagrams/` - For standalone diagram files
+     - Current directory (`.`) - If no specific directory structure exists
+   - **File naming**: Use descriptive names like `system-architecture.md`, `user-flow.md`, `database-schema.md`, etc.
+   - **File format**: Save as `.md` file with the Mermaid code block inside
+   - **Example**: If user requests a system architecture diagram, save it as `docs/diagrams/system-architecture.md` or `diagrams/system-architecture.md`
+   - **Ask if needed**: If the project structure is unclear, ask the user where they'd like the diagram saved, but default to creating a `docs/` or `diagrams/` directory if it doesn't exist
+
+**Output Format and File Saving**:
+
+When generating a diagram, follow this response structure:
+
+1. **Save the file first**: Create the diagram file in the project directory (e.g., `docs/diagrams/system-architecture.md`)
+
+2. **Inform the user**: Tell them where the file was saved
+
+3. **Display the diagram**: Show the Mermaid code in a properly formatted Markdown code block with `mermaid` language tag
+
+**Example Response Structure**:
+- First line: "I've created the Mermaid diagram and saved it to `docs/diagrams/system-architecture.md`."
+- Then show the diagram wrapped in a code block:
+  - Start with: three backticks + `mermaid` + newline
+  - Then the Mermaid code
+  - End with: three backticks + newline
+
+**Critical Requirements**:
+- The Mermaid code block MUST ALWAYS be properly formatted with triple backticks (```) and `mermaid` language tag
+- NEVER output raw Mermaid code without code block markers
+- The code block must be complete (opening and closing backticks)
+- This ensures users can copy the code without losing formatting
+- Always save the diagram file to the current project directory (default: `docs/diagrams/` or `diagrams/`)
+
 If the diagram type doesn't match any existing example, refer to the Mermaid documentation or ask the user for clarification about the desired visualization.
 
 ## Keywords

skills/mermaid/examples/architecture.md

@@ -1,25 +1,208 @@
 ## Instructions
 
-Architecture diagrams (beta) visualize system architectures, showing components and their relationships.
+Architecture diagrams are used to show the relationship between services and resources commonly found within the Cloud or CI/CD deployments. In an architecture diagram, services (nodes) are connected by edges. Related services can be placed within groups to better illustrate how they are organized.
+
+**⚠️ Important Compatibility Note**: `architecture-beta` requires Mermaid v11.1.0 or higher. If your rendering environment doesn't support this diagram type (you'll see "No diagram type detected" error), please use the **Flowchart alternatives** provided below each example, which are compatible with all Mermaid versions.
 
 ### Syntax
 
-- Use `architecture-beta` keyword
-- Components: `component ComponentName`
-- Connections: `Component1 --> Component2`
-- Labels: `Component1 -->|Label| Component2`
-- Groups: `group GroupName { }`
+- Use `architecture-beta` keyword (requires Mermaid v11.1.0+)
+- **If your environment doesn't support `architecture-beta`**: Each example below includes a flowchart alternative that works with all Mermaid versions
+- Building blocks: `groups`, `services`, `edges`, and `junctions`
+- Icons: Declared by surrounding the icon name with `()`
+- Labels: Declared by surrounding the text with `[]`
+- Groups: `group {group id}({icon name})[{title}] (in {parent id})?`
+- Services: `service {service id}({icon name})[{title}] (in {parent id})?`
+- Edges: `{serviceId}{{group}}?:{T|B|L|R} -- {T|B|L|R}:{serviceId}{{group}}?` (use `--` not `-->`)
+- Junctions: `junction {junction id} (in {parent id})?`
+- Default icons: `cloud`, `database`, `disk`, `internet`, `server`
+- Custom icons: Can use 200,000+ icons from iconify.design by registering an icon pack
+
+Reference: [Mermaid Architecture Diagram Documentation](https://mermaid.ai/open-source/syntax/architecture.html)
+
+### Example (Basic Architecture)
+
+**Note**: Requires Mermaid v11.1.0+. If not supported, use the flowchart alternative below.
+
+```mermaid
+architecture-beta
+    group public_api(cloud)[Public API]
+    group private_api(cloud)[Private API] in public_api
+    service database1(database)[My Database] in private_api
+    service server1(server)[Web Server] in public_api
+    server1:L -- R:database1
+```
+
+**Flowchart Alternative (Compatible with all versions):**
+
+```mermaid
+flowchart TD
+    subgraph PublicAPI["Public API"]
+        subgraph PrivateAPI["Private API"]
+            Database[(My Database)]
+        end
+        Server[Web Server]
+    end
+    Server --> Database
+```
+
+### Example (With Edges and Directions)
+
+**Note**: Requires Mermaid v11.1.0+. If not supported, use the flowchart alternative below.
+
+```mermaid
+architecture-beta
+    service db(database)[Database]
+    service server(server)[Server]
+    service gateway(internet)[Gateway]
+
+    db:L -- R:server
+    server:T -- B:gateway
+```
+
+**Flowchart Alternative (Compatible with all versions):**
+
+```mermaid
+flowchart LR
+    DB[(Database)]
+    Server[Server]
+    Gateway[Gateway]
+
+    DB --> Server
+    Server --> Gateway
+```
+
+### Example (Groups and Nested Services)
+
+**Note**: Requires Mermaid v11.1.0+. If not supported, use the flowchart alternative below.
+
+```mermaid
+architecture-beta
+    group frontend(cloud)[Frontend]
+    group backend(cloud)[Backend]
+
+    service web(server)[Web Server] in frontend
+    service api(server)[API Server] in backend
+    service db(database)[Database] in backend
+
+    web:L -- R:api
+    api:L -- R:db
+```
+
+**Flowchart Alternative (Compatible with all versions):**
+
+```mermaid
+flowchart TD
+    subgraph Frontend["Frontend"]
+        Web[Web Server]
+    end
+    subgraph Backend["Backend"]
+        API[API Server]
+        DB[(Database)]
+    end
+    Web --> API
+    API --> DB
+```
+
+### Example (With Junctions)
+
+**Note**: Requires Mermaid v11.1.0+. If not supported, use the flowchart alternative below.
+
+```mermaid
+architecture-beta
+    service db1(database)[Database 1]
+    service db2(database)[Database 2]
+    service server(server)[Server]
+    junction j1
+
+    server:B -- T:j1
+    j1:L -- R:db1
+    j1:R -- L:db2
+```
+
+**Flowchart Alternative (Compatible with all versions):**
+
+```mermaid
+flowchart TD
+    Server[Server]
+    DB1[(Database 1)]
+    DB2[(Database 2)]
+
+    Server --> DB1
+    Server --> DB2
+```
+
+### Example (Edge from Group to Group)
+
+**Note**: Requires Mermaid v11.1.0+. If not supported, use the flowchart alternative below.
+
+```mermaid
+architecture-beta
+    group groupOne(cloud)[Group One]
+    group groupTwo(cloud)[Group Two]
+
+    service server[Server] in groupOne
+    service subnet[Subnet] in groupTwo
+
+    server{group}:B -- T:subnet{group}
+```
 
-### Example
+**Flowchart Alternative (Compatible with all versions):**
+
+```mermaid
+flowchart TD
+    subgraph GroupOne["Group One"]
+        Server[Server]
+    end
+    subgraph GroupTwo["Group Two"]
+        Subnet[Subnet]
+    end
+    Server --> Subnet
+```
+
+### Example (Complex Cloud Architecture)
+
+**Note**: Requires Mermaid v11.1.0+. If not supported, use the flowchart alternative below.
 
 ```mermaid
 architecture-beta
-    component Frontend
-    component API
-    component Database
-    component Cache
-    
-    Frontend -->|HTTP| API
-    API -->|Query| Database
-    API -->|Read/Write| Cache
+    group public(cloud)[Public Cloud]
+    group private(cloud)[Private Cloud]
+
+    service gateway(internet)[Internet Gateway] in public
+    service loadbalancer(server)[Load Balancer] in public
+    service app1(server)[App Server 1] in private
+    service app2(server)[App Server 2] in private
+    service db(database)[Database] in private
+    service storage(disk)[Storage] in private
+
+    gateway:L -- R:loadbalancer
+    loadbalancer:B -- T:app1
+    loadbalancer:B -- T:app2
+    app1:L -- R:db
+    app2:L -- R:db
+    db:B -- T:storage
+```
+
+**Flowchart Alternative (Compatible with all versions):**
+
+```mermaid
+flowchart TD
+    subgraph Public["Public Cloud"]
+        Gateway[Internet Gateway]
+        LB[Load Balancer]
+    end
+    subgraph Private["Private Cloud"]
+        App1[App Server 1]
+        App2[App Server 2]
+        DB[(Database)]
+        Storage[(Storage)]
+    end
+
+    Gateway --> LB
+    LB --> App1
+    LB --> App2
+    App1 --> DB
+    App2 --> DB
+    DB --> Storage
 ```

skills/mermaid/examples/block.md

@@ -1,23 +1,122 @@
 ## Instructions
 
-Block diagrams represent systems as interconnected blocks, showing the structure and relationships between components.
+Block diagrams are an intuitive way to represent complex systems, processes, or architectures visually. They are composed of blocks and connectors, where blocks represent fundamental components or functions, and connectors show relationships or flow between components. Unlike flowcharts, block diagrams give the author full control over where shapes are positioned.
 
 ### Syntax
 
 - Use `block-beta` keyword
-- Blocks: `block BlockName`
-- Connections: `Block1 --> Block2`
+- Basic blocks: `block BlockName` or just `BlockName`
+- Columns: Specify number of columns to organize blocks
+- Block width: Blocks can span multiple columns
+- Composite blocks: Nested blocks within parent blocks
+- Connections: `Block1 --> Block2` or `Block1 --- Block2`
 - Labels: `Block1 -->|Label| Block2`
-- Groups: `blockGroup GroupName { }`
+- Block shapes: rectangle (default), circle, round, diamond, hexagon, square, double-circle, asymmetric, rhombus, parallelogram, trapezoid
+- Space blocks: `space` or `space:num` for intentional spacing
+- Styling: `style BlockName fill:#color,stroke:#color,stroke-width:2px`
 
-### Example
+Reference: [Mermaid Block Diagram Documentation](https://mermaid.ai/open-source/syntax/block.html)
+
+### Example (Simple Block Diagram)
+
+```mermaid
+block-beta
+    a b c
+```
+
+### Example (Multi-Column Layout)
+
+```mermaid
+block-beta columns 3
+    a b c d
+```
+
+### Example (Block Spanning Multiple Columns)
+
+```mermaid
+block-beta columns 3
+    A:1 b:2 c:2 d:1
+```
+
+### Example (Composite Blocks - Nested)
+
+```mermaid
+block-beta
+    A B C
+    D
+        D E
+        D F
+```
+
+### Example (Basic Connections)
+
+```mermaid
+block-beta
+    A B C
+    A --> B
+    B --> C
+```
+
+### Example (Connections with Labels)
+
+```mermaid
+block-beta
+    A B C
+    A -->|Data| B
+    B -->|Result| C
+```
+
+### Example (Different Block Shapes)
 
 ```mermaid
 block-beta
-    block Input
-    block Process
-    block Output
-    
-    Input -->|Data| Process
-    Process -->|Result| Output
+    A["Rectangle"]
+    B(("Circle"))
+    C(["Round"])
+    D{"Diamond"}
+    E{{"Hexagon"}}
+    E1["Square"]
+    E2(("Double Circle"))
+    E3>"Asymmetric"]
+    E4{"Rhombus"}
+    E5[/"Parallelogram"/]
+    E6[/"Trapezoid"\]
+```
+
+### Example (Space Blocks)
+
+```mermaid
+block-beta
+    A space B
+    C space:2 D
+```
+
+### Example (System Architecture with Styling)
+
+```mermaid
+block-beta
+    Frontend Backend Database
+    Frontend -->|HTTP| Backend
+    Backend -->|Query| Database
+
+    style Frontend fill:#e1f5,stroke:#333,stroke-width:2px
+    style Backend fill:#fff4e1,stroke:#333,stroke-width:2px
+    style Database fill:#e1f5ff,stroke:#333,stroke-width:2px
+```
+
+### Example (Business Process Flow)
+
+```mermaid
+block-beta
+    Start{"Start"}
+    Process1["Process 1"]
+    Decision{"Decision?"}
+    Process2["Process 2"]
+    End["End"]
+
+    Start --> Process1
+    Process1 --> Decision
+    Decision -->|Yes| Process2
+    Decision -->|No| End
+    Process2 --> End
 ```

skills/mermaid/examples/c4.md

@@ -1,30 +1,162 @@
 ## Instructions
 
-C4 diagrams model software architecture at different levels of abstraction, from system context to component details.
+C4 diagrams model software architecture at different levels of abstraction, from system context to component details. Mermaid's C4 diagram syntax is compatible with plantUML. C4 diagrams are used to visualize software architecture at different levels: System Context, Container, Component, Dynamic, and Deployment.
+
+**Note**: This is an experimental diagram type. The syntax and properties can change in future releases. Proper documentation will be provided when the syntax is stable.
 
 ### Syntax
 
-- Use `C4Context`, `C4Container`, `C4Component`, or `C4Dynamic` keywords
-- Title: `title Diagram Title`
-- Person: `Person(alias, "Label", "Description")`
-- System: `System(alias, "Label", "Description")`
-- SystemDb: `SystemDb(alias, "Label", "Description")`
-- Boundary: `Enterprise_Boundary(alias, "Label") { }`
-- Relationships: `Rel(from, to, "Label", "Technology")`
-- BiRel: `BiRel(from, to, "Label", "Technology")`
+- Use `C4Context`, `C4Container`, `C4Component`, `C4Dynamic`, or `C4Deployment` keywords
+- Title: `title Diagram Title` (optional)
+- Elements:
+  - Person: `Person(alias, "Label", "Description")`
+  - System: `System(alias, "Label", "Description")`
+  - SystemDb: `SystemDb(alias, "Label", "Description")`
+  - SystemQueue: `SystemQueue(alias, "Label", "Description")`
+  - System_Ext: `System_Ext(alias, "Label", "Description")`
+  - Container: `Container(alias, "Label", "Technology", "Description")`
+  - Component: `Component(alias, "Label", "Technology", "Description")`
+  - Deployment_Node: `Deployment_Node(alias, "Label", "Type", "Description")`
+- Boundaries: `Enterprise_Boundary(alias, "Label") { }` or `System_Boundary(alias, "Label") { }`
+- Relationships: `Rel(from, to, "Label", "Technology")` or `BiRel(from, to, "Label", "Technology")`
+- Directional relationships: `Rel_U`, `Rel_D`, `Rel_L`, `Rel_R` (Up, Down, Left, Right)
+
+Reference: [Mermaid C4 Diagram Documentation](https://mermaid.ai/open-source/syntax/c4.html)
 
-### Example
+### Example (C4Context - System Context Diagram)
 
 ```mermaid
 C4Context
     title System Context Diagram
-    
+
     Person(customer, "Customer", "A customer of the system")
     System(webapp, "Web Application", "Provides web interface")
     System_Ext(email, "Email System", "Sends email notifications")
     SystemDb(database, "Database", "Stores application data")
-    
+
     Rel(customer, webapp, "Uses")
     Rel(webapp, database, "Reads from and writes to")
     Rel(webapp, email, "Sends emails via")
 ```
+
+### Example (C4Container - Container Diagram)
+
+```mermaid
+C4Container
+    title Container Diagram
+
+    Person(user, "User", "A user of the system")
+    System_Boundary(c1, "Web Application") {
+        Container(web, "Web Server", "Java/Spring", "Delivers web content")
+        Container(api, "API Application", "Java/Spring", "Provides API endpoints")
+    }
+    SystemDb(database, "Database", "PostgreSQL", "Stores data")
+
+    Rel(user, web, "Uses", "HTTPS")
+    Rel(web, api, "Uses", "HTTPS")
+    Rel(api, database, "Reads from and writes to", "JDBC")
+```
+
+### Example (C4Component - Component Diagram)
+
+```mermaid
+C4Component
+    title Component Diagram
+
+    Container(webapp, "Web Application", "Java/Spring", "Web application")
+    System_Boundary(c1, "Web Application") {
+        Component(controller, "UserController", "Spring MVC", "Handles HTTP requests")
+        Component(service, "UserService", "Spring", "Business logic")
+        Component(repository, "UserRepository", "Spring Data", "Data access")
+    }
+    SystemDb(database, "Database", "PostgreSQL", "Stores data")
+
+    Rel(webapp, controller, "Uses")
+    Rel(controller, service, "Uses")
+    Rel(service, repository, "Uses")
+    Rel(repository, database, "Reads from and writes to")
+```
+
+### Example (C4Dynamic - Dynamic Diagram)
+
+```mermaid
+C4Dynamic
+    title Dynamic Diagram
+
+    Person(user, "User", "A user")
+    System(webapp, "Web Application", "Web app")
+    SystemDb(database, "Database", "Database")
+
+    RelIndex(1, user, webapp, "1. Login request")
+    RelIndex(2, webapp, database, "2. Query user")
+    RelIndex(3, database, webapp, "3. Return user data")
+    RelIndex(4, webapp, user, "4. Return login result")
+```
+
+### Example (C4Deployment - Deployment Diagram)
+
+```mermaid
+C4Deployment
+    title Deployment Diagram
+
+    Deployment_Node(web, "Web Server", "Linux", "Apache Tomcat"){
+        Container(webapp, "Web Application", "Java", "Web application")
+    }
+    Deployment_Node(app, "Application Server", "Linux", "Java Runtime"){
+        Container(appserver, "App Server", "Java", "Application server")
+    }
+    Deployment_Node(db, "Database Server", "Linux", "PostgreSQL"){
+        ContainerDb(database, "Database", "PostgreSQL", "Database")
+    }
+
+    Rel(webapp, appserver, "Deploys")
+    Rel(appserver, database, "Connects to")
+```
+
+### Example (With Enterprise Boundary)
+
+```mermaid
+C4Context
+    title System Context with Boundaries
+
+    Person(customer, "Customer", "A customer")
+    Enterprise_Boundary(c1, "Customer Enterprise") {
+        System(crm, "CRM System", "Customer management")
+    }
+    Enterprise_Boundary(c2, "Provider Enterprise") {
+        System(webapp, "Web Application", "Main application")
+        SystemDb(database, "Database", "Data storage")
+    }
+
+    Rel(customer, crm, "Uses")
+    Rel(crm, webapp, "Sends data to")
+    Rel(webapp, database, "Uses")
+```
+
+### Example (With Bidirectional Relationship)
+
+```mermaid
+C4Context
+    title System Context with BiRel
+
+    System(systemA, "System A", "First system")
+    System(systemB, "System B", "Second system")
+
+    BiRel(systemA, systemB, "Communicates with", "REST API")
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If C4 diagrams are not supported, use this flowchart alternative:
+
+```mermaid
+flowchart TD
+    Customer[Customer]
+    WebApp[Web Application]
+    Database[(Database)]
+    Email[Email System]
+
+    Customer -->|Uses| WebApp
+    WebApp -->|Reads/Writes| Database
+    WebApp -->|Sends| Email
+```

skills/mermaid/examples/class.md

@@ -1,22 +1,39 @@
 ## Instructions
 
-Class diagrams represent the structure of a system by showing classes, their attributes, methods, and relationships.
+Class diagrams represent the structure of a system by showing classes, their attributes, methods, and relationships. In software engineering, a class diagram in the Unified Modeling Language (UML) is a type of static structure diagram that describes the structure of a system by showing the system's classes, their attributes, operations (or methods), and the relationships among objects.
 
 ### Syntax
 
 - Use `classDiagram` keyword
-- Class definition: `class ClassName { }`
-- Attributes: `+public`, `-private`, `#protected`
-- Methods: `+methodName()`, `-privateMethod()`
+- Class definition: `class ClassName` or via relationship `Vehicle <|-- Car`
+- Members: `ClassName : +attribute` or `ClassName { +attribute +method() }`
+- Visibility: `+` (Public), `-` (Private), `#` (Protected), `~` (Package/Internal)
+- Methods: Identified by `()` parentheses
+- Return types: `method() ReturnType` (space between `)` and return type)
+- Generic types: `ClassName~Type~` (enclosed in `~` tilde)
+- Classifiers: `*` (Abstract), `$` (Static)
 - Relationships:
   - `<|--` - Inheritance
   - `*--` - Composition
   - `o--` - Aggregation
   - `-->` - Association
+  - `--` - Link (Solid)
   - `..>` - Dependency
-- Interfaces: `<<interface>>` or `<<Interface>>`
+  - `..|>` - Realization
+  - `..` - Link (Dashed)
+- Labels: `ClassA --> ClassB : LabelText`
+- Cardinality: `"1" ClassA --> "0..1" ClassB : LabelText`
+- Annotations: `<<Interface>>`, `<<Abstract>>`, `<<Service>>`, `<<Enumeration>>`
+- Interfaces: `ClassA ..|> InterfaceName` or lollipop syntax
+- Namespaces: `namespace NamespaceName { Class1 Class2 }`
+- Direction: `direction TB|BT|LR|RL` (default: TB)
+- Comments: `%% comment` (on separate line)
+- Notes: `note for ClassName "note text"`
+- Styling: `style ClassName fill:#color,stroke:#color` or `classDef className fill:#color` and `cssClass "ClassName" className` or `ClassName:::className`
 
-### Example
+Reference: [Mermaid Class Diagram Documentation](https://mermaid.ai/open-source/syntax/classDiagram.html)
+
+### Example (Basic Class Diagram)
 
 ```mermaid
 classDiagram
@@ -33,7 +50,237 @@ classDiagram
     class Cat {
         +meow()
     }
-    
+
     Animal <|-- Dog
     Animal <|-- Cat
 ```
+
+### Example (With Visibility and Methods)
+
+```mermaid
+classDiagram
+    class BankAccount {
+        -double balance
+        +deposit(amount)
+        +withdraw(amount) double
+        +getBalance() double
+    }
+    class Customer {
+        +String name
+        +String email
+        +openAccount() BankAccount
+    }
+
+    Customer --> BankAccount : owns
+```
+
+### Example (With Return Types)
+
+```mermaid
+classDiagram
+    class Calculator {
+        +add(a, b) int
+        +subtract(a, b) int
+        +multiply(a, b) int
+        +divide(a, b) double
+    }
+```
+
+### Example (With Generic Types)
+
+```mermaid
+classDiagram
+    class List~T~ {
+        +add(item T)
+        +get(index) T
+        +size() int
+    }
+    class Map~K,V~ {
+        +put(key K, value V)
+        +get(key K) V
+    }
+```
+
+### Example (With Relationships)
+
+```mermaid
+classDiagram
+    class Vehicle {
+        +String brand
+        +start()
+    }
+    class Car {
+        +int doors
+    }
+    class Engine {
+        +int horsepower
+    }
+    class Wheel {
+        +int size
+    }
+
+    Vehicle <|-- Car
+    Car *-- Engine
+    Car o-- Wheel
+```
+
+### Example (With Labels and Cardinality)
+
+```mermaid
+classDiagram
+    class Company {
+        +String name
+    }
+    class Employee {
+        +String name
+        +String position
+    }
+
+    Company "1" --> "1..*" Employee : employs
+```
+
+### Example (With Interfaces)
+
+```mermaid
+classDiagram
+    class Shape {
+        <<interface>>
+        +area() double
+        +perimeter() double
+    }
+    class Circle {
+        +double radius
+        +area() double
+        +perimeter() double
+    }
+    class Rectangle {
+        +double width
+        +double height
+        +area() double
+        +perimeter() double
+    }
+
+    Shape <|.. Circle
+    Shape <|.. Rectangle
+```
+
+### Example (With Annotations)
+
+```mermaid
+classDiagram
+    class UserService {
+        <<Service>>
+        +createUser()
+        +deleteUser()
+    }
+    class AbstractRepository {
+        <<Abstract>>
+        +save()
+        +find()*
+    }
+    class Status {
+        <<Enumeration>>
+        ACTIVE
+        INACTIVE
+        PENDING
+    }
+```
+
+### Example (With Namespaces)
+
+```mermaid
+classDiagram
+    namespace Core {
+        class User
+        class Product
+    }
+    namespace Services {
+        class UserService
+        class ProductService
+    }
+
+    User --> UserService
+    Product --> ProductService
+```
+
+### Example (With Direction - Left to Right)
+
+```mermaid
+classDiagram
+    direction LR
+    class Animal {
+        +String name
+        +eat()
+    }
+    class Dog {
+        +bark()
+    }
+    Animal <|-- Dog
+```
+
+### Example (With Styling)
+
+```mermaid
+classDiagram
+    class User {
+        +String name
+        +String email
+    }
+    class Admin {
+        +String role
+    }
+    User <|-- Admin
+
+    classDef userClass fill:#e1f5ff,stroke:#333,stroke-width:2px;
+    classDef adminClass fill:#ff6b6b,stroke:#333,stroke-width:3px;
+
+    cssClass "User" userClass;
+    cssClass "Admin" adminClass;
+```
+
+### Example (Complex Class Diagram)
+
+```mermaid
+classDiagram
+    class Person {
+        +String name
+        +int age
+        +walk()
+    }
+    class Student {
+        +int studentId
+        +study()
+    }
+    class Teacher {
+        +String subject
+        +teach()
+    }
+    class Course {
+        +String title
+        +int credits
+    }
+    class Enrollment {
+        +date enrolledDate
+        +String grade
+    }
+
+    Person <|-- Student
+    Person <|-- Teacher
+    Student "1..*" --> "0..*" Course : enrolls
+    Course "1" --> "0..*" Enrollment : has
+    Student "1" --> "0..*" Enrollment : receives
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If class diagrams are not supported, use this flowchart alternative:
+
+```mermaid
+flowchart TD
+    Animal[Animal]
+    Dog[Dog]
+    Cat[Cat]
+
+    Animal -->|inherits| Dog
+    Animal -->|inherits| Cat
+```

skills/mermaid/examples/er.md

@@ -1,46 +1,212 @@
 ## Instructions
 
-Entity Relationship (ER) diagrams model the structure of a database by showing entities, their attributes, and relationships between them.
+Entity Relationship (ER) diagrams represent the structure of a database, showing entities, their attributes, and relationships between them. An entity–relationship model (or ER model) describes interrelated things of interest in a specific domain of knowledge. A basic ER model is composed of entity types (which classify the things of interest) and specifies relationships that can exist between entities (instances of those entity types).
 
 ### Syntax
 
 - Use `erDiagram` keyword
-- Entities: `ENTITY_NAME { }`
-- Attributes: `type attribute_name`
-- Relationships: `ENTITY1 ||--o{ ENTITY2 : "relationship_label"`
-- Cardinality:
-  - `||--o{` - One to many
-  - `||--||` - One to one
-  - `}o--o{` - Many to many
-  - `||--o|` - One to zero or one
-  - `}o--||` - Many to one
+- Entities: `ENTITY_NAME { }` or `ENTITY_NAME { type name }` (with attributes)
+- Relationships: `<first-entity> [<relationship> <second-entity> : <relationship-label>]`
+- Cardinality markers:
+  - `||` - Exactly one
+  - `|o` - Zero or one
+  - `}|` - One or more
+  - `}o` - Zero or more
+- Relationship types:
+  - `--` - Identifying relationship (solid line)
+  - `..` - Non-identifying relationship (dashed line)
+- Aliases: `one or zero`, `zero or one`, `one or more`, `one or many`, `many(1)`, `1+`, `zero or more`, `zero or many`, `many(0)`, `0+`, `only one`, `1`, `to`, `optionally to`
+- Attributes: `type name` or `*type name` (asterisk for primary key)
+- Attribute keys: `PK` (Primary Key), `FK` (Foreign Key), `UK` (Unique Key)
+- Comments: Double quotes at the end of attribute: `type name "comment"`
+- Entity aliases: `ENTITY_NAME[alias]` (alias shown instead of entity name)
+- Direction: `direction TB|BT|LR|RL` (default: TB)
+- Styling: `style entityId fill:#color,stroke:#color` or `classDef className fill:#color`
+- Unicode and Markdown: Supported in entity names, relationships, and attributes
 
-### Example
+Reference: [Mermaid Entity Relationship Diagram Documentation](https://mermaid.ai/open-source/syntax/entityRelationshipDiagram.html)
+
+### Example (Basic ER Diagram)
 
 ```mermaid
 erDiagram
     CUSTOMER ||--o{ ORDER : places
-    ORDER ||--|{ ORDER_LINE : contains
-    PRODUCT ||--o{ ORDER_LINE : "ordered in"
-    
+    ORDER ||--|{ LINE-ITEM : contains
+    PRODUCT ||--|{ LINE-ITEM : "ordered in"
+```
+
+### Example (With Attributes)
+
+```mermaid
+erDiagram
     CUSTOMER {
-        int customer_id PK
+        int id PK
         string name
-        string email
+        string email UK
+        string phone
     }
     ORDER {
-        int order_id PK
-        date order_date
-        int customer_id FK
+        int id PK
+        date orderDate
+        decimal total
+        int customerId FK
     }
     PRODUCT {
-        int product_id PK
+        int id PK
         string name
         decimal price
+        int stock
+    }
+    CUSTOMER ||--o{ ORDER : places
+    ORDER ||--|{ LINE-ITEM : contains
+    PRODUCT ||--|{ LINE-ITEM : "ordered in"
+```
+
+### Example (With Relationship Labels)
+
+```mermaid
+erDiagram
+    PROPERTY ||--|{ ROOM : contains
+    ROOM ||--o{ WINDOW : has
+    BUILDING ||--o{ PROPERTY : "located in"
+```
+
+### Example (Identifying vs Non-identifying)
+
+```mermaid
+erDiagram
+    PERSON }|..|{ CAR : "driver"
+    PERSON ||--o{ NAMED-DRIVER : "is"
+    CAR ||--o{ NAMED-DRIVER : "drives"
+```
+
+### Example (With Aliases)
+
+```mermaid
+erDiagram
+    CUSTOMER[Cust] ||--o{ ORDER[Ord] : places
+    ORDER ||--|{ LINE-ITEM[Item] : contains
+    PRODUCT[Prod] ||--|{ LINE-ITEM : "ordered in"
+```
+
+### Example (With Attribute Comments)
+
+```mermaid
+erDiagram
+    USER {
+        int id PK "Unique identifier"
+        string username UK "Login name"
+        string email "Contact email"
+        date createdAt "Account creation date"
+    }
+    POST {
+        int id PK
+        string title
+        text content
+        int userId FK "Author reference"
+        date publishedAt
+    }
+    USER ||--o{ POST : "writes"
+```
+
+### Example (With Direction - Left to Right)
+
+```mermaid
+erDiagram
+    direction LR
+    CUSTOMER ||--o{ ORDER : places
+    ORDER ||--|{ LINE-ITEM : contains
+    PRODUCT ||--|{ LINE-ITEM : "ordered in"
+```
+
+### Example (With Styling)
+
+```mermaid
+erDiagram
+    CUSTOMER {
+        int id PK
+        string name
+        string email
+    }
+    ORDER {
+        int id PK
+        date orderDate
+        decimal total
+    }
+    CUSTOMER ||--o{ ORDER : places
+
+    style CUSTOMER fill:#e1f5,stroke:#333,stroke-width:2px
+    style ORDER fill:#fff4e1,stroke:#333,stroke-width:2px
+```
+
+### Example (With Class Definitions)
+
+```mermaid
+erDiagram
+    CUSTOMER {
+        int id PK
+        string name
     }
-    ORDER_LINE {
-        int order_id FK
-        int product_id FK
-        int quantity
+    ORDER {
+        int id PK
+        date orderDate
     }
+    CUSTOMER ||--o{ ORDER : places
+
+    classDef customerClass fill:#e1f5,stroke:#333,stroke-width:2px
+    classDef orderClass fill:#fff4e1,stroke:#333,stroke-width:2px
+
+    class CUSTOMER customerClass
+    class ORDER orderClass
+```
+
+### Example (Complex Database Schema)
+
+```mermaid
+erDiagram
+    USER {
+        int id PK
+        string username UK
+        string email
+        date createdAt
+    }
+    POST {
+        int id PK
+        string title
+        text content
+        int authorId FK
+        date publishedAt
+    }
+    COMMENT {
+        int id PK
+        text content
+        int postId FK
+        int userId FK
+        date createdAt
+    }
+    CATEGORY {
+        int id PK
+        string name
+        string slug UK
+    }
+    USER ||--o{ POST : "writes"
+    POST ||--o{ COMMENT : "has"
+    USER ||--o{ COMMENT : "makes"
+    CATEGORY ||--o{ POST : "categorizes"
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If ER diagrams are not supported, use this flowchart alternative:
+
+```mermaid
+flowchart TD
+    CUSTOMER[Customer]
+    ORDER[Order]
+    PRODUCT[Product]
+    LINE_ITEM[Line Item]
+
+    CUSTOMER -->|places| ORDER
+    ORDER -->|contains| LINE_ITEM
+    PRODUCT -->|ordered in| LINE_ITEM
 ```

skills/mermaid/examples/flowchart.md

@@ -1,27 +1,271 @@
 ## Instructions
 
-Flowcharts are used to visualize processes, workflows, and decision trees. They show the flow of control or data through a system.
+Flowcharts are composed of nodes (geometric shapes) and edges (arrows or lines). The Mermaid code defines how nodes and edges are made and accommodates different arrow types, multi-directional arrows, and any linking to and from subgraphs.
 
 ### Syntax
 
 - Use `flowchart` or `graph` keyword
-- Direction indicators: `TD` (top-down), `BT` (bottom-top), `LR` (left-right), `RL` (right-left)
+- Direction: `TD`/`TB` (Top to Bottom), `BT` (Bottom to Top), `RL` (Right to Left), `LR` (Left to Right)
 - Node shapes:
-  - `[text]` - Rectangle
-  - `(text)` - Rounded rectangle
-  - `{text}` - Diamond (decision)
-  - `((text))` - Circle
-  - `>text]` - Asymmetric shape
-- Connections: `-->` (arrow), `---` (line), `-.->` (dotted arrow)
-- Labels on connections: `-->|label|` or `-->|"label"|`
+  - Default: `A` or `A["Text"]`
+  - Round edges: `A("Text")`
+  - Stadium: `A(["Text"])`
+  - Subroutine: `A[["Text"]]`
+  - Cylindrical: `A[("Text")]`
+  - Circle: `A(("Text"))`
+  - Asymmetric: `A>"Text"]`
+  - Rhombus: `A{"Text"}`
+  - Hexagon: `A{{"Text"}}`
+  - Parallelogram: `A[/"Text"/]` or `A[\"Text"/]`
+  - Parallelogram alt: `A[/"Text"\]` or `A[\"Text"\`
+  - Trapezoid: `A[/"Text"\]` or `A[\"Text"\`
+  - Trapezoid alt: `A[/"Text"/]` or `A[\"Text"/]`
+  - Double circle: `A((("Text")))`
+  - New shapes (v11.3.0+): `A@{ shape: shapeName }` (e.g., `bang`, `cloud`, `diamond`, `cylinder`, etc.)
+- Edges:
+  - `A --> B` - Arrow with arrowhead
+  - `A --- B` - Open link
+  - `A -->|label| B` - Link with label
+  - `A -.-> B` - Dotted link
+  - `A -.->|label| B` - Dotted link with label
+  - `A ==> B` - Thick link
+  - `A ==|label|==> B` - Thick link with label
+- Subgraphs: `subgraph id ["Title"] ... end`
+- Styling: `style A fill:#color,stroke:#color` or `classDef className fill:#color` and `class A className` or `A:::className`
+- Links: `linkStyle 0 stroke:#color` (0-based index)
+- Comments: `%% comment` (on separate line)
+- FontAwesome icons: `A[fa:fa-icon-name]`
+- Custom icons: `A[fak:fa-custom-icon-name]` (requires FontAwesome kit)
+- Click events: `click A callback "tooltip"` or `click A href "url" "tooltip"`
+- Line curves: `curve: basis|bumpX|bumpY|cardinal|catmullRom|linear|monotoneX|monotoneY|natural|step|stepAfter|stepBefore`
+- Edge IDs (v11.10.0+): `A -->|label|e1[ID] B` then `e1.curve = "stepBefore"`
 
-### Example
+**Warnings:**
+- If using "end" in a node, capitalize it (e.g., "End" or "END")
+- If using "o" or "x" as first letter, add space or capitalize (e.g., "dev--- ops" or "dev---Ops")
+
+Reference: [Mermaid Flowchart Documentation](https://mermaid.ai/open-source/syntax/flowchart.html)
+
+### Example (Basic Flowchart)
+
+```mermaid
+flowchart TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Process]
+    B -->|No| D[End]
+    C --> D
+```
+
+### Example (With Different Directions)
+
+```mermaid
+flowchart LR
+    A[Start] --> B[Process] --> C[End]
+```
+
+### Example (With Node Shapes)
+
+```mermaid
+flowchart TD
+    A[Rectangle]
+    B("Rounded")
+    C(["Stadium"])
+    D[["Subroutine"]]
+    E[("Cylindrical")]
+    F(("Circle"))
+    G>"Asymmetric"]
+    H{"Diamond"}
+    I{{"Hexagon"}}
+    J[/"Parallelogram"/]
+    K[\"Parallelogram Alt"\]
+    L[/"Trapezoid"\]
+    M[\"Trapezoid Alt"/]
+    N((("Double Circle")))
+```
+
+### Example (With Labels on Edges)
+
+```mermaid
+flowchart TD
+    A[Start] -->|Step 1| B[Process 1]
+    B -->|Step 2| C[Process 2]
+    C -->|Step 3| D[End]
+```
+
+### Example (With Subgraphs)
+
+```mermaid
+flowchart TD
+    A[Start] --> B[Process]
+    B --> C[End]
+
+    subgraph SG1 ["Subgraph 1"]
+        D[Node D]
+        E[Node E]
+        D --> E
+    end
+
+    subgraph SG2 ["Subgraph 2"]
+        F[Node F]
+        G[Node G]
+        F --> G
+    end
+
+    B --> D
+    E --> F
+    G --> C
+```
+
+### Example (With Styling)
+
+```mermaid
+flowchart TD
+    A[Start] --> B[Process]
+    B --> C[End]
+
+    style A fill:#e1f5,stroke:#333,stroke-width:2px
+    style B fill:#bbf,stroke:#333,stroke-width:2px
+    style C fill:#bfb,stroke:#333,stroke-width:2px
+```
+
+### Example (With Class Definitions)
+
+```mermaid
+flowchart TD
+    A[Start] --> B[Process]
+    B --> C[End]
+
+    classDef startEnd fill:#e1f5,stroke:#333,stroke-width:2px
+    classDef process fill:#bbf,stroke:#333,stroke-width:2px
+
+    class A,C startEnd
+    class B process
+```
+
+### Example (With Class Shorthand)
+
+```mermaid
+flowchart TD
+    A[Start]:::startClass --> B[Process]:::processClass
+    B --> C[End]:::endClass
+
+    classDef startClass fill:#e1f5,stroke:#333
+    classDef processClass fill:#bbf,stroke:#333
+    classDef endClass fill:#bfb,stroke:#333
+```
+
+### Example (With Dotted Links)
 
 ```mermaid
 flowchart TD
-    A[Start] --> B{Decision?}
-    B -->|Yes| C[Process A]
-    B -->|No| D[Process B]
-    C --> E[End]
-    D --> E
+    A[Start] --> B[Process]
+    A -.-> C[Alternative]
+    B -.->|Optional| D[End]
+    C -.-> D
+```
+
+### Example (With Thick Links)
+
+```mermaid
+flowchart TD
+    A[Start] ==> B[Important Process]
+    B ==>|Critical| C[End]
+```
+
+### Example (With FontAwesome Icons)
+
+```mermaid
+flowchart TD
+    A[fa:fa-user Start]
+    B[fa:fa-cog Process]
+    C[fa:fa-check End]
+
+    A --> B --> C
+```
+
+### Example (Complex Flowchart)
+
+```mermaid
+flowchart TD
+    Start([Start]) --> Input{Input Data?}
+    Input -->|Yes| Validate[Validate Data]
+    Input -->|No| End([End])
+
+    Validate --> Check{Valid?}
+    Check -->|Yes| Process[Process Data]
+    Check -->|No| Error[Error Handler]
+
+    Process --> Save[Save Results]
+    Save --> End
+    Error --> End
+
+    style Start fill:#e1f5,stroke:#333
+    style End fill:#e1f5,stroke:#333
+    style Process fill:#bbf,stroke:#333
+    style Error fill:#fbb,stroke:#333
+```
+
+### Example (With Multiple Paths)
+
+```mermaid
+flowchart TD
+    A[Start] --> B{Decision 1}
+    B -->|Path 1| C[Process 1]
+    B -->|Path 2| D[Process 2]
+    B -->|Path 3| E[Process 3]
+
+    C --> F[Converge]
+    D --> F
+    E --> F
+    F --> G[End]
+```
+
+### Example (With Comments)
+
+```mermaid
+flowchart TD
+    A[Start] --> B[Process]
+    %% This is a comment
+    B --> C[End]
+```
+
+### Example (With Edge Styling)
+
+```mermaid
+flowchart TD
+    A[Start] --> B[Process 1]
+    B --> C[Process 2]
+    C --> D[End]
+
+    linkStyle 0 stroke:#ff3,stroke-width:4px
+    linkStyle 1 stroke:#3f3,stroke-width:2px
+    linkStyle 2 stroke:#33f,stroke-width:3px
+```
+
+### Example (With New Shapes - v11.3.0+)
+
+```mermaid
+flowchart TD
+    A@{ shape: cloud, label: "Cloud" }
+    B@{ shape: diam, label: "Decision" }
+    C@{ shape: cyl, label: "Database" }
+    D@{ shape: bang, label: "Event" }
+
+    A --> B
+    B --> C
+    C --> D
+```
+
+### Example (With Edge IDs and Curve Styles - v11.10.0+)
+
+```mermaid
+flowchart LR
+    A[Start]
+    B[Process]
+    C[End]
+    A e1@-->|Step 1| B
+    B e2@-->|Step 2| C
+
+    e1@{ curve: stepBefore }
+    e2@{ curve: stepAfter }
 ```

skills/mermaid/examples/gantt.md

@@ -1,22 +1,35 @@
 ## Instructions
 
-Gantt charts display project schedules, showing tasks, their durations, and dependencies over time.
+Gantt charts display project schedules, showing tasks, their durations, and dependencies over time. A Gantt chart is a type of bar chart that illustrates a project schedule and the amount of time it would take for any one project to finish. Gantt charts illustrate number of days between the start and finish dates of the terminal elements and summary elements of a project.
 
 ### Syntax
 
 - Use `gantt` keyword
-- Title: `title Project Title`
-- Date format: `dateFormat YYYY-MM-DD`
-- Sections: `section Section Name`
-- Tasks: `Task Name :crit, milestone, done, active, task_id, start_date, end_date`
-- Status:
-  - `done` - Completed
-  - `active` - In progress
-  - `crit` - Critical path
-  - `milestone` - Milestone marker
-- Dependencies: `after task_id, duration`
+- Date format: `dateFormat YYYY-MM-DD` (required)
+- Title: `title Project Title` (optional)
+- Sections: `section Section Name` (required for grouping tasks)
+- Tasks: `Task Name :[tags], [taskID], [startDate], [endDate|duration]`
+- Tags: `active`, `done`, `crit`, `milestone` (optional, must be first)
+- Task metadata syntax:
+  - `Task Name :[tags], taskID, startDate, endDate`
+  - `Task Name :[tags], taskID, startDate, duration`
+  - `Task Name :[tags], taskID, after otherTaskID, endDate`
+  - `Task Name :[tags], taskID, after otherTaskID, duration`
+  - `Task Name :[tags], startDate, endDate` (no ID)
+  - `Task Name :[tags], startDate, duration` (no ID)
+  - `Task Name :[tags], after otherTaskID, endDate` (no ID)
+  - `Task Name :[tags], endDate` (no ID, sequential)
+  - `Task Name :[tags], duration` (no ID, sequential)
+- Excludes: `excludes dates` (optional) - excludes specific dates, days, or weekends
+- Weekend: `weekend friday` or `weekend saturday` (v11.0.0+, optional)
+- Milestones: Use `milestone` tag
+- Comments: `%% comment` (on separate line)
+- Tick interval: `tickInterval 1day|1week|1month` (v10.3.0+)
+- Weekday: `weekday sunday|monday|...` (for week-based intervals)
 
-### Example
+Reference: [Mermaid Gantt Chart Documentation](https://mermaid.ai/open-source/syntax/gantt.html)
+
+### Example (Basic Gantt Chart)
 
 ```mermaid
 gantt
@@ -29,3 +42,118 @@ gantt
     Testing :test1, after dev1, 10d
     Deployment :milestone, deploy1, after test1, 1d
 ```
+
+### Example (With Task IDs and Dependencies)
+
+```mermaid
+gantt
+    title Project Schedule
+    dateFormat YYYY-MM-DD
+    section Design
+    Requirements :req1, 2024-01-01, 2024-01-10
+    Design Phase :des1, after req1, 2024-01-25
+    section Development
+    Frontend :front1, after des1, 20d
+    Backend :back1, after des1, 25d
+    section Testing
+    Integration Testing :test1, after front1 back1, 10d
+    Deployment :milestone, deploy1, after test1, 1d
+```
+
+### Example (With Tags)
+
+```mermaid
+gantt
+    title Project with Tags
+    dateFormat YYYY-MM-DD
+    section Tasks
+    Completed Task :done, task1, 2024-01-01, 2024-01-10
+    Active Task :active, task2, 2024-01-11, 2024-01-25
+    Critical Task :crit, task3, 2024-01-26, 2024-02-10
+    Milestone :milestone, milestone1, 2024-02-11, 0d
+```
+
+### Example (With Excludes)
+
+```mermaid
+gantt
+    title Project with Exclusions
+    dateFormat YYYY-MM-DD
+    excludes weekends
+    section Development
+    Task 1 :task1, 2024-01-01, 10d
+    Task 2 :task2, after task1, 10d
+```
+
+### Example (With Weekend Configuration)
+
+```mermaid
+gantt
+    title Project with Custom Weekend
+    dateFormat YYYY-MM-DD
+    excludes weekends
+    weekend friday
+    section Development
+    Task 1 :task1, 2024-01-01, 10d
+    Task 2 :task2, after task1, 10d
+```
+
+### Example (With Tick Interval)
+
+```mermaid
+gantt
+    title Project Timeline
+    dateFormat YYYY-MM-DD
+    tickInterval 1week
+    weekday monday
+    section Phase 1
+    Design :des1, 2024-01-01, 2024-01-15
+    Development :dev1, after des1, 20d
+```
+
+### Example (Sequential Tasks)
+
+```mermaid
+gantt
+    title Sequential Tasks
+    dateFormat YYYY-MM-DD
+    section Phase 1
+    Task A :2024-01-01, 5d
+    Task B :5d
+    Task C :10d
+    section Phase 2
+    Task D :after Task C, 7d
+```
+
+### Example (Complex Project)
+
+```mermaid
+gantt
+    title Software Development Project
+    dateFormat YYYY-MM-DD
+    excludes weekends
+    section Planning
+    Requirements Gathering :done, req1, 2024-01-01, 2024-01-10
+    System Design :done, des1, after req1, 2024-01-20
+    section Development
+    Frontend Development :active, front1, after des1, 30d
+    Backend Development :active, back1, after des1, 35d
+    Database Setup :db1, after des1, 10d
+    section Testing
+    Unit Testing :test1, after front1 back1, 15d
+    Integration Testing :test2, after test1, 10d
+    section Deployment
+    Production Deployment :milestone, deploy1, after test2, 1d
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If Gantt charts are not supported, use this flowchart alternative:
+
+```mermaid
+flowchart LR
+    Start[Project Start] --> Phase1[Phase 1: Design]
+    Phase1 --> Phase2[Phase 2: Development]
+    Phase2 --> Phase3[Phase 3: Testing]
+    Phase3 --> End[Deployment]
+```

skills/mermaid/examples/gitgraph.md

@@ -1,27 +1,174 @@
 ## Instructions
 
-Git graphs visualize Git branching structures and commit history, showing how branches diverge and merge.
+Git graphs visualize Git branching structures and commit history, showing how branches diverge and merge. A Git Graph is a pictorial representation of git commits and git actions (commands) on various branches. These diagrams are particularly helpful to developers and devops teams to share their Git branching strategies.
 
 ### Syntax
 
 - Use `gitGraph` keyword
-- Options: `options { "key": "value" }`
-- Commits: `commit id: "message"`
-- Branches: `branch branchName`, `checkout branchName`
-- Merges: `merge branchName`
-- Cherry-pick: `cherry-pick commitId`
+- Default branch: `main` (formerly `master`) - initialized automatically
+- Commits: `commit id: "message"` or `commit` (auto-generated ID)
+- Commit types: `NORMAL` (default), `REVERSE`, `HIGHLIGHT`
+- Commit attributes: `id: "custom_id"`, `type: HIGHLIGHT`, `tag: "v1.0"`
+- Branches: `branch branchName` (creates and switches to new branch)
+- Checkout: `checkout branchName` or `switch branchName` (switches to existing branch)
+- Merge: `merge branchName` (merges branch into current branch)
+- Cherry-pick: `cherry-pick commitId` (applies commit to current branch)
+- Orientation: `LR:` (Left-to-Right, default), `TB:` (Top-to-Bottom), `BT:` (Bottom-to-Top, v11.0.0+)
+- Options: `mainBranchName`, `mainBranchOrder`, `parallelCommits`
 
-### Example
+Reference: [Mermaid GitGraph Documentation](https://mermaid.ai/open-source/syntax/gitgraph.html)
+
+### Example (Basic GitGraph)
+
+```mermaid
+gitGraph
+    commit id: "Initial commit"
+    commit id: "Add feature A"
+    commit id: "Add feature B"
+```
+
+### Example (With Branches)
 
 ```mermaid
 gitGraph
     commit id: "Initial commit"
+    commit id: "Update README"
     branch develop
     checkout develop
     commit id: "Add feature A"
     commit id: "Add feature B"
     checkout main
-    commit id: "Update README"
+    commit id: "Fix bug"
+    merge develop
+    commit id: "Release v1.0"
+```
+
+### Example (With Commit Types)
+
+```mermaid
+gitGraph
+    commit id: "Initial commit" type: NORMAL
+    commit id: "Add feature" type: HIGHLIGHT
+    commit id: "Revert change" type: REVERSE
+    commit id: "Final commit" type: NORMAL
+```
+
+### Example (With Tags)
+
+```mermaid
+gitGraph
+    commit id: "Initial commit"
+    commit id: "Add feature A" tag: "v0.1"
+    commit id: "Add feature B"
+    commit id: "Release" tag: "v1.0"
+```
+
+### Example (Complex Branching)
+
+```mermaid
+gitGraph
+    commit id: "Initial commit"
+    branch develop
+    checkout develop
+    commit id: "Add feature A"
+    branch feature-branch
+    checkout feature-branch
+    commit id: "Work on feature"
+    checkout develop
+    commit id: "Add feature B"
+    checkout main
+    commit id: "Update docs"
     merge develop
     commit id: "Release v1.0"
+    checkout feature-branch
+    commit id: "Complete feature"
+    checkout develop
+    merge feature-branch
+```
+
+### Example (With Cherry-pick)
+
+```mermaid
+gitGraph
+    commit id: "Initial commit"
+    branch develop
+    checkout develop
+    commit id: "Add feature A"
+    commit id: "Add feature B"
+    checkout main
+    commit id: "Hotfix"
+    cherry-pick "Add feature A"
+    commit id: "Release"
+```
+
+### Example (Top-to-Bottom Orientation)
+
+```mermaid
+gitGraph TB:
+    commit id: "Initial commit"
+    branch develop
+    checkout develop
+    commit id: "Add feature A"
+    checkout main
+    merge develop
+```
+
+### Example (Bottom-to-Top Orientation - v11.0.0+)
+
+```mermaid
+gitGraph BT:
+    commit id: "Initial commit"
+    branch develop
+    checkout develop
+    commit id: "Add feature A"
+    checkout main
+    merge develop
+```
+
+### Example (With Custom Main Branch Name)
+
+```mermaid
+gitGraph:
+    options:
+        mainBranchName: "production"
+    commit id: "Initial commit"
+    branch develop
+    checkout develop
+    commit id: "Add feature"
+```
+
+### Example (Git Flow Strategy)
+
+```mermaid
+gitGraph
+    commit id: "Initial commit"
+    branch develop
+    checkout develop
+    commit id: "Setup project"
+    branch feature/login
+    checkout feature/login
+    commit id: "Add login form"
+    commit id: "Add validation"
+    checkout develop
+    merge feature/login
+    commit id: "Merge login feature"
+    branch release/v1.0
+    checkout release/v1.0
+    commit id: "Prepare release"
+    checkout main
+    merge release/v1.0
+    commit id: "Release v1.0" tag: "v1.0"
+    checkout develop
+    merge release/v1.0
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If GitGraph diagrams are not supported, use this flowchart alternative:
+
+```mermaid
+flowchart TD
+    C1[Initial commit] --> C2[Add feature A]
+    C2 --> C3[Add feature B]
+    C3 --> C4[Release v1.0]
 ```

skills/mermaid/examples/journey.md

@@ -1,17 +1,19 @@
 ## Instructions
 
-User journey diagrams visualize the experience of a user as they interact with a system or service, showing different stages and touchpoints.
+User journey diagrams visualize the experience of a user as they interact with a system or service, showing different stages and touchpoints. User journeys describe at a high level of detail exactly what steps different users take to complete a specific task within a system, application or website. This technique shows the current (as-is) user workflow, and reveals areas of improvement for the to-be workflow.
 
 ### Syntax
 
 - Use `journey` keyword
-- Title: `title Title Text`
-- Sections: `section Section Name`
+- Title: `title Title Text` (optional)
+- Sections: `section Section Name` (groups steps into stages)
 - Steps: `Step Name: Score: Actor1, Actor2`
-- Score: 1-5 (satisfaction level)
-- Actors: Who performs the step
+- Score: Number between 1 and 5 (inclusive) - represents satisfaction level
+- Actors: Comma-separated list of actors who perform the step
 
-### Example
+Reference: [Mermaid User Journey Documentation](https://mermaid.ai/open-source/syntax/userJourney.html)
+
+### Example (Basic User Journey)
 
 ```mermaid
 journey
@@ -29,3 +31,123 @@ journey
       Shipping: 4: Logistics
       Receive Product: 5: User
 ```
+
+### Example (Simple Journey)
+
+```mermaid
+journey
+    title Daily Workflow
+    section Morning
+      Wake Up: 3: User
+      Breakfast: 4: User
+      Commute: 2: User
+    section Work
+      Check Email: 3: User
+      Meetings: 4: User, Team
+      Lunch: 5: User
+    section Evening
+      Exercise: 5: User
+      Dinner: 5: User
+      Sleep: 4: User
+```
+
+### Example (Product Onboarding)
+
+```mermaid
+journey
+    title New User Onboarding
+    section Sign Up
+      Create Account: 4: User
+      Verify Email: 3: User, System
+      Complete Profile: 3: User
+    section First Use
+      Tutorial: 4: User, System
+      First Task: 4: User
+      Get Help: 3: User, Support
+    section Engagement
+      Daily Usage: 5: User
+      Share with Friends: 4: User
+      Upgrade Plan: 3: User, Sales
+```
+
+### Example (Customer Support Journey)
+
+```mermaid
+journey
+    title Customer Support Experience
+    section Issue Discovery
+      Notice Problem: 2: Customer
+      Search Help: 3: Customer
+      Contact Support: 3: Customer
+    section Resolution
+      Describe Issue: 3: Customer, Support Agent
+      Troubleshooting: 4: Customer, Support Agent
+      Solution Provided: 5: Support Agent
+    section Follow-up
+      Issue Resolved: 5: Customer
+      Feedback: 4: Customer
+      Close Ticket: 5: Support Agent
+```
+
+### Example (E-commerce Purchase)
+
+```mermaid
+journey
+    title Online Shopping Experience
+    section Discovery
+      Browse Catalog: 5: Customer
+      Search Product: 4: Customer
+      Compare Options: 4: Customer
+    section Decision
+      Read Reviews: 5: Customer
+      Check Price: 4: Customer
+      Add to Wishlist: 4: Customer
+    section Purchase
+      Add to Cart: 4: Customer
+      Apply Discount: 5: Customer
+      Checkout: 3: Customer
+      Payment: 4: Customer, Payment Gateway
+    section Post-Purchase
+      Order Confirmation: 5: System
+      Track Shipment: 4: Customer
+      Receive Product: 5: Customer
+      Leave Review: 4: Customer
+```
+
+### Example (App Installation)
+
+```mermaid
+journey
+    title Mobile App Installation
+    section Discovery
+      Find App: 4: User
+      Read Description: 3: User
+      Check Reviews: 5: User
+    section Installation
+      Download: 4: User, App Store
+      Install: 3: User, Device
+      Open App: 4: User
+    section Setup
+      Permissions: 2: User, Device
+      Account Creation: 3: User
+      Initial Configuration: 4: User
+    section Usage
+      First Use: 4: User
+      Explore Features: 5: User
+      Regular Usage: 5: User
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If user journey diagrams are not supported, use this flowchart alternative:
+
+```mermaid
+flowchart TD
+    Start[Start] --> Browse[Browse Products]
+    Browse --> Select[Select Product]
+    Select --> Cart[Add to Cart]
+    Cart --> Checkout[Checkout]
+    Checkout --> Payment[Payment]
+    Payment --> Confirm[Order Confirmation]
+    Confirm --> End[End]
+```

skills/mermaid/examples/kanban.md

@@ -4,27 +4,63 @@ Kanban diagrams visualize workflow using a board with columns representing diffe
 
 ### Syntax
 
-- Use `kanban` keyword
-- Columns: `section ColumnName`
-- Cards: `Card Title :crit, done, active`
-- Status:
-  - `done` - Completed
-  - `active` - In progress
-  - `crit` - Critical
-- Cards can be moved between columns
+- Use `kanban` keyword (requires Mermaid v11.4.0+, experimental feature 🔥)
+- Columns: `columnId[Column Title]` - Each column has a unique identifier and title
+- Tasks: `taskId[Task Description]` - Tasks are indented under their column
+- Metadata: `@{assigned: "name", ticket: "TICKET-123", priority: "High"}` (optional)
+- Supported priority values: `'Very High'`, `'High'`, `'Low'`, `'Very Low'`
+- Tasks must be indented under their column (proper indentation is crucial)
+- **Important**: If your environment doesn't support kanban, use the flowchart alternative below
 
-### Example
+Reference: [Mermaid Kanban Documentation](https://mermaid.ai/open-source/syntax/kanban.html)
+
+### Example (Kanban - requires Mermaid v11.4.0+)
+
+```mermaid
+kanban
+    id1[To Do]
+        docs[Create Documentation]
+        test[Write Tests]
+    id2[In Progress]
+        dev[Develop Feature] @{assigned: "Alice", priority: "High"}
+        review[Code Review] @{assigned: "Bob", ticket: "TICKET-123"}
+    id3[Done]
+        deploy[Deploy to Production] @{assigned: "Charlie", priority: "Very High"}
+        monitor[Monitor Performance]
+```
+
+### Example with Metadata
 
 ```mermaid
 kanban
-    title Project Board
-    section To Do
-        Task 1
-        Task 2
-    section In Progress
-        Task 3 :active
-        Task 4 :crit
-    section Done
-        Task 5 :done
-        Task 6 :done
+    todo[To Do]
+        task1[Task 1] @{assigned: "Developer A", priority: "High"}
+        task2[Task 2] @{ticket: "PROJ-456"}
+    progress[In Progress]
+        task3[Task 3] @{assigned: "Developer B", ticket: "PROJ-789", priority: "Very High"}
+    done[Done]
+        task4[Task 4] @{assigned: "Developer C", priority: "Low"}
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If kanban is not supported, use this flowchart alternative:
+
+```mermaid
+flowchart LR
+    subgraph ToDo["To Do"]
+        T1[Task 1]
+        T2[Task 2]
+    end
+    subgraph InProgress["In Progress"]
+        T3[Task 3]
+        T4[Task 4]
+    end
+    subgraph Done["Done"]
+        T5[Task 5]
+        T6[Task 6]
+    end
+
+    ToDo --> InProgress
+    InProgress --> Done
 ```

skills/mermaid/examples/mindmap.md

@@ -1,16 +1,29 @@
 ## Instructions
 
-Mindmaps visualize hierarchical information, showing relationships between concepts in a tree-like structure.
+Mindmaps visualize hierarchical information, showing relationships between concepts in a tree-like structure. A mind map is a diagram used to visually organize information into a hierarchy, showing relationships among pieces of the whole. It is often created around a single concept, drawn as an image in the center of a blank page, to which associated representations of ideas such as images, words and parts of words are added.
+
+**Note**: This is an experimental diagram type. The syntax and properties can change in future releases. The syntax is stable except for the icon integration which is the experimental part.
 
 ### Syntax
 
 - Use `mindmap` keyword
-- Root: `root((Root Node))`
-- Nodes: `NodeName[Label]` or `NodeName((Label))`
-- Hierarchy: Indentation determines parent-child relationships
-- Icons: `fa:fa-icon-name` for Font Awesome icons
+- Root: `root((Root Node))` or just `Root` (text at root level)
+- Nodes: Defined by indentation (spaces or tabs determine hierarchy)
+- Shapes: Similar to flowchart nodes:
+  - Square: `id["Label"]`
+  - Rounded square: `id("Label")`
+  - Circle: `id(("Label"))`
+  - Bang: `id))Label((`
+  - Cloud: `id))Label(("
+  - Hexagon: `id{{"Label"}}`
+  - Default: Just text (no shape delimiters)
+- Icons: `::icon(fa:fa-icon-name)` (experimental, requires icon fonts)
+- Classes: `:::class1 class2` (triple colon followed by CSS classes)
+- Markdown strings: Supports **bold** and *italics*, auto-wraps text
+
+Reference: [Mermaid Mindmap Documentation](https://mermaid.ai/open-source/syntax/mindmap.html)
 
-### Example
+### Example (Basic Mindmap)
 
 ```mermaid
 mindmap
@@ -32,3 +45,109 @@ mindmap
             ER Diagrams
             Gantt Charts
 ```
+
+### Example (With Different Shapes)
+
+```mermaid
+mindmap
+    root((Project))
+        Planning["Planning"]
+            Requirements("Requirements")
+            Design(("Design"))
+            Timeline))Timeline((
+        Development{{"Development"}}
+            Frontend
+            Backend
+            Database
+        Testing
+            Unit Tests
+            Integration Tests
+```
+
+### Example (With Markdown Formatting)
+
+```mermaid
+mindmap
+    root((**Mermaid**))
+        *Flowcharts*
+            **Basic** Flowchart
+            *Subgraph*
+            Styling
+        Sequence Diagrams
+            **Participants**
+            Messages
+            *Activations*
+```
+
+### Example (Simple Hierarchy)
+
+```mermaid
+mindmap
+    Root
+        A
+            B
+            C
+        D
+            E
+            F
+```
+
+### Example (Technology Stack)
+
+```mermaid
+mindmap
+    root((Tech Stack))
+        Frontend
+            React
+            Vue
+            Angular
+        Backend
+            Node.js
+            Python
+            Java
+        Database
+            PostgreSQL
+            MongoDB
+            Redis
+        DevOps
+            Docker
+            Kubernetes
+            CI/CD
+```
+
+### Example (Project Planning)
+
+```mermaid
+mindmap
+    root((Project))
+        Planning
+            Requirements
+            Design
+            Timeline
+        Development
+            Frontend
+            Backend
+            Testing
+        Deployment
+            Staging
+            Production
+            Monitoring
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If mindmap diagrams are not supported, use this flowchart alternative:
+
+```mermaid
+flowchart TD
+    Root((Root))
+    A[Node A]
+    B[Node B]
+    C[Node C]
+    D[Node D]
+
+    Root --> A
+    Root --> B
+    A --> C
+    A --> D
+```

skills/mermaid/examples/packet.md

@@ -1,28 +1,91 @@
 ## Instructions
 
-Packet diagrams visualize network packet structures, showing the layers and fields of network protocols.
+Packet diagrams are visual representations used to illustrate the structure and contents of a network packet. Network packets are the fundamental units of data transferred over a network. This diagram type is particularly useful for developers, network engineers, educators, and students who require a clear and concise way to represent the structure of network packets.
 
 ### Syntax
 
-- Use `packet-beta` keyword
-- Packets: `packet PacketName { }`
-- Fields: `field FieldName : Type`
-- Nested structures: Indentation for nested fields
-- Bit fields: `field FieldName : Type (bits)`
+- Use `packet` keyword (requires Mermaid v11.0.0+)
+- Title: `title "Packet Title"` (optional)
+- Fields:
+  - `start-end: "Field Description"` - Multi-bit blocks (e.g., `0-15: "Field Name"`)
+  - `start: "Field Description"` - Single-bit block (e.g., `0: "Flag"`)
+- Bit Syntax (v11.7.0+): Use `+<count>` to set the number of bits, which starts from the end of the previous field automatically
+  - `+1: "Block name"` - Single-bit block
+  - `+8: "Block name"` - 8-bit block
+  - You can mix and match: `9-15: "Manually set start and end"`
+- Ranges: Each line after the title represents a different field in the packet. The range (e.g., `0-15`) indicates the bit positions in the packet.
+- Field Description: A brief description of what the field represents, enclosed in quotes.
 
-### Example
+Reference: [Mermaid Packet Diagram Documentation](https://mermaid.ai/open-source/syntax/packet.html)
+
+### Example (Ethernet Frame - Basic Syntax)
+
+```mermaid
+packet
+    title "Ethernet Frame"
+    0-47: "Destination MAC"
+    48-95: "Source MAC"
+    96-111: "Type/Length"
+    112-: "Payload"
+```
+
+### Example (IPv4 Header - Basic Syntax)
+
+```mermaid
+packet
+    title "IPv4 Header"
+    0-3: "Version"
+    4-7: "Header Length"
+    8-15: "Type of Service"
+    16-31: "Total Length"
+    32-47: "Identification"
+    48-63: "Flags & Fragment Offset"
+    64-71: "Time to Live"
+    72-79: "Protocol"
+    80-95: "Header Checksum"
+    96-127: "Source IP Address"
+    128-159: "Destination IP Address"
+    160-: "Options & Padding"
+```
+
+### Example (Using Bit Count Syntax - v11.7.0+)
+
+```mermaid
+packet
+    title "TCP Header"
+    +4: "Source Port"
+    +4: "Destination Port"
+    +8: "Sequence Number"
+    +8: "Acknowledgment Number"
+    32-35: "Data Offset"
+    +4: "Reserved"
+    +6: "Flags"
+    +16: "Window Size"
+    +16: "Checksum"
+    +16: "Urgent Pointer"
+```
+
+### Example (Mixed Syntax)
+
+```mermaid
+packet
+    title "Mixed Syntax Example"
+    +8: "First Field (8 bits)"
+    8-15: "Second Field (manually set)"
+    +4: "Third Field (4 bits, auto-continues from 16)"
+    20-31: "Fourth Field (manually set)"
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If packet diagrams are not supported, use this flowchart alternative:
 
 ```mermaid
-packet-beta
-    packet Ethernet {
-        field Destination MAC : 48 bits
-        field Source MAC : 48 bits
-        field Type : 16 bits
-    }
-    packet IPv4 {
-        field Version : 4 bits
-        field Header Length : 4 bits
-        field Total Length : 16 bits
-        field Protocol : 8 bits
-    }
+flowchart TD
+    subgraph Packet["Packet Structure"]
+        Field1["0-47: Destination MAC"]
+        Field2["48-95: Source MAC"]
+        Field3["96-111: Type/Length"]
+        Field4["112-: Payload"]
+    end
 ```

skills/mermaid/examples/pie.md

@@ -1,15 +1,20 @@
 ## Instructions
 
-Pie charts display proportional data, showing how parts relate to a whole.
+Pie charts display proportional data, showing how parts relate to a whole. A pie chart (or a circle chart) is a circular statistical graphic, which is divided into slices to illustrate numerical proportion. In a pie chart, the arc length of each slice (and consequently its central angle and area), is proportional to the quantity it represents.
 
 ### Syntax
 
-- Use `pie` keyword
-- Title: `title Chart Title` (optional)
-- Data format: `"Label" : Value`
-- Values should be numeric
+- Use `pie` keyword to begin the diagram
+- Show data: `showData` (optional) - renders the actual data values after the legend text
+- Title: `title "Chart Title"` (optional) - gives a title to the pie chart
+- Data format: `"Label" : Value` (quotes around label, colon separator, positive numeric value)
+- Values: Must be positive numbers greater than zero (supported up to two decimal places)
+- Negative values are not allowed and will result in an error
+- Pie slices will be ordered clockwise in the same order as the labels
 
-### Example
+Reference: [Mermaid Pie Chart Documentation](https://mermaid.ai/open-source/syntax/pie.html)
+
+### Example (Basic Pie Chart)
 
 ```mermaid
 pie title Sales by Product
@@ -18,3 +23,82 @@ pie title Sales by Product
     "Product C" : 15.8
     "Product D" : 11.5
 ```
+
+### Example (With showData)
+
+```mermaid
+pie showData title Sales by Product
+    "Product A" : 42.5
+    "Product B" : 30.2
+    "Product C" : 15.8
+    "Product D" : 11.5
+```
+
+### Example (Budget Allocation)
+
+```mermaid
+pie title Budget Allocation
+    "Development" : 40
+    "Marketing" : 25
+    "Operations" : 20
+    "Support" : 10
+    "Other" : 5
+```
+
+### Example (Market Share)
+
+```mermaid
+pie title Market Share
+    "Company A" : 35.5
+    "Company B" : 28.3
+    "Company C" : 20.1
+    "Company D" : 10.2
+    "Others" : 5.9
+```
+
+### Example (Team Distribution)
+
+```mermaid
+pie showData title Team Distribution
+    "Frontend" : 30
+    "Backend" : 35
+    "DevOps" : 15
+    "QA" : 12
+    "Design" : 8
+```
+
+### Example (Revenue Sources)
+
+```mermaid
+pie title Revenue Sources
+    "Product Sales" : 55.5
+    "Services" : 25.3
+    "Subscriptions" : 12.7
+    "Licensing" : 4.2
+    "Other" : 2.3
+```
+
+### Example (With Decimal Values)
+
+```mermaid
+pie title Survey Results
+    "Very Satisfied" : 45.75
+    "Satisfied" : 32.50
+    "Neutral" : 12.25
+    "Dissatisfied" : 7.50
+    "Very Dissatisfied" : 2.00
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If pie charts are not supported, use this flowchart alternative:
+
+```mermaid
+flowchart TD
+    subgraph Chart["Sales by Product"]
+        A[Product A: 42.5%]
+        B[Product B: 30.2%]
+        C[Product C: 15.8%]
+        D[Product D: 11.5%]
+    end
+```

skills/mermaid/examples/quadrant.md

@@ -1,17 +1,25 @@
 ## Instructions
 
-Quadrant charts display items in a 2x2 grid based on two criteria, useful for prioritization and analysis.
+Quadrant charts display items in a 2x2 grid based on two criteria, useful for prioritization and analysis. A quadrant chart is a visual representation of data that is divided into four quadrants. It is used to plot data points on a two-dimensional grid, with one variable represented on the x-axis and another variable represented on the y-axis. The quadrants are determined by dividing the chart into four equal parts based on a set of criteria that is specific to the data being analyzed.
 
 ### Syntax
 
 - Use `quadrantChart` keyword
-- Title: `title Chart Title`
-- X-axis: `x-axis Low Label --> High Label`
-- Y-axis: `y-axis Low Label --> High Label`
+- Title: `title Chart Title` (optional)
+- X-axis: `x-axis Left Label --> Right Label` or `x-axis Left Label` (only left)
+- Y-axis: `y-axis Bottom Label --> Top Label` or `y-axis Bottom Label` (only bottom)
 - Quadrants: `quadrant-1 Label`, `quadrant-2 Label`, `quadrant-3 Label`, `quadrant-4 Label`
-- Items: `Item Name: [x, y]`
+  - `quadrant-1`: Top right quadrant
+  - `quadrant-2`: Top left quadrant
+  - `quadrant-3`: Bottom left quadrant
+  - `quadrant-4`: Bottom right quadrant
+- Points: `Point Name: [x, y]` where x and y values are in the range 0-1
+- Point styling: `Point Name: [x, y] radius: 12, color: #ff3300, stroke-color: #10f0f0, stroke-width: 5px`
+- Class styling: `Point Name:::className: [x, y]` with `classDef className color: #109060, radius: 10`
 
-### Example
+Reference: [Mermaid Quadrant Chart Documentation](https://mermaid.ai/open-source/syntax/quadrantChart.html)
+
+### Example (Basic Quadrant Chart)
 
 ```mermaid
 quadrantChart
@@ -27,3 +35,111 @@ quadrantChart
     Feature C: [0.2, 0.3]
     Feature D: [0.8, 0.2]
 ```
+
+### Example (With Single Axis Labels)
+
+```mermaid
+quadrantChart
+    title Risk vs Reward
+    x-axis Low Risk
+    y-axis Low Reward
+    quadrant-1 High Risk, High Reward
+    quadrant-2 Low Risk, High Reward
+    quadrant-3 Low Risk, Low Reward
+    quadrant-4 High Risk, Low Reward
+    Investment A: [0.8, 0.9]
+    Investment B: [0.2, 0.7]
+    Investment C: [0.3, 0.2]
+```
+
+### Example (With Point Styling)
+
+```mermaid
+quadrantChart
+    title Performance vs Cost
+    x-axis Low Cost --> High Cost
+    y-axis Low Performance --> High Performance
+    quadrant-1 High Cost, High Performance
+    quadrant-2 Low Cost, High Performance
+    quadrant-3 Low Cost, Low Performance
+    quadrant-4 High Cost, Low Performance
+    Product A: [0.9, 0.0] radius: 12
+    Product B: [0.8, 0.1] color: #ff3300, radius: 10
+    Product C: [0.7, 0.2] radius: 25, color: #00ff33, stroke-color: #10f0f0
+    Product D: [0.6, 0.3] radius: 15, stroke-color: #00ff0f, stroke-width: 5px, color: #ff33f0
+```
+
+### Example (With Class Styling)
+
+```mermaid
+quadrantChart
+    title Feature Analysis
+    x-axis Low Priority --> High Priority
+    y-axis Low Value --> High Value
+    quadrant-1 High Priority, High Value
+    quadrant-2 Low Priority, High Value
+    quadrant-3 Low Priority, Low Value
+    quadrant-4 High Priority, Low Value
+    Feature A:::highValue: [0.3, 0.9]
+    Feature B:::mediumValue: [0.7, 0.6]
+    Feature C:::lowValue: [0.2, 0.2]
+    Feature D:::highValue: [0.8, 0.8]
+
+    classDef highValue color: #109060, radius: 10
+    classDef mediumValue color: #908342, radius: 8, stroke-color: #310085, stroke-width: 3px
+    classDef lowValue color: #f00fff, radius: 6
+```
+
+### Example (Business Strategy)
+
+```mermaid
+quadrantChart
+    title Market Analysis
+    x-axis Low Market Share --> High Market Share
+    y-axis Low Growth --> High Growth
+    quadrant-1 Stars
+    quadrant-2 Question Marks
+    quadrant-3 Dogs
+    quadrant-4 Cash Cows
+    Product A: [0.8, 0.9]
+    Product B: [0.3, 0.7]
+    Product C: [0.2, 0.2]
+    Product D: [0.7, 0.3]
+```
+
+### Example (Team Skills Assessment)
+
+```mermaid
+quadrantChart
+    title Team Skills Matrix
+    x-axis Low Experience --> High Experience
+    y-axis Low Performance --> High Performance
+    quadrant-1 High Experience, High Performance
+    quadrant-2 Low Experience, High Performance
+    quadrant-3 Low Experience, Low Performance
+    quadrant-4 High Experience, Low Performance
+    Developer A: [0.9, 0.85]
+    Developer B: [0.6, 0.9]
+    Developer C: [0.3, 0.4]
+    Developer D: [0.8, 0.5]
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If quadrant charts are not supported, use this flowchart alternative:
+
+```mermaid
+flowchart TD
+    subgraph Q1["Quadrant 1<br>High X, High Y"]
+        A[Feature A]
+    end
+    subgraph Q2["Quadrant 2<br>Low X, High Y"]
+        B[Feature B]
+    end
+    subgraph Q3["Quadrant 3<br>Low X, Low Y"]
+        C[Feature C]
+    end
+    subgraph Q4["Quadrant 4<br>High X, Low Y"]
+        D[Feature D]
+    end
+```

skills/mermaid/examples/radar.md

@@ -1,25 +1,102 @@
 ## Instructions
 
-Radar charts (beta) display multivariate data on axes starting from the same point, useful for comparing multiple items across different dimensions.
+Radar diagrams are a simple way to plot low-dimensional data in a circular format. They are also known as radar charts, spider charts, star charts, cobweb charts, polar charts, or Kiviat diagrams. This diagram type is particularly useful for developers, data scientists, and engineers who require a clear and concise way to represent data in a circular format. It is commonly used to graphically summarize and compare the performance of multiple entities across multiple dimensions.
 
 ### Syntax
 
-- Use `radar-beta` keyword
-- Title: `title Chart Title`
-- Axes: `axis AxisName [min, max]`
-- Series: `series SeriesName [values]`
-- Values should match the number of axes
+- Use `radar-beta` keyword (requires Mermaid v11.6.0+)
+- Title: `title Title of the Radar Diagram` (optional)
+- Axis: `axis id1["Label1"]` or `axis id1, id2, id3` (multiple axes in one line)
+- Curve: `curve id1["Label1"]{1, 2, 3}` or `curve id1{ axis1: 20, axis2: 30, axis3: 10 }` (key-value pairs)
+- Options:
+  - `showLegend true/false` - Show or hide legend (default: true)
+  - `max value` - Maximum value for scaling (auto-calculated if not provided)
+  - `min value` - Minimum value for scaling (default: 0)
+  - `graticule circle/polygon` - Type of graticule (default: circle)
+  - `ticks number` - Number of concentric circles/polygons (default: 5)
 
-### Example
+Reference: [Mermaid Radar Diagram Documentation](https://mermaid.ai/open-source/syntax/radar.html)
+
+### Example (Basic Radar Diagram)
+
+```mermaid
+radar-beta
+    axis Performance, Quality, Speed, Cost
+    curve Product A[Product A]{80, 90, 70, 60}
+    curve Product B[Product B]{70, 85, 90, 75}
+```
+
+### Example (With Title and Options)
 
 ```mermaid
 radar-beta
     title Performance Comparison
-    axis Performance [0, 100]
-    axis Quality [0, 100]
-    axis Speed [0, 100]
-    axis Cost [0, 100]
-    
-    series Product A [80, 90, 70, 60]
-    series Product B [70, 85, 90, 75]
+    axis Performance, Quality, Speed, Cost
+    curve Product A[Product A]{80, 90, 70, 60}
+    curve Product B[Product B]{70, 85, 90, 75}
+    showLegend true
+    max 100
+    min 0
+    graticule circle
+    ticks 5
+```
+
+### Example (Using Key-Value Pairs)
+
+```mermaid
+radar-beta
+    axis Performance["Performance"], Quality["Quality"], Speed["Speed"], Cost["Cost"]
+    curve Product A[Product A]{ Performance: 80, Quality: 90, Speed: 70, Cost: 60 }
+    curve Product B[Product B]{ Performance: 70, Quality: 85, Speed: 90, Cost: 75 }
+```
+
+### Example (Multiple Curves)
+
+```mermaid
+radar-beta
+    title Team Skills Assessment
+    axis Frontend, Backend, DevOps, Testing, Design
+    curve Developer1[Developer 1]{85, 70, 60, 75, 80}
+    curve Developer2[Developer 2]{70, 90, 75, 80, 65}
+    curve Developer3[Developer 3]{90, 75, 85, 70, 90}
+    max 100
+    graticule polygon
+    ticks 4
+```
+
+### Example (Polygon Graticule)
+
+```mermaid
+radar-beta
+    title Sales Performance
+    axis Q1, Q2, Q3, Q4
+    curve Region A[Region A]{100, 120, 110, 130}
+    curve Region B[Region B]{90, 100, 115, 125}
+    graticule polygon
+    ticks 6
+    max 150
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If radar diagrams are not supported, use this flowchart alternative:
+
+```mermaid
+flowchart TD
+    subgraph Performance["Performance Comparison"]
+        A1[Product A: 80]
+        A2[Product B: 70]
+    end
+    subgraph Quality["Quality"]
+        B1[Product A: 90]
+        B2[Product B: 85]
+    end
+    subgraph Speed["Speed"]
+        C1[Product A: 70]
+        C2[Product B: 90]
+    end
+    subgraph Cost["Cost"]
+        D1[Product A: 60]
+        D2[Product B: 75]
+    end
 ```

skills/mermaid/examples/requirement.md

@@ -1,20 +1,30 @@
 ## Instructions
 
-Requirement diagrams model system requirements and their relationships, showing how requirements relate to each other and to system elements.
+Requirement diagrams model system requirements and their relationships, showing how requirements relate to each other and to system elements. A Requirement diagram provides a visualization for requirements and their connections, to each other and other documented elements. The modeling specs follow those defined by SysML v1.6.
 
 ### Syntax
 
 - Use `requirementDiagram` keyword
-- Requirements: `requirement RequirementID { }`
-- Requirement types: `functionalRequirement`, `interfaceRequirement`, `performanceRequirement`, `physicalRequirement`, `designConstraint`
-- Relationships:
-  - `contains` - Parent-child relationship
-  - `satisfies` - Requirement satisfies element
-  - `verifies` - Element verifies requirement
-  - `refines` - Requirement refines another
-  - `traces` - Trace relationship
+- Requirements: `<type> name { id: id, text: text, risk: risk, verifymethod: method }`
+- Requirement types: `requirement`, `functionalRequirement`, `interfaceRequirement`, `performanceRequirement`, `physicalRequirement`, `designConstraint`
+- Risk levels: `Low`, `Medium`, `High`
+- Verification methods: `Analysis`, `Inspection`, `Test`, `Demonstration`
+- Elements: `element name { type: type, docref: docref }`
+- Relationships: Must use arrow syntax `Source - <relationship> -> Destination`
+  - `contains` - Parent-child relationship: `R1 - contains -> R2`
+  - `copies` - Requirement copies another: `R1 - copies -> R2`
+  - `derives` - Requirement derives from another: `R1 - derives -> R2`
+  - `satisfies` - Requirement satisfies element: `R1 - satisfies -> E1`
+  - `verifies` - Element verifies requirement: `E1 - verifies -> R1`
+  - `refines` - Requirement refines another: `R2 - refines -> R1`
+  - `traces` - Trace relationship: `R2 - traces -> R1`
+- Direction: `direction TB|BT|LR|RL` (default: TB)
+- Styling: `style name fill:#color,stroke:#color` or `classDef className fill:#color`
+- Markdown formatting: Supports **bold** and *italics* in quoted text
 
-### Example
+Reference: [Mermaid Requirement Diagram Documentation](https://mermaid.ai/open-source/syntax/requirementDiagram.html)
+
+### Example (Basic Requirement Diagram)
 
 ```mermaid
 requirementDiagram
@@ -30,12 +40,223 @@ requirementDiagram
         risk: medium
         verifymethod: test
     }
-    
+
     element E1 {
         type: System
         docref: docs/system.md
     }
-    
-    R1 satisfies E1
-    R2 satisfies E1
+
+    R1 - satisfies -> E1
+    R2 - satisfies -> E1
+```
+
+### Example (With Different Requirement Types)
+
+```mermaid
+requirementDiagram
+    functionalRequirement FR1 {
+        id: 1
+        text: User authentication functionality
+        risk: high
+        verifymethod: test
+    }
+    performanceRequirement PR1 {
+        id: 2
+        text: Response time must be under 2 seconds
+        risk: medium
+        verifymethod: analysis
+    }
+    interfaceRequirement IR1 {
+        id: 3
+        text: REST API interface specification
+        risk: low
+        verifymethod: inspection
+    }
+
+    FR1 - refines -> PR1
+    PR1 - traces -> IR1
+```
+
+### Example (With Relationships)
+
+```mermaid
+requirementDiagram
+    requirement R1 {
+        id: 1
+        text: High-level system requirement
+        risk: high
+        verifymethod: test
+    }
+    requirement R2 {
+        id: 2
+        text: Detailed requirement
+        risk: medium
+        verifymethod: test
+    }
+    requirement R3 {
+        id: 3
+        text: Derived requirement
+        risk: low
+        verifymethod: analysis
+    }
+
+    element E1 {
+        type: Component
+        docref: docs/component.md
+    }
+
+    R1 - contains -> R2
+    R2 - refines -> R1
+    R3 - derives -> R1
+    R2 - satisfies -> E1
+    E1 - verifies -> R2
+```
+
+### Example (With Markdown Formatting)
+
+```mermaid
+requirementDiagram
+    requirement R1 {
+        id: 1
+        text: "System must support **bold** and *italic* text"
+        risk: low
+        verifymethod: inspection
+    }
+
+    element E1 {
+        type: "**System** Component"
+        docref: "docs/*system*.md"
+    }
+
+    R1 - satisfies -> E1
+```
+
+### Example (With Direction - Left to Right)
+
+```mermaid
+requirementDiagram
+    direction LR
+
+    requirement R1 {
+        id: 1
+        text: Requirement 1
+        risk: high
+        verifymethod: test
+    }
+    requirement R2 {
+        id: 2
+        text: Requirement 2
+        risk: medium
+        verifymethod: test
+    }
+
+    R1 - refines -> R2
+```
+
+### Example (With Styling)
+
+```mermaid
+requirementDiagram
+    requirement R1 {
+        id: 1
+        text: High priority requirement
+        risk: high
+        verifymethod: test
+    }
+    requirement R2 {
+        id: 2
+        text: Medium priority requirement
+        risk: medium
+        verifymethod: test
+    }
+
+    element E1 {
+        type: System
+        docref: docs/system.md
+    }
+
+    R1 - satisfies -> E1
+    R2 - satisfies -> E1
+
+    style R1 fill:#ff6b6b,stroke:#333,stroke-width:3px
+    style R2 fill:#4ecdc4,stroke:#333,stroke-width:2px
+    style E1 fill:#ffe66d,stroke:#333,stroke-width:2px
+```
+
+### Example (With Class Definitions)
+
+```mermaid
+requirementDiagram
+    requirement R1 {
+        id: 1
+        text: Requirement 1
+        risk: high
+        verifymethod: test
+    }
+    requirement R2 {
+        id: 2
+        text: Requirement 2
+        risk: medium
+        verifymethod: test
+    }
+
+    classDef highRisk fill:#ff6b6b,stroke:#333,stroke-width:3px
+    classDef mediumRisk fill:#4ecdc4,stroke:#333,stroke-width:2px
+
+    class R1 highRisk
+    class R2 mediumRisk
+```
+
+### Example (Complex Requirement Diagram)
+
+```mermaid
+requirementDiagram
+    requirement R1 {
+        id: 1
+        text: System must be scalable
+        risk: high
+        verifymethod: test
+    }
+    requirement R2 {
+        id: 2
+        text: System must handle 1000 users
+        risk: high
+        verifymethod: test
+    }
+    requirement R3 {
+        id: 3
+        text: System must respond quickly
+        risk: medium
+        verifymethod: analysis
+    }
+
+    element E1 {
+        type: System
+        docref: docs/system.md
+    }
+    element E2 {
+        type: Component
+        docref: docs/component.md
+    }
+
+    R1 - contains -> R2
+    R1 - contains -> R3
+    R2 - satisfies -> E1
+    R3 - satisfies -> E1
+    E1 - verifies -> R2
+    E2 - verifies -> R3
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If requirement diagrams are not supported, use this flowchart alternative:
+
+```mermaid
+flowchart TD
+    R1[Requirement 1<br>Risk: High]
+    R2[Requirement 2<br>Risk: Medium]
+    E1[Element 1<br>Type: System]
+
+    R1 -->|satisfies| E1
+    R2 -->|satisfies| E1
 ```

skills/mermaid/examples/sankey.md

@@ -4,19 +4,64 @@ Sankey diagrams visualize flow and relationships between entities, showing the m
 
 ### Syntax
 
-- Use `sankey-beta` keyword
-- Flows: `Source -->|Value| Target`
+- Use `sankey` keyword (requires Mermaid v10.3.0+, experimental feature 🔥)
+- Format: CSV style with exactly **3 columns**: `Source,Target,Value`
+- Each line represents one flow: `source,target,value`
+- **Empty lines are allowed** (for visual separation, without comma separators)
+- Node names with **commas** must be wrapped in quotes: `"Node, Name"`
+- Node names with **double quotes** use two quotes: `"He said ""Hello"""`
 - Values should be numeric
 - Multiple flows can originate from or target the same node
+- **Important**: Do NOT use arrow syntax (`-->|Value|`). Use CSV format instead.
+- **Important**: If your environment doesn't support sankey, use the flowchart alternative below
 
-### Example
+Reference: [Mermaid Sankey Documentation](https://mermaid.ai/open-source/syntax/sankey.html)
+
+### Example (Sankey - requires Mermaid v10.3.0+)
+
+```mermaid
+sankey
+Energy Production,Electricity,100
+Energy Production,Heat,30
+
+Electricity,Residential,80
+Electricity,Industrial,20
+
+Heat,Residential,25
+Heat,Industrial,5
+```
+
+### Example with Special Characters
 
 ```mermaid
-sankey-beta
-    Energy Production -->|100| Electricity
-    Energy Production -->|30| Heat
-    Electricity -->|80| Residential
-    Electricity -->|20| Industrial
-    Heat -->|25| Residential
-    Heat -->|5| Industrial
+sankey
+Source A,Target B,50
+"Source, with comma","Target with ""quotes""",30
+Source C,Target D,20
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If sankey is not supported, use this flowchart alternative:
+
+```mermaid
+flowchart LR
+    EP[Energy Production]
+    E[Electricity]
+    H[Heat]
+    R[Residential]
+    I[Industrial]
+
+    EP -->|100| E
+    EP -->|30| H
+    E -->|80| R
+    E -->|20| I
+    H -->|25| R
+    H -->|5| I
+
+    style EP fill:#e1f5ff
+    style E fill:#b3e5fc
+    style H fill:#b3e5fc
+    style R fill:#c8e6c9
+    style I fill:#c8e6c9
 ```

skills/mermaid/examples/sequence.md

@@ -1,27 +1,51 @@
 ## Instructions
 
-Sequence diagrams show interactions between objects or participants over time, displaying the messages exchanged between them.
+Sequence diagrams show interactions between objects or participants over time, displaying the messages exchanged between them. A Sequence diagram is an interaction diagram that shows how processes operate with one another and in what order.
 
 ### Syntax
 
 - Use `sequenceDiagram` keyword
-- Define participants: `participant A as "Label"`
-- Message types:
-  - `->>` - Solid arrow (synchronous)
-  - `-->>` - Dotted arrow (asynchronous)
-  - `->` - Solid line (return)
-  - `-->` - Dotted line (return)
-- Activation: `activate` and `deactivate`
-- Control structures: `alt/else`, `opt`, `loop`, `par`, `critical`, `break`
+- Participants: Defined implicitly by order of appearance, or explicitly with `participant Name` or `participant Alias as "Label"`
+- Actor symbols: `actor Name` (uses actor symbol instead of rectangle)
+- Participant types: `participant`, `actor`, `boundary`, `control`, `entity`, `database`, `collections`, `queue`
+- Messages: `Participant1->Participant2: Message` or `Participant1-->>Participant2: Message`
+- Arrow types:
+  - `->` - Solid line without arrow
+  - `-->` - Dotted line without arrow
+  - `->>` - Solid line with arrowhead
+  - `-->>` - Dotted line with arrowhead
+  - `<<->>` - Solid line with bidirectional arrowheads (v11.0.0+)
+  - `<<-->>` - Dotted line with bidirectional arrowheads (v11.0.0+)
+  - `-x` - Solid line with cross at end
+  - `--x` - Dotted line with cross at end
+  - `-)` - Solid line with open arrow (async)
+  - `--)` - Dotted line with open arrow (async)
+- Activations: `activate Participant` and `deactivate Participant`, or use `+`/`-` suffix on arrows
+- Notes: `note right of Participant: Text` or `note left of Participant: Text` or `note over Participant1, Participant2: Text`
+- Control structures:
+  - Loops: `loop Loop text ... end`
+  - Alt: `alt Describing text ... else ... end`
+  - Opt: `opt Describing text ... end`
+  - Parallel: `par [Action 1] ... and [Action 2] ... end`
+  - Critical: `critical [Action] ... option [Circumstance] ... end`
+  - Break: `break [Condition] ... end`
+- Rectangles: `rect rgb(0,0,255) ... end` or `rect rgba(0,0,255,.1) ... end`
+- Actor creation/destruction: `create participant Name` or `destroy participant Name` (v10.3.0+)
+- Grouping: `box Color Label ... actors ... end`
+- Comments: `%% comment` (on separate line)
+- Line breaks: Use `\n` in messages and notes
+- Sequence numbers: `sequenceNumbers` (optional)
 
-### Example
+Reference: [Mermaid Sequence Diagram Documentation](https://mermaid.ai/open-source/syntax/sequenceDiagram.html)
+
+### Example (Basic Sequence Diagram)
 
 ```mermaid
 sequenceDiagram
     participant U as User
     participant S as System
     participant D as Database
-    
+
     U->>S: Login Request
     activate S
     S->>D: Query User
@@ -31,3 +55,196 @@ sequenceDiagram
     S-->>U: Login Success
     deactivate S
 ```
+
+### Example (With Activations - Shortcut)
+
+```mermaid
+sequenceDiagram
+    participant A as Alice
+    participant B as Bob
+
+    A->>+B: Hello
+    B-->>-A: Hi
+    A->>+B: How are you?
+    B-->>-A: I'm good!
+```
+
+### Example (With Loops)
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant S as System
+
+    U->>S: Request Data
+    loop For each item
+        S->>S: Process Item
+        S-->>U: Return Item
+    end
+    S-->>U: Complete
+```
+
+### Example (With Alt - Alternative Paths)
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant S as System
+
+    U->>S: Login Request
+    alt Valid credentials
+        S-->>U: Login Success
+    else Invalid credentials
+        S-->>U: Login Failed
+    end
+```
+
+### Example (With Opt - Optional)
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant S as System
+    participant C as Cache
+
+    U->>S: Request Data
+    opt Cache available
+        S->>C: Check Cache
+        C-->>S: Cached Data
+    end
+    S-->>U: Response
+```
+
+### Example (With Parallel)
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant S as System
+    participant A as Service A
+    participant B as Service B
+
+    U->>S: Request
+    par Parallel Processing
+        S->>A: Call Service A
+        A-->>S: Response A
+    and
+        S->>B: Call Service B
+        B-->>S: Response B
+    end
+    S-->>U: Combined Response
+```
+
+### Example (With Critical Region)
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant S as System
+
+    U->>S: Transaction Request
+    critical Critical Transaction
+        S->>S: Validate
+        S->>S: Process
+    option Success
+        S-->>U: Success
+    option Failure
+        S-->>U: Error
+    end
+```
+
+### Example (With Notes)
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant S as System
+
+    U->>S: Request
+    note right of S: Processing request
+    S->>S: Internal Processing
+    note left of U: Waiting for response
+    S-->>U: Response
+```
+
+### Example (With Actor Creation)
+
+```mermaid
+sequenceDiagram
+    participant A as Alice
+    participant B as Bob
+
+    A->>B: Create Session
+    create participant C as Cache
+    B->>C: Store Data
+    C-->>B: Confirmation
+    destroy C
+    B-->>A: Session Created
+```
+
+### Example (With Grouping)
+
+```mermaid
+sequenceDiagram
+    box rgb(200, 220, 255) Frontend
+        participant U as User
+        participant W as Web App
+    end
+    box rgb(255, 220, 200) Backend
+        participant A as API
+        participant D as Database
+    end
+
+    U->>W: Request
+    W->>A: API Call
+    A->>D: Query
+    D-->>A: Data
+    A-->>W: Response
+    W-->>U: Result
+```
+
+### Example (With Different Arrow Types)
+
+```mermaid
+sequenceDiagram
+    participant A
+    participant B
+
+    A->>B: Solid arrow
+    A-->>B: Dotted arrow
+    A->B: Solid line
+    A-->B: Dotted line
+    A-xB: Cross end
+    A--)B: Async
+```
+
+### Example (With Rectangles)
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant S as System
+
+    rect rgb(200, 220, 255)
+        U->>S: Request 1
+        S-->>U: Response 1
+    end
+    rect rgba(255, 220, 200, 0.5)
+        U->>S: Request 2
+        S-->>U: Response 2
+    end
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If sequence diagrams are not supported, use this flowchart alternative:
+
+```mermaid
+flowchart TD
+    Start([Start]) --> User[User]
+    User -->|Login Request| System[System]
+    System -->|Query| Database[(Database)]
+    Database -->|User Data| System
+    System -->|Login Success| User
+    User --> End([End])
+```

skills/mermaid/examples/state.md

@@ -1,25 +1,206 @@
 ## Instructions
 
-State diagrams show the different states of an object and the transitions between them, useful for modeling state machines.
+State diagrams show the different states of an object and the transitions between them, useful for modeling state machines. A state diagram is a type of diagram used in computer science and related fields to describe the behavior of systems. State diagrams require that the system described is composed of a finite number of states; sometimes, this is indeed the case, while at other times this is a reasonable abstraction.
 
 ### Syntax
 
-- Use `stateDiagram-v2` (recommended) or `stateDiagram`
-- States: `[StateName]`
-- Initial state: `[*]`
-- Final state: `[*]`
-- Transitions: `State1 --> State2 : Event`
-- Notes: `note right of StateName : Note text`
-- Concurrent states: `state StateName { [State1] [State2] }`
+- Use `stateDiagram-v2` (recommended) or `stateDiagram` keyword
+- States: `[StateName]` or `state StateName` or `StateId : State Description`
+- Initial state: `[*]` (start state)
+- Final state: `[*]` (end state)
+- Transitions: `State1 --> State2 : Event` or `State1 --> State2`
+- Composite states: `state StateName { [State1] [State2] }`
+- Choice: `<<choice>>` (decision point)
+- Fork/Join: `<<fork>>` and `<<join>>`
+- Notes: `note right of StateName : Note text` or `note left of StateName : Note text`
+- Concurrency: `--` (parallel states)
+- Direction: `direction TB|BT|LR|RL` (default: TB)
+- Comments: `%% comment` (on separate line)
+- Styling: `classDef className fill:#color,stroke:#color` and `class StateName className` or `StateName:::className`
+- Spaces in state names: Define state with id first, then reference it
 
-### Example
+Reference: [Mermaid State Diagram Documentation](https://mermaid.ai/open-source/syntax/stateDiagram.html)
+
+### Example (Basic State Diagram)
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle
+    Idle --> Processing : Start
+    Processing --> Completed : Success
+    Processing --> Error : Failure
+    Error --> Idle : Retry
+    Completed --> [*]
+```
+
+### Example (With State Descriptions)
+
+```mermaid
+stateDiagram-v2
+    [*] --> Still
+    Still --> Moving : Start
+    Moving --> Still : Stop
+    Moving --> Crash : Error
+    Crash --> [*]
+
+    state Still {
+        [*] --> Stationary
+        Stationary --> [*]
+    }
+```
+
+### Example (With Transitions and Labels)
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle
+    Idle --> Running : Start Event
+    Running --> Paused : Pause Event
+    Paused --> Running : Resume Event
+    Running --> Stopped : Stop Event
+    Stopped --> [*]
+```
+
+### Example (Composite States)
+
+```mermaid
+stateDiagram-v2
+    [*] --> First
+
+    state First {
+        [*] --> State1
+        State1 --> State2
+        State2 --> [*]
+    }
+
+    First --> Second
+
+    state Second {
+        [*] --> State3
+        State3 --> State4
+        State4 --> [*]
+    }
+
+    Second --> [*]
+```
+
+### Example (With Choice)
+
+```mermaid
+stateDiagram-v2
+    [*] --> State1
+    State1 --> Choice1 : Event1
+    Choice1 --> State2 : Condition1
+    Choice1 --> State3 : Condition2
+    State2 --> [*]
+    State3 --> [*]
+
+    state Choice1 <<choice>>
+```
+
+### Example (With Fork and Join)
+
+```mermaid
+stateDiagram-v2
+    [*] --> Fork1
+
+    state Fork1 <<fork>>
+    Fork1 --> State1
+    Fork1 --> State2
+    Fork1 --> State3
+
+    State1 --> Join1
+    State2 --> Join1
+    State3 --> Join1
+
+    state Join1 <<join>>
+    Join1 --> [*]
+```
+
+### Example (With Notes)
 
 ```mermaid
 stateDiagram-v2
     [*] --> Idle
     Idle --> Processing : Start
     Processing --> Completed : Success
+    Completed --> [*]
+
+    note right of Processing : This is a critical state
+    note left of Idle : Initial state
+```
+
+### Example (With Concurrency)
+
+```mermaid
+stateDiagram-v2
+    [*] --> State1
+    State1 --> State2
+    State2 --> State3
+
+    State2 --> Parallel1
+    State2 --> Parallel2
+
+    Parallel1 --> State4
+    Parallel2 --> State5
+
+    State4 --> State3
+    State5 --> State3
+    State3 --> [*]
+```
+
+### Example (With Direction - Left to Right)
+
+```mermaid
+stateDiagram-v2
+    direction LR
+    [*] --> State1
+    State1 --> State2 : Event
+    State2 --> [*]
+```
+
+### Example (With Styling)
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle
+    Idle --> Processing : Start
     Processing --> Error : Failure
     Error --> Idle : Retry
+    Processing --> Completed : Success
     Completed --> [*]
+
+    classDef errorState fill:#ff6b6b,stroke:#333,stroke-width:3px
+    classDef successState fill:#4ecdc4,stroke:#333,stroke-width:2px
+
+    class Error errorState
+    class Completed successState
+```
+
+### Example (With Spaces in State Names)
+
+```mermaid
+stateDiagram-v2
+    [*] --> yswsii
+    yswsii --> YetAnotherState
+
+    state yswsii : Your state with spaces in it
+    YetAnotherState --> [*]
+
+    classDef spacedState fill:#ffe66d,stroke:#333,stroke-width:2px
+    class yswsii spacedState
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If state diagrams are not supported, use this flowchart alternative:
+
+```mermaid
+flowchart TD
+    Start([Start]) --> Idle[Idle]
+    Idle -->|Start| Processing[Processing]
+    Processing -->|Success| Completed[Completed]
+    Processing -->|Failure| Error[Error]
+    Error -->|Retry| Idle
+    Completed --> End([End])
 ```

skills/mermaid/examples/timeline.md

@@ -1,19 +1,35 @@
 ## Instructions
 
-Timeline diagrams display events in chronological order, showing the sequence of events over time.
+Timeline diagrams display events in chronological order, showing the sequence of events over time. A timeline is a type of diagram used to illustrate a chronology of events, dates, or periods of time. It is usually presented graphically to indicate the passing of time, and it is usually organized chronologically. A basic timeline presents a list of events in chronological order, usually using dates as markers.
+
+**Note**: This is an experimental diagram type. The syntax and properties can change in future releases. The syntax is stable except for the icon integration which is the experimental part.
 
 ### Syntax
 
 - Use `timeline` keyword
-- Title: `title Timeline Title`
-- Sections: `section Period Name`
-- Events: `Event Description : Event details`
+- Title: `title Timeline Title` (optional)
+- Time period: `{time period} : {event}` or `{time period} : {event} : {event}` (multiple events per period)
+- Sections: `section Section Name` (groups time periods in sections/ages)
+- Text wrapping: Use `<br>` to force line breaks
+- Multiple events per period: Can be on same line with `:` separator or on separate lines
+
+Reference: [Mermaid Timeline Diagram Documentation](https://mermaid.ai/open-source/syntax/timeline.html)
 
-### Example
+### Example (Basic Timeline)
 
 ```mermaid
 timeline
     title Project Milestones
+    2024 Q1 : Project Kickoff : Team formation
+    2024 Q2 : Development Phase 1 : First Release
+    2024 Q3 : Development Phase 2 : Production Launch
+```
+
+### Example (With Sections)
+
+```mermaid
+timeline
+    title Product Development Timeline
     section 2024 Q1
         Project Kickoff : Team formation
         Requirements Gathering : Stakeholder meetings
@@ -24,3 +40,61 @@ timeline
         Development Phase 2 : Advanced features
         Production Launch : Public release
 ```
+
+### Example (Multiple Events per Period)
+
+```mermaid
+timeline
+    title Company History
+    2020 : Founded : First Product Launch
+    2021 : Series A Funding : Team Expansion
+    2022 : International Expansion : Second Product Launch
+    2023 : Series B Funding : Major Partnership
+```
+
+### Example (With Text Wrapping)
+
+```mermaid
+timeline
+    title Long Event Names
+    2024 Q1 : Project Kickoff and<br>Team Formation
+    2024 Q2 : Development Phase 1<br>Core Features Implementation
+    2024 Q3 : Production Launch<br>Public Release
+```
+
+### Example (Simple Timeline)
+
+```mermaid
+timeline
+    January 2024 : Project Start
+    February 2024 : Design Phase
+    March 2024 : Development Begins
+    April 2024 : Testing Phase
+    May 2024 : Launch
+```
+
+### Example (Historical Timeline)
+
+```mermaid
+timeline
+    title Technology Evolution
+    section 1990s
+        Early Internet : Web 1.0
+    section 2000s
+        Social Media : Web 2.0
+    section 2010s
+        Mobile Revolution : Cloud Computing
+    section 2020s
+        AI & Machine Learning : Web 3.0
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If timeline diagrams are not supported, use this flowchart alternative:
+
+```mermaid
+flowchart LR
+    Start[2024 Q1<br>Project Kickoff] --> Phase1[2024 Q2<br>Development Phase 1]
+    Phase1 --> Phase2[2024 Q3<br>Development Phase 2]
+    Phase2 --> Launch[2024 Q4<br>Production Launch]
+```

skills/mermaid/examples/treemap.md

@@ -1,28 +1,121 @@
 ## Instructions
 
-Treemap diagrams (beta) visualize hierarchical data as nested rectangles, where the size of each rectangle represents a value.
+Treemap diagrams display hierarchical data as a set of nested rectangles. Each branch of the tree is represented by a rectangle, which is then tiled with smaller rectangles representing sub-branches. The size of each rectangle is proportional to the value it represents, making it easy to compare different parts of a hierarchy.
+
+Treemap diagrams are particularly useful for:
+- Visualizing hierarchical data structures
+- Comparing proportions between categories
+- Displaying large amounts of hierarchical data in a limited space
+- Identifying patterns and outliers in hierarchical data
 
 ### Syntax
 
-- Use `treemap-beta` keyword
-- Title: `title Chart Title`
-- Hierarchy: Indentation determines parent-child relationships
-- Values: `Label : Value`
-- Colors can be applied to different levels
+- Use `treemap-beta` keyword (requires Mermaid v11.0.0+, experimental feature 🔥)
+- Section/Parent nodes: `"Section Name"` (quoted text)
+- Leaf nodes with values: `"Leaf Name": value` (quoted text followed by colon and value)
+- Hierarchy: Created using indentation (spaces or tabs)
+- Styling: Nodes can be styled using `:::class` syntax
+- Root node: The first node is the root of the tree
+- **Important**: If your environment doesn't support treemap, use the flowchart alternative below
+
+Reference: [Mermaid Treemap Diagram Documentation](https://mermaid.ai/open-source/syntax/treemap.html)
+
+### Example (Basic Treemap)
+
+```mermaid
+treemap-beta
+"Sales"
+    "Region A": 500
+    "Region B": 300
+    "Region C": 200
+```
+
+### Example (Hierarchical Treemap)
 
-### Example
+```mermaid
+treemap-beta
+"Sales"
+    "Region A": 500
+        "Product A1": 200
+        "Product A2": 150
+        "Product A3": 150
+    "Region B": 300
+        "Product B1": 120
+        "Product B2": 180
+    "Region C": 200
+        "Product C1": 100
+        "Product C2": 100
+```
+
+### Example (With Styling)
 
 ```mermaid
 treemap-beta
-    title Sales by Region
-    Region A : 500
-        Product A1 : 200
-        Product A2 : 150
-        Product A3 : 150
-    Region B : 300
-        Product B1 : 120
-        Product B2 : 180
-    Region C : 200
-        Product C1 : 100
-        Product C2 : 100
+"Sales":::highlight
+    "Region A": 500:::regionA
+    "Region B": 300:::regionB
+    "Region C": 200:::regionC
+
+classDef highlight fill:#ff6b6b,stroke:#333,stroke-width:3px
+classDef regionA fill:#4ecdc4,stroke:#333,stroke-width:2px
+classDef regionB fill:#45b7d1,stroke:#333,stroke-width:2px
+classDef regionC fill:#f9ca24,stroke:#333,stroke-width:2px
+```
+
+### Example (File System Structure)
+
+```mermaid
+treemap-beta
+"Disk Usage"
+    "System": 500
+        "Applications": 200
+        "Library": 150
+        "Users": 150
+    "Documents": 300
+        "Projects": 180
+        "Downloads": 120
+    "Media": 200
+        "Photos": 120
+        "Videos": 80
+```
+
+### Example (Budget Allocation)
+
+```mermaid
+treemap-beta
+"Budget"
+    "Development": 50000
+        "Salaries": 35000
+        "Tools": 10000
+        "Training": 5000
+    "Marketing": 30000
+        "Advertising": 20000
+        "Events": 10000
+    "Operations": 20000
+        "Infrastructure": 15000
+        "Support": 5000
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If treemap diagrams are not supported, use this flowchart alternative:
+
+```mermaid
+flowchart TD
+    Root["Sales: 1000"]
+    A["Region A: 500"]
+    B["Region B: 300"]
+    C["Region C: 200"]
+
+    Root --> A
+    Root --> B
+    Root --> C
+
+    A1["Product A1: 200"]
+    A2["Product A2: 150"]
+    A3["Product A3: 150"]
+
+    A --> A1
+    A --> A2
+    A --> A3
 ```

skills/mermaid/examples/xychart.md

@@ -1,23 +1,80 @@
 ## Instructions
 
-XY charts display data using X and Y axes, supporting bar charts, line charts, and area charts.
+XY charts display data using X and Y axes, supporting bar charts and line charts. The XY chart module is designed to be dynamic and adaptable, with capacity for expansion to include additional chart types in the future.
 
 ### Syntax
 
-- Use `xychart-beta` keyword
-- Title: `title Chart Title`
-- X-axis: `x-axis [categories]`
-- Y-axis: `y-axis "Label" [min, max]`
-- Series: `bar [values]` or `line [values]` or `area [values]`
+- Use `xychart` keyword (not `xychart-beta`)
+- Orientation: `xychart horizontal` (default is vertical)
+- Title: `title "Chart Title"` (quotes needed if title has spaces)
+- X-axis:
+  - Numeric range: `x-axis title min --> max`
+  - Categorical: `x-axis "title" [cat1, "cat2 with space", cat3]`
+- Y-axis:
+  - `y-axis title min --> max` (numeric range)
+  - `y-axis title` (auto-generated range from data)
+- Series:
+  - `line [values]` - Line chart with numeric values
+  - `bar [values]` - Bar chart with numeric values
 - Multiple series can be defined
+- **Simplest example**: Only chart name and one data set required
 
-### Example
+Reference: [Mermaid XY Chart Documentation](https://mermaid.ai/open-source/syntax/xyChart.html)
+
+### Example (Simplest)
+
+```mermaid
+xychart
+    line [+1.3, .6, 2.4, -.34]
+```
+
+### Example (Bar Chart)
 
 ```mermaid
-xychart-beta
+xychart
     title "Sales Performance"
     x-axis [Jan, Feb, Mar, Apr, May, Jun]
     y-axis "Sales" 0 --> 1000
     bar [500, 600, 750, 800, 950, 1000]
-    line [450, 550, 700, 750, 900, 950]
+```
+
+### Example (Line Chart)
+
+```mermaid
+xychart
+    title "Revenue Trend"
+    x-axis "Month" [Jan, Feb, Mar, Apr, May]
+    y-axis "Revenue" 0 --> 5000
+    line [1200, 1900, 3000, 5000, 4000]
+```
+
+### Example (Multiple Series)
+
+```mermaid
+xychart
+    title "Sales vs Revenue"
+    x-axis [Q1, Q2, Q3, Q4]
+    y-axis "Amount" 0 --> 10000
+    bar [5000, 6000, 7500, 8000]
+    line [4500, 5500, 7000, 7500]
+```
+
+### Example (Horizontal Orientation)
+
+```mermaid
+xychart horizontal
+    title "Product Comparison"
+    x-axis "Score" 0 --> 100
+    y-axis [Product A, Product B, Product C]
+    bar [85, 70, 90]
+```
+
+### Example (Numeric X-axis Range)
+
+```mermaid
+xychart
+    title "Function Plot"
+    x-axis "X" 0 --> 10
+    y-axis "Y" -5 --> 5
+    line [0, 1, 2, 3, 4, 5, 4, 3, 2, 1, 0]
 ```

skills/mermaid/examples/zenuml.md

@@ -1,26 +1,188 @@
 ## Instructions
 
-ZenUML diagrams provide a simplified way to create sequence diagrams with a more concise syntax.
+ZenUML provides a simplified way to create sequence diagrams with a more concise syntax than the original Sequence Diagram in Mermaid. A sequence diagram is an interaction diagram that shows how processes operate with one another and in what order.
 
 ### Syntax
 
 - Use `zenuml` keyword
-- Participants: `participant Name`
-- Messages: `Name1.method() -> Name2`
-- Return: `Name2.result() -> Name1`
-- Activations: `activate Name`, `deactivate Name`
-- Notes: `note over Name: Note text`
+- Participants: Defined implicitly by order of appearance, or explicitly with `participant Name`
+- Annotators: Use symbols instead of rectangles (e.g., `@Actor`, `@User`, `@Database`)
+- Aliases: `participant Alias as "Label"`
+- Messages:
+  - Sync message: `Participant1.method() -> Participant2` (blocking)
+  - Async message: `Participant1.method() => Participant2` (non-blocking)
+  - Creation message: `new Participant()` (creates new object)
+  - Reply message: `Participant2.result() -> Participant1` or `@return` or `return`
+- Nesting: Sync and Creation messages are naturally nestable with `{}`
+- Comments: `// comment` (Markdown supported)
+- Control structures:
+  - Loops: `while(condition)`, `for(condition)`, `forEach(condition)`, `loop(condition)`
+  - Alt: `if(condition) { } else if(condition) { } else { }`
+  - Opt: `opt { }`
+  - Parallel: `par { statement1 statement2 }`
+  - Try/Catch/Finally: `try { } catch { } finally { }`
 
-### Example
+Reference: [Mermaid ZenUML Documentation](https://mermaid.ai/open-source/syntax/zenuml.html)
+
+### Example (Basic Sequence)
+
+```mermaid
+zenuml
+    User.login() -> System
+    System.validate() -> Database
+    Database.query() -> System
+    System.response() -> User
+```
+
+### Example (With Participants)
 
 ```mermaid
 zenuml
     participant User
     participant System
     participant Database
-    
+
     User.login() -> System
     System.validate() -> Database
     Database.query() -> System
     System.response() -> User
 ```
+
+### Example (Sync and Async Messages)
+
+```mermaid
+zenuml
+    participant Client
+    participant Server
+
+    Client.sendRequest() -> Server
+    Server.process() -> Database
+    Server.notify() => Client
+    Server.response() -> Client
+```
+
+### Example (With Nesting)
+
+```mermaid
+zenuml
+    User.login() -> System {
+        System.validate() -> Database
+        Database.check() -> System
+    }
+    System.response() -> User
+```
+
+### Example (With Loops)
+
+```mermaid
+zenuml
+    participant User
+    participant System
+
+    User.request() -> System
+    while(hasMoreData) {
+        System.fetch() -> Database
+        Database.result() -> System
+        System.send() -> User
+    }
+    System.complete() -> User
+```
+
+### Example (With Alt - Alternative Paths)
+
+```mermaid
+zenuml
+    User.login() -> System
+    if(valid) {
+        System.success() -> User
+    } else {
+        System.error() -> User
+    }
+```
+
+### Example (With Opt - Optional)
+
+```mermaid
+zenuml
+    User.request() -> System
+    opt(cacheAvailable) {
+        System.getFromCache() -> Cache
+        Cache.data() -> System
+    }
+    System.response() -> User
+```
+
+### Example (With Parallel)
+
+```mermaid
+zenuml
+    User.request() -> System
+    par {
+        System.process1() -> Service1
+        System.process2() -> Service2
+        System.process3() -> Service3
+    }
+    System.combine() -> User
+```
+
+### Example (With Try/Catch/Finally)
+
+```mermaid
+zenuml
+    User.request() -> System
+    try {
+        System.process() -> Database
+        Database.result() -> System
+    } catch {
+        System.error() -> User
+    } finally {
+        System.cleanup()
+    }
+```
+
+### Example (With Annotators)
+
+```mermaid
+zenuml
+    @Actor User
+    @System API
+    @Database DB
+
+    User.login() -> API
+    API.validate() -> DB
+    DB.query() -> API
+    API.response() -> User
+```
+
+### Example (With Comments)
+
+```mermaid
+zenuml
+    // User authentication flow
+    User.login() -> System
+    // Validate credentials
+    System.validate() -> Database
+    Database.check() -> System
+    // Return result
+    System.response() -> User
+```
+
+### Alternative (Standard Sequence Diagram - compatible with all Mermaid versions)
+
+If ZenUML is not supported, use the standard sequence diagram:
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant S as System
+    participant D as Database
+
+    U->>S: Login Request
+    activate S
+    S->>D: Query User
+    activate D
+    D-->>S: User Data
+    deactivate D
+    S-->>U: Login Success
+    deactivate S
+```