Merge pull request #2 from teachingai/teachingai/merge_skills

Teachingai/merge skills

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 会根据技能描述自动判断何时使用该技能。
@@ -98,7 +106,7 @@ python convert_all.py ../skills ../adapters-output
 
 ## 可用插件和技能
 
-本仓库的技能按功能分为 7 个插件类别，共包含 23 个技能：
+本仓库的技能按功能分为 7 个插件类别，共包含 24 个技能：
 
 ### 1. teaching-skills（教学技能集合）
 
@@ -185,30 +193,43 @@ Markdown 相关技能集合，包括 Mermaid 图表绘制等。
 
 #### mermaid（Mermaid 图表绘制）
 
-创建各种类型的 Mermaid 图表，包括流程图、时序图、类图、状态图、甘特图等。
+创建各种类型的 Mermaid 图表，支持 23 种图表类型，包括流程图、时序图、类图、状态图、甘特图、架构图等。
 
 **使用示例：**
 - "使用 Mermaid 创建一个流程图"
 - "绘制一个系统架构的 C4 图"
 - "生成一个项目时间线的甘特图"
 - "创建一个用户旅程图"
-
-**支持的图表类型：**
-- 流程图（flowchart）
-- 时序图（sequence diagram）
-- 类图（class diagram）
-- 状态图（state diagram）
-- 实体关系图（ER diagram）
-- 用户旅程图（user journey）
-- 甘特图（Gantt chart）
-- 饼图（pie chart）
-- 象限图（quadrant chart）
-- Git 图（Git graph）
-- C4 架构图（C4 diagram）
-- 思维导图（mindmap）
-- 时间线图（timeline）
-- 桑基图（Sankey diagram）
-- 以及其他多种图表类型
+- "绘制一个类图展示系统设计"
+- "生成一个甘特图展示项目进度"
+- "创建一个思维导图整理知识点"
+- "绘制一个时序图展示系统交互"
+
+**支持的图表类型（共 23 种）：**
+
+1. **流程图（Flowchart）** - 展示流程、决策和过程
+2. **时序图（Sequence Diagram）** - 展示对象之间的交互顺序
+3. **类图（Class Diagram）** - 展示类、接口和它们之间的关系
+4. **状态图（State Diagram）** - 展示对象的状态转换
+5. **实体关系图（ER Diagram）** - 展示数据库实体和关系
+6. **用户旅程图（User Journey）** - 展示用户体验流程
+7. **甘特图（Gantt Chart）** - 展示项目时间线和任务进度
+8. **饼图（Pie Chart）** - 展示数据比例分布
+9. **象限图（Quadrant Chart）** - 展示二维数据分类
+10. **Git 图（Git Graph）** - 展示 Git 分支和提交历史
+11. **C4 架构图（C4 Diagram）** - 展示系统架构（Context、Container、Component、Deployment）
+12. **思维导图（Mindmap）** - 展示层次化信息结构
+13. **时间线图（Timeline）** - 展示事件的时间顺序
+14. **桑基图（Sankey Diagram）** - 展示流量和流向
+15. **架构图（Architecture Diagram）** - 展示系统架构和服务关系
+16. **块图（Block Diagram）** - 展示系统组件和连接
+17. **看板图（Kanban）** - 展示任务看板和工作流
+18. **数据包图（Packet Diagram）** - 展示网络数据包结构
+19. **雷达图（Radar Chart）** - 展示多维度数据对比
+20. **需求图（Requirement Diagram）** - 展示系统需求和关系
+21. **树状图（Treemap）** - 展示层次化数据
+22. **XY 图表（XY Chart）** - 展示二维数据关系
+23. **ZenUML 图（ZenUML Diagram）** - 使用 ZenUML 语法绘制 UML 图
 
 ### 4. development-skills（开发技能集合）
 
@@ -241,6 +262,48 @@ Markdown 相关技能集合，包括 Mermaid 图表绘制等。
 - "创建一个用户使用手册"
 - "编写开发环境搭建指南"
 
+#### zh-product-doc-generator（项目文档生成技能）
+
+基于标准模板快速生成项目文档，包括产品调研、需求分析、PRD、架构设计、技术文档等 14 种项目交付文档模板。适用于软件开发项目的全生命周期文档生成，基于 DDD（领域驱动设计）和 COLA 架构思想。
+
+**使用示例：**
+- "使用项目文档生成技能，帮我生成一个 PRD 文档"
+- "基于模板生成系统架构设计文档，项目名称是 TeachingAI 教学平台"
+- "为我的项目生成全套文档，包括 PRD、架构设计、技术文档"
+- "生成一个产品调研文档"
+- "创建需求分析文档"
+- "生成领域模型说明文档"
+
+**支持的文档模板（共 14 种）：**
+
+**产品阶段文档：**
+1. **产品调研模板** - 市场调研、用户调研、竞品分析
+2. **需求调研模板** - 需求收集、用户访谈、需求整理
+3. **技术调研模板** - 技术选型、技术可行性分析、技术对比
+4. **需求分析模板** - 需求拆解、优先级排序、需求评审
+
+**设计阶段文档：**
+5. **PRD文档模板** - 产品需求文档，包含功能需求、用户故事、验收标准
+6. **视觉与交互 DNA 规范模板** - 设计语言、交互规范、视觉规范
+7. **UI 设计说明模板** - UI设计规范、组件库、设计系统
+
+**技术设计文档：**
+8. **领域模型说明模板** - DDD领域模型、实体、值对象、聚合
+9. **系统架构设计模板** - 技术架构、系统架构、部署架构
+10. **技术细分模板** - 接口设计、数据库设计、技术实现细节
+
+**测试与交付文档：**
+11. **功能提测模板** - 提测清单、测试环境、测试范围
+12. **测试结果模板** - 测试报告、缺陷统计、测试结论
+13. **上线通知模板** - 上线计划、上线检查清单、回滚方案
+14. **项目运维模板** - 运维手册、监控告警、故障处理
+
+**特点：**
+- 标准化结构，统一的文档格式和结构
+- 基于 DDD 和 COLA 架构思想
+- 全生命周期覆盖，从产品调研到项目运维
+- 易于定制，使用占位符便于替换
+
 #### mcp-builder（MCP 构建器）
 
 帮助创建和配置 Model Context Protocol (MCP) 服务器。
@@ -375,6 +438,7 @@ Markdown 相关技能集合，包括 Mermaid 图表绘制等。
 │   │   ├── code-generator/
 │   │   ├── test-writer/
 │   │   ├── documentation-builder/
+│   │   ├── zh-product-doc-generator/
 │   │   ├── mcp-builder/
 │   │   ├── webapp-testing/
 │   │   ├── frontend-design/
@@ -509,7 +573,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

@@ -36,7 +36,7 @@ To create a Mermaid diagram:
    - Quadrant chart/象限图 → `quadrantChart`
    - Requirement diagram/需求图 → `requirementDiagram`
    - Git graph/Git图 → `gitGraph`
-   - C4 diagram/C4图 → `C4Context` or other C4 types
+   - C4 diagram/C4图 → `C4Context`, `C4Container`, `C4Component`, `C4Deployment`, or `C4Dynamic`
    - Mindmap/思维导图 → `mindmap`
    - Timeline/时间线图 → `timeline`
    - ZenUML/禅UML → `zenuml`
@@ -45,9 +45,9 @@ To create a Mermaid diagram:
    - Block diagram/方块图 → `block`
    - Packet diagram/数据包图 → `packet`
    - Kanban/看板图 → `kanban`
-   - Architecture diagram/架构图 → `architecture-beta`
-   - Radar chart/雷达图 → `radar-beta`
-   - Treemap/树状图 → `treemap-beta`
+   - Architecture diagram/架构图 → `architecture-beta` (requires Mermaid v11.1.0+)
+   - Radar chart/雷达图 → `radar-beta` (requires Mermaid v11.1.0+)
+   - Treemap/树状图 → `treemap-beta` (requires Mermaid v11.1.0+)
 
 2. **Load the appropriate example file** from the `examples/` directory:
    - `examples/flowchart.md` - For flowcharts and process diagrams
@@ -76,11 +76,28 @@ 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:
+   **Important Notes**:
+   - Beta diagram types (`architecture-beta`, `radar-beta`, `treemap-beta`) require Mermaid v11.1.0 or higher
+   - If the rendering environment doesn't support beta diagram types, use the flowchart alternatives provided in the example files
+   - Always check the example file for version compatibility notes and alternative syntax options
+
+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
@@ -90,11 +107,78 @@ To create a Mermaid diagram:
 6. **Validate the syntax**:
    - Ensure all required elements are present
    - Check that relationships and connections are properly defined
-   - Verify date formats for Gantt charts
+   - Verify date formats for Gantt charts (YYYY-MM-DD)
    - Confirm data formats for charts (pie, quadrant, etc.)
+   - For ER diagrams: Use underscores instead of hyphens in entity names (e.g., `LINE_ITEM` not `LINE-ITEM`)
+   - For flowcharts: Avoid using "end" as a node label (use "End" or "END" instead)
+   - For class diagrams: Escape special characters in labels using backticks
+   - Check version compatibility for beta diagram types
+
+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.
 
+## Version Compatibility
+
+Some diagram types have specific version requirements:
+
+- **Beta diagram types** (require Mermaid v11.1.0+):
+  - `architecture-beta` - Architecture diagrams
+  - `radar-beta` - Radar charts
+  - `treemap-beta` - Treemap diagrams
+
+- **Advanced features** (require specific versions):
+  - Participant types with JSON configuration: Mermaid v10.0.0+
+  - Actor creation/destruction: Mermaid v10.3.0+
+  - Edge IDs and curve styles: Mermaid v11.10.0+
+  - New shapes with `@{}` syntax: Mermaid v11.3.0+
+
+If a beta diagram type is not supported, the example files provide flowchart alternatives that work with all Mermaid versions.
+
+## Best Practices
+
+1. **Always use code blocks**: Wrap all Mermaid code in Markdown code blocks with `mermaid` language tag
+2. **Check compatibility**: Verify version requirements before using beta diagram types
+3. **Use alternatives**: When beta types aren't supported, use the provided flowchart alternatives
+4. **Follow naming conventions**: Avoid reserved keywords and special characters in node labels
+5. **Test syntax**: Validate diagram syntax before saving to ensure proper rendering
+6. **Organize files**: Save diagrams in appropriate directories (`docs/diagrams/` or `diagrams/`)
+7. **Use descriptive names**: Name diagram files clearly (e.g., `system-architecture.md`, `user-flow.md`)
+
 ## Keywords
 
 mermaid, diagram, flowchart, flow chart, sequence diagram, class diagram, state diagram, entity relationship, ER diagram, user journey, Gantt chart, pie chart, quadrant chart, requirement diagram, Git graph, C4 diagram, mindmap, timeline, ZenUML, Sankey diagram, XY chart, block diagram, packet diagram, Kanban, architecture diagram, radar chart, treemap, 流程图, 时序图, 类图, 状态图, 实体关系图, 用户旅程图, 甘特图, 饼图, 象限图, 需求图, Git图, C4图, 思维导图, 时间线图, 桑基图, XY图, 方块图, 数据包图, 看板图, 架构图, 雷达图, 树状图

skills/mermaid/examples/architecture.md

@@ -1,25 +1,276 @@
 ## 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 api(cloud)[API]
+    service db(database)[Database] in api
+    service disk1(disk)[Storage] in api
+    service disk2(disk)[Storage] in api
+    service server(server)[Server] in api
+    db:L -- R:server
+    disk1:T -- B:server
+    disk2:T -- B:db
+```
+
+**Flowchart Alternative (Compatible with all versions):**
+
+```mermaid
+flowchart TD
+    subgraph API["API"]
+        DB[(Database)]
+        Disk1[(Storage)]
+        Disk2[(Storage)]
+        Server[Server]
+    end
+    DB --> Server
+    Disk1 --> Server
+    Disk2 --> DB
+```
+
+### 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 (With Arrows)
+
+**Note**: Requires Mermaid v11.1.0+. If not supported, use the flowchart alternative below.
+
+```mermaid
+architecture-beta
+    service subnet(server)[Subnet]
+    service gateway(internet)[Gateway]
+
+    subnet:R --> L:gateway
+```
+
+**Flowchart Alternative (Compatible with all versions):**
+
+```mermaid
+flowchart LR
+    Subnet[Subnet]
+    Gateway[Gateway]
+
+    Subnet --> 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):**
 
-### Example
+```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
-    component Frontend
-    component API
-    component Database
-    component Cache
-    
-    Frontend -->|HTTP| API
-    API -->|Query| Database
-    API -->|Read/Write| Cache
+    service left_disk(disk)[Disk]
+    service top_disk(disk)[Disk]
+    service bottom_disk(disk)[Disk]
+    service top_gateway(internet)[Gateway]
+    service bottom_gateway(internet)[Gateway]
+    junction junctionCenter
+    junction junctionRight
+
+    left_disk:R -- L:junctionCenter
+    top_disk:B -- T:junctionCenter
+    bottom_disk:T -- B:junctionCenter
+    junctionCenter:R -- L:junctionRight
+    top_gateway:B -- T:junctionRight
+    bottom_gateway:T -- B:junctionRight
+```
+
+**Flowchart Alternative (Compatible with all versions):**
+
+```mermaid
+flowchart TD
+    LeftDisk[(Disk)]
+    TopDisk[(Disk)]
+    BottomDisk[(Disk)]
+    TopGateway[Gateway]
+    BottomGateway[Gateway]
+
+    LeftDisk --> TopDisk
+    LeftDisk --> BottomDisk
+    TopDisk --> TopGateway
+    BottomDisk --> BottomGateway
+```
+
+### 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}
+```
+
+**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
+    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
+```
+
+### Example (With Custom Icons)
+
+**Note**: Requires Mermaid v11.1.0+ and icon pack registration. If not supported, use the flowchart alternative below.
+
+```mermaid
+architecture-beta
+    group api(logos:aws-lambda)[API]
+    service db(logos:aws-aurora)[Database] in api
+    service disk1(logos:aws-glacier)[Storage] in api
+    service disk2(logos:aws-s3)[Storage] in api
+    service server(logos:aws-ec2)[Server] in api
+    db:L -- R:server
+    disk1:T -- B:server
+    disk2:T -- B:db
+```
+
+**Flowchart Alternative (Compatible with all versions):**
+
+```mermaid
+flowchart TD
+    subgraph API["API"]
+        DB[(Database)]
+        Disk1[(Storage)]
+        Disk2[(Storage)]
+        Server[Server]
+    end
+    DB --> Server
+    Disk1 --> Server
+    Disk2 --> DB
 ```

skills/mermaid/examples/block.md

@@ -1,23 +1,291 @@
 ## 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`
-- Labels: `Block1 -->|Label| Block2`
-- Groups: `blockGroup GroupName { }`
+- Use `block` keyword
+- Basic blocks: `block BlockName` or just `BlockName`
+- Columns: `columns N` to specify number of columns to organize blocks
+- Block width: `BlockName:N` where N is the number of columns to span
+- Composite blocks: `block:ID ... end` for nested blocks within parent blocks
+- Connections: `Block1 --> Block2` or `Block1 --- Block2`
+- Labels: `Block1 -- "Label" --> Block2`
+- Block shapes: rectangle (default), `("Round")`, `(["Stadium"])`, `[["Subroutine"]]`, `[("Cylindrical")]`, `(("Circle"))`, `{"Diamond"}`, `{{"Hexagon"}}`, `>"Asymmetric"]`, `[/"Parallelogram"/]`, `[\"Trapezoid"\`, `((("Double Circle")))`
+- Block arrows: `blockArrowId<["Label"]>(direction)` where direction is `right`, `left`, `up`, `down`, `x`, `y`, or combinations
+- Space blocks: `space` or `space:N` for intentional spacing (N is number of columns)
+- Styling: `style BlockName fill:#color,stroke:#color,stroke-width:2px`
+- Class styling: `classDef className fill:#color` and `class BlockName className`
 
-### Example
+Reference: [Mermaid Block Diagram Documentation](https://mermaid.js.org/syntax/block.html)
+
+### Example (Simple Block Diagram)
+
+A simple block diagram with three blocks:
+
+```mermaid
+block
+  a b c
+```
+
+### Example (Multi-Column Layout)
+
+Specify the number of columns to organize blocks:
+
+```mermaid
+block
+  columns 3
+  a b c d
+```
+
+### Example (Block Spanning Multiple Columns)
+
+Blocks can span multiple columns using `:N` notation:
+
+```mermaid
+block
+  columns 3
+  a["A label"] b:2 c:2 d
+```
+
+### Example (Composite Blocks)
+
+Create nested blocks using `block:ID ... end`:
+
+```mermaid
+block
+    block
+      D
+    end
+    A["A: I am a wide one"]
+```
+
+### Example (Composite Blocks with Columns)
+
+Create composite blocks with column configuration:
+
+```mermaid
+block
+  columns 3
+  a:3
+  block:group1:2
+    columns 2
+    h i j k
+  end
+  g
+  block:group2:3
+    l m n o p q r
+  end
+```
+
+### Example (Vertical Stacking)
+
+Stack blocks vertically using single column:
+
+```mermaid
+block
+  block
+    columns 1
+    a["A label"] b c d
+  end
+```
+
+### Example (Block Shapes)
+
+Use different shapes for blocks:
+
+```mermaid
+block
+    id1("Round")
+    id2(["Stadium"])
+    id3[["Subroutine"]]
+    id4[("Cylindrical")]
+    id5(("Circle"))
+    id6{"Diamond"}
+    id7{{"Hexagon"}}
+    id8>"Asymmetric"]
+    id9[/"Parallelogram"/]
+    id10[\"Trapezoid"\]
+    id11((("Double Circle")))
+```
+
+### Example (Individual Shape Examples)
+
+Examples of each shape type:
+
+```mermaid
+block
+    id1("This is the text in the box")
+```
+
+```mermaid
+block
+    id1(["This is the text in the box"])
+```
+
+```mermaid
+block
+    id1[["This is the text in the box"]]
+```
+
+```mermaid
+block
+    id1[("Database")]
+```
+
+```mermaid
+block
+    id1(("This is the text in the circle"))
+```
+
+```mermaid
+block
+    id1>"This is the text in the box"]
+```
+
+```mermaid
+block
+    id1{"This is the text in the box"}
+```
+
+```mermaid
+block
+    id1{{"This is the text in the box"}}
+```
+
+```mermaid
+block
+    id1[/"This is the text in the box"/]
+    id2[\"This is the text in the box"\]
+```
+
+```mermaid
+block
+    id1((("This is the text in the circle")))
+```
+
+### Example (Block Arrows)
+
+Use block arrows to indicate direction or flow:
+
+```mermaid
+block
+  blockArrowId<["Label"]>(right)
+  blockArrowId2<["Label"]>(left)
+  blockArrowId3<["Label"]>(up)
+  blockArrowId4<["Label"]>(down)
+  blockArrowId5<["Label"]>(x)
+  blockArrowId6<["Label"]>(y)
+  blockArrowId7<["Label"]>(x, down)
+```
+
+### Example (Space Blocks)
+
+Create intentional empty spaces using `space` or `space:N`:
+
+```mermaid
+block
+  columns 3
+  a space b
+  c   d   e
+```
+
+Or specify column width:
+
+```mermaid
+block
+  ida space:3 idb idc
+```
+
+### Example (Basic Connections)
+
+Connect blocks using arrows:
+
+```mermaid
+block
+  A space B
+  A-->B
+```
+
+### Example (Connections with Labels)
+
+Add text to links:
+
+```mermaid
+block
+  A space:2 B
+  A-- "X" -->B
+```
+
+### Example (Styling)
+
+Apply styles to individual blocks:
+
+```mermaid
+block
+  id1 space id2
+  id1("Start")-->id2("Stop")
+  style id1 fill:#636,stroke:#333,stroke-width:4px
+  style id2 fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
+```
+
+### Example (Class Styling)
+
+Define reusable style classes:
+
+```mermaid
+block
+  A space B
+  A-->B
+  classDef blue fill:#6e6ce6,stroke:#333,stroke-width:4px;
+  class A blue
+  style B fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
+```
+
+### Example (System Architecture)
+
+A system architecture example with styling:
+
+```mermaid
+block
+  columns 3
+  Frontend blockArrowId6<[" "]>(right) Backend
+  space:2 down<[" "]>(down)
+  Disk left<[" "]>(left) Database[("Database")]
+
+  classDef front fill:#696,stroke:#333;
+  classDef back fill:#969,stroke:#333;
+  class Frontend front
+  class Backend,Database back
+```
+
+### Example (Business Process Flow)
+
+A business process flow with decision points:
+
+```mermaid
+block
+  columns 3
+  Start(("Start")) space:2
+  down<[" "]>(down) space:2
+  Decision{{"Make Decision"}} right<["Yes"]>(right) Process1["Process A"]
+  downAgain<["No"]>(down) space r3<["Done"]>(down)
+  Process2["Process B"] r2<["Done"]>(right) End(("End"))
+
+  style Start fill:#969;
+  style End fill:#696;
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If block diagrams are not supported, use this flowchart alternative:
 
 ```mermaid
-block-beta
-    block Input
-    block Process
-    block Output
+flowchart TD
+    A[Component A]
+    B[Component B]
+    C[Component C]
     
-    Input -->|Data| Process
-    Process -->|Result| Output
+    A -->|Data| B
+    B -->|Result| C
 ```

skills/mermaid/examples/c4.md

@@ -1,30 +1,225 @@
 ## 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 (C4Context - System Context Diagram)
 
-### Example
+Basic system context diagram with Person, System, System_Ext, and SystemDb:
 
 ```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)
+
+Use BiRel for bidirectional relationships:
+
+```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")
+```
+
+### Example (With Directional Relationships)
+
+Use Rel_U, Rel_D, Rel_L, Rel_R for directional relationships:
+
+```mermaid
+C4Deployment
+    title Deployment with Directional Relationships
+
+    Deployment_Node(web, "Web Server", "Linux", "Apache Tomcat"){
+        Container(webapp, "Web Application", "Java", "Web application")
+    }
+    Deployment_Node(browser, "Browser", "Chrome", "Web browser"){
+        Container(spa, "SPA", "JavaScript", "Single page app")
+    }
+
+    Rel_U(webapp, spa, "Delivers to")
+    Rel_D(spa, webapp, "Makes requests to")
+```
+
+### Example (With Style Updates)
+
+Update element and relationship styles using UpdateElementStyle and UpdateRelStyle:
+
+```mermaid
+C4Context
+    title System Context with Styles
+
+    Person(customer, "Customer", "A customer")
+    System(webapp, "Web Application", "Main application")
+    SystemDb(database, "Database", "Data storage")
+
+    Rel(customer, webapp, "Uses")
+    Rel(webapp, database, "Uses")
+
+    UpdateElementStyle(customer, $fontColor="red", $bgColor="grey", $borderColor="red")
+    UpdateRelStyle(customer, webapp, $textColor="blue", $lineColor="blue", $offsetX="5")
+    UpdateRelStyle(webapp, database, $textColor="blue", $lineColor="blue", $offsetY="-10")
+```
+
+### Example (With Layout Configuration)
+
+Configure layout using UpdateLayoutConfig:
+
+```mermaid
+C4Context
+    title System Context with Layout Config
+
+    Person(customer, "Customer", "A customer")
+    System(webapp, "Web Application", "Main application")
+    System_Ext(email, "Email System", "Email service")
+    SystemDb(database, "Database", "Data storage")
+
+    Rel(customer, webapp, "Uses")
+    Rel(webapp, database, "Uses")
+    Rel(webapp, email, "Sends emails")
+
+    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
+```
+
+### 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,39 +1,453 @@
 ## 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. The class diagram is the main building block of object-oriented modeling.
 
 ### 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.js.org/syntax/classDiagram.html)
+
+### Example (Basic Class Diagram)
+
+A simple class diagram showing classes with members and relationships:
+
+```mermaid
+---
+title: Animal example
+---
+classDiagram
+    note "From Duck till Zebra"
+    Animal <|-- Duck
+    note for Duck "can fly\ncan swim\ncan dive\ncan help in debugging"
+    Animal <|-- Fish
+    Animal <|-- Zebra
+    Animal : +int age
+    Animal : +String gender
+    Animal: +isMammal()
+    Animal: +mate()
+    class Duck{
+        +String beakColor
+        +swim()
+        +quack()
+    }
+    class Fish{
+        -int sizeInFeet
+        -canEat()
+    }
+    class Zebra{
+        +bool is_wild
+        +run()
+    }
+```
+
+### Example (Define a class)
+
+There are two ways to define a class: explicitly using `class` keyword or via a relationship:
+
+```mermaid
+classDiagram
+    class Animal
+    Vehicle <|-- Car
+```
+
+### Example (Class labels)
+
+Provide a label for a class using square brackets:
+
+```mermaid
+classDiagram
+    class Animal["Animal with a label"]
+    class Car["Car with *! symbols"]
+    Animal --> Car
+```
+
+### Example (Class labels with backticks)
+
+Use backticks to escape special characters in class names:
+
+```mermaid
+classDiagram
+    class `Animal Class!`
+    class `Car Class`
+    `Animal Class!` --> `Car Class`
+```
+
+### Example (Defining Members)
+
+Define members using `:` (colon) or `{}` brackets. Methods are identified by `()`:
+
+```mermaid
+---
+title: Bank example
+---
+classDiagram
+    class BankAccount
+    BankAccount : +String owner
+    BankAccount : +Bigdecimal balance
+    BankAccount : +deposit(amount)
+    BankAccount : +withdrawal(amount)
+```
+
+Or using brackets:
+
+```mermaid
+classDiagram
+class BankAccount{
+    +String owner
+    +BigDecimal balance
+    +deposit(amount)
+    +withdrawal(amount)
+}
+```
+
+### Example (Return Type)
+
+End a method definition with the data type that will be returned (space between `)` and return type):
+
+```mermaid
+classDiagram
+class BankAccount{
+    +String owner
+    +BigDecimal balance
+    +deposit(amount) bool
+    +withdrawal(amount) int
+}
+```
+
+### Example (Generic Types)
+
+Enclose generic types within `~` (tilde):
+
+```mermaid
+classDiagram
+class Square~Shape~{
+    int id
+    List~int~ position
+    setPoints(List~int~ points)
+    getPoints() List~int~
+}
+
+Square : -List~string~ messages
+Square : +setMessages(List~string~ messages)
+Square : +getMessages() List~string~
+Square : +getDistanceMatrix() List~List~int~~
+```
+
+### Example (Visibility)
+
+Use `+` (Public), `-` (Private), `#` (Protected), `~` (Package/Internal) before member names:
 
 ```mermaid
 classDiagram
-    class Animal {
-        +String name
-        +int age
-        +eat()
-        +sleep()
+class BankAccount{
+    +String owner
+    -BigDecimal balance
+    #String accountNumber
+    ~String internalId
+}
+```
+
+### Example (Relationships)
+
+Eight types of relations are supported:
+
+```mermaid
+classDiagram
+classA <|-- classB
+classC *-- classD
+classE o-- classF
+classG <-- classH
+classI -- classJ
+classK <.. classL
+classM <|.. classN
+classO .. classP
+```
+
+### Example (Labels on Relations)
+
+Add label text to a relation:
+
+```mermaid
+classDiagram
+classA --|> classB : Inheritance
+classC --* classD : Composition
+classE --o classF : Aggregation
+classG --> classH : Association
+classI -- classJ : Link(Solid)
+classK ..> classL : Dependency
+classM ..|> classN : Realization
+classO .. classP : Link(Dashed)
+```
+
+### Example (Two-way relations)
+
+Represent N:M associations using two-way relations:
+
+```mermaid
+classDiagram
+    Animal <|--|> Zebra
+```
+
+### Example (Lollipop Interfaces)
+
+Define lollipop interfaces using `()--` or `--()`:
+
+```mermaid
+classDiagram
+  bar ()-- foo
+```
+
+### Example (Namespaces)
+
+Group classes using namespaces:
+
+```mermaid
+classDiagram
+namespace BaseShapes {
+    class Triangle
+    class Rectangle {
+      double width
+      double height
     }
-    class Dog {
-        +String breed
-        +bark()
+}
+```
+
+### Example (Cardinality)
+
+Place cardinality notations near the end of an association:
+
+```mermaid
+classDiagram
+    Customer "1" --> "*" Ticket
+    Student "1" --> "1..*" Course
+    Galaxy --> "many" Star : Contains
+```
+
+### Example (Annotations)
+
+Annotate classes with markers like `<<Interface>>`, `<<Abstract>>`, `<<Service>>`, `<<Enumeration>>`:
+
+```mermaid
+classDiagram
+class Shape{
+    <<interface>>
+    noOfVertices
+    draw()
+}
+class Color{
+    <<enumeration>>
+    RED
+    BLUE
+    GREEN
+    WHITE
+    BLACK
+}
+```
+
+### Example (Comments)
+
+Comments need to be on their own line, prefaced with `%%`:
+
+```mermaid
+classDiagram
+%% This whole line is a comment
+classDiagram
+class Shape <<interface>>
+class Shape{
+    <<interface>>
+    noOfVertices
+    draw()
+}
+```
+
+### Example (Direction)
+
+Set the direction using `direction` statement:
+
+```mermaid
+classDiagram
+  direction RL
+  class Student {
+    -idCard : IdCard
+  }
+  class IdCard{
+    -id : int
+    -name : string
+  }
+  class Bike{
+    -id : int
+    -name : string
+  }
+  Student "1" --o "1" IdCard : carries
+  Student "1" --o "1" Bike : rides
+```
+
+### Example (Notes)
+
+Add notes using `note` or `note for ClassName`:
+
+```mermaid
+classDiagram
+    note "This is a general note"
+    note for MyClass "This is a note for a class"
+    class MyClass{
     }
-    class Cat {
-        +meow()
+```
+
+### Example (Interaction - Links)
+
+Bind click events to nodes for links:
+
+```mermaid
+classDiagram
+class Shape
+link Shape "https://www.github.com" "This is a tooltip for a link"
+class Shape2
+click Shape2 href "https://www.github.com" "This is a tooltip for a link"
+```
+
+### Example (Interaction - Callbacks)
+
+Bind click events to nodes for callbacks:
+
+```mermaid
+classDiagram
+class Shape
+callback Shape "callbackFunction" "This is a tooltip for a callback"
+class Shape2
+click Shape2 call callbackFunction() "This is a tooltip for a callback"
+```
+
+### Example (Styling a node)
+
+Apply specific styles using `style` keyword:
+
+```mermaid
+classDiagram
+  class Animal
+  class Mineral
+  style Animal fill:#f9f,stroke:#333,stroke-width:4px
+  style Mineral fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
+```
+
+### Example (Classes)
+
+Define reusable style classes using `classDef` and apply with `:::`:
+
+```mermaid
+classDiagram
+    class Animal:::someclass
+    classDef someclass fill:#f96
+```
+
+Or with class members:
+
+```mermaid
+classDiagram
+    class Animal:::someclass {
+        -int sizeInFeet
+        -canEat()
     }
-    
-    Animal <|-- Dog
-    Animal <|-- Cat
+    classDef someclass fill:#f96
+```
+
+### Example (Default class)
+
+A class named `default` will be applied to all nodes:
+
+```mermaid
+classDiagram
+  class Animal:::pink
+  class Mineral
+
+  classDef default fill:#f96,color:red
+  classDef pink color:#f9f
+```
+
+### Example (CSS Classes)
+
+Predefine classes in CSS styles and apply from the graph definition:
+
+```mermaid
+classDiagram
+    class Animal:::styleClass
+```
+
+### Example (Using cssClass)
+
+Apply a class to a node using `cssClass`:
+
+```mermaid
+classDiagram
+    class Animal
+    class Mineral
+    classDef someclass fill:#f96
+    cssClass "Animal" someclass
+```
+
+### Example (Multiple Classes in classDef)
+
+Define styles for multiple classes in one statement:
+
+```mermaid
+classDiagram
+    class Animal
+    class Mineral
+    classDef firstClassName,secondClassName fill:#f9f,stroke:#333,stroke-width:2px;
+    cssClass "Animal" firstClassName
+    cssClass "Mineral" secondClassName
+```
+
+### Example (Configuration - Hide Empty Members Box)
+
+Hide the empty members box using configuration:
+
+```mermaid
+---
+  config:
+    class:
+      hideEmptyMembersBox: true
+---
+classDiagram
+  class Duck
+```
+
+### 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,331 @@
 ## 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. Mermaid uses the popular crow's foot notation to represent cardinality.
 
 ### 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.js.org/syntax/entityRelationshipDiagram.html)
+
+### Example (Basic ER Diagram)
+
+A simple ER diagram showing relationships between entities:
+
+```mermaid
+---
+title: Order example
+---
+erDiagram
+    CUSTOMER ||--o{ ORDER : places
+    ORDER ||--|{ LINE-ITEM : contains
+    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
+```
+
+### Example (With Attributes)
+
+Include attribute definitions to show entity properties:
 
 ```mermaid
 erDiagram
     CUSTOMER ||--o{ ORDER : places
-    ORDER ||--|{ ORDER_LINE : contains
-    PRODUCT ||--o{ ORDER_LINE : "ordered in"
-    
     CUSTOMER {
-        int customer_id PK
         string name
+        string custNumber
+        string sector
+    }
+    ORDER ||--|{ LINE-ITEM : contains
+    ORDER {
+        int orderNumber
+        string deliveryAddress
+    }
+    LINE-ITEM {
+        string productCode
+        int quantity
+        float pricePerUnit
+    }
+```
+
+### Example (Unicode text)
+
+Entity names, relationships, and attributes all support unicode text:
+
+```mermaid
+erDiagram
+    "This ❤ Unicode"
+```
+
+### Example (Markdown formatting)
+
+Markdown formatting and text is also supported:
+
+```mermaid
+erDiagram
+    "This **is** _Markdown_"
+```
+
+### Example (Identifying vs Non-identifying Relationships)
+
+Identifying relationships use `--` (solid line), non-identifying use `..` (dashed line):
+
+```mermaid
+erDiagram
+    CAR ||--o{ NAMED-DRIVER : allows
+    PERSON }o..o{ NAMED-DRIVER : is
+```
+
+### Example (Using Aliases for Cardinality)
+
+Cardinality markers can be specified using aliases:
+
+```mermaid
+erDiagram
+    CAR 1 to zero or more NAMED-DRIVER : allows
+    PERSON many(0) optionally to 0+ NAMED-DRIVER : is
+```
+
+### Example (With Attributes on Entities)
+
+Define attributes using `type name` pairs within entity blocks:
+
+```mermaid
+erDiagram
+    CAR ||--o{ NAMED-DRIVER : allows
+    CAR {
+        string registrationNumber
+        string make
+        string model
+    }
+    PERSON ||--o{ NAMED-DRIVER : is
+    PERSON {
+        string firstName
+        string lastName
+        int age
+    }
+```
+
+### Example (Entity Name Aliases)
+
+Add an alias using square brackets to display a different name:
+
+```mermaid
+erDiagram
+    p[Person] {
+        string firstName
+        string lastName
+    }
+    a["Customer Account"] {
         string email
     }
+    p ||--o| a : has
+```
+
+### Example (Attribute Keys and Comments)
+
+Use `PK`, `FK`, `UK` for keys and double quotes for comments:
+
+```mermaid
+erDiagram
+    CAR ||--o{ NAMED-DRIVER : allows
+    CAR {
+        string registrationNumber PK
+        string make
+        string model
+        string[] parts
+    }
+    PERSON ||--o{ NAMED-DRIVER : is
+    PERSON {
+        string driversLicense PK "The license #"
+        string(99) firstName "Only 99 characters are allowed"
+        string lastName
+        string phone UK
+        int age
+    }
+    NAMED-DRIVER {
+        string carRegistrationNumber PK, FK
+        string driverLicence PK, FK
+    }
+    MANUFACTURER only one to zero or more CAR : makes
+```
+
+### Example (Direction - Top to Bottom)
+
+Set diagram orientation using `direction TB` (top to bottom):
+
+```mermaid
+erDiagram
+    direction TB
+    CUSTOMER ||--o{ ORDER : places
+    CUSTOMER {
+        string name
+        string custNumber
+        string sector
+    }
+    ORDER ||--|{ LINE-ITEM : contains
     ORDER {
-        int order_id PK
-        date order_date
-        int customer_id FK
+        int orderNumber
+        string deliveryAddress
+    }
+    LINE-ITEM {
+        string productCode
+        int quantity
+        float pricePerUnit
     }
-    PRODUCT {
-        int product_id PK
+```
+
+### Example (Direction - Left to Right)
+
+Set diagram orientation using `direction LR` (left to right):
+
+```mermaid
+erDiagram
+    direction LR
+    CUSTOMER ||--o{ ORDER : places
+    CUSTOMER {
         string name
-        decimal price
+        string custNumber
+        string sector
     }
-    ORDER_LINE {
-        int order_id FK
-        int product_id FK
+    ORDER ||--|{ LINE-ITEM : contains
+    ORDER {
+        int orderNumber
+        string deliveryAddress
+    }
+    LINE-ITEM {
+        string productCode
         int quantity
+        float pricePerUnit
+    }
+```
+
+### Example (Styling a node)
+
+Apply specific styles using `style` statement:
+
+```mermaid
+erDiagram
+    id1||--||id2 : label
+    style id1 fill:#f9f,stroke:#333,stroke-width:4px
+    style id2 fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
+```
+
+### Example (Classes)
+
+Define reusable style classes using `classDef` and apply with `class` or `:::`:
+
+```mermaid
+erDiagram
+    direction TB
+    CAR:::someclass {
+        string registrationNumber
+        string make
+        string model
+    }
+    PERSON:::someclass {
+        string firstName
+        string lastName
+        int age
     }
+    HOUSE:::someclass
+
+    classDef someclass fill:#f96
+```
+
+### Example (Classes with Relationships)
+
+Apply classes when declaring relationships:
+
+```mermaid
+erDiagram
+    CAR {
+        string registrationNumber
+        string make
+        string model
+    }
+    PERSON {
+        string firstName
+        string lastName
+        int age
+    }
+    PERSON:::foo ||--|| CAR : owns
+    PERSON o{--|| HOUSE:::bar : has
+
+    classDef foo stroke:#f00
+    classDef bar stroke:#0f0
+    classDef foobar stroke:#00f
+```
+
+### Example (Default class)
+
+A class named `default` is assigned to all nodes without specific class definitions:
+
+```mermaid
+erDiagram
+    CAR {
+        string registrationNumber
+        string make
+        string model
+    }
+    PERSON {
+        string firstName
+        string lastName
+        int age
+    }
+    PERSON:::foo ||--|| CAR : owns
+    PERSON o{--|| HOUSE:::bar : has
+
+    classDef default fill:#f9f,stroke-width:4px
+    classDef foo stroke:#f00
+    classDef bar stroke:#0f0
+    classDef foobar stroke:#00f
+```
+
+### Example (ELK Layout)
+
+Use ELK layout for larger or more-complex diagrams (requires Mermaid v9.4+):
+
+```mermaid
+---
+title: Order example
+config:
+    layout: elk
+---
+erDiagram
+    CUSTOMER ||--o{ ORDER : places
+    ORDER ||--|{ LINE-ITEM : contains
+    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
+```
+
+### 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,445 @@
 ## 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[Start] --> B{Decision?}
-    B -->|Yes| C[Process A]
-    B -->|No| D[Process B]
-    C --> E[End]
-    D --> E
+    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[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+)
+
+**Note**: New shapes require Mermaid v11.3.0+. If your environment doesn't support new shapes, use traditional shapes instead.
+
+```mermaid
+flowchart RL
+    A@{ shape: manual-file, label: "File Handling"}
+    B@{ shape: manual-input, label: "User Input"}
+    C@{ shape: docs, label: "Multiple Documents"}
+    D@{ shape: procs, label: "Process Automation"}
+    E@{ shape: paper-tape, label: "Paper Records"}
+```
+
+### Example (With Edge IDs and Curve Styles - v11.10.0+)
+
+**Note**: Edge ID syntax requires Mermaid v11.10.0+. If your environment doesn't support edge IDs, use linkStyle instead (shown in alternative below).
+
+```mermaid
+flowchart LR
+    A e1@==> B
+    A e2@--> C
+    e1@{ curve: linear }
+    e2@{ curve: natural }
+```
+
+**Alternative (Using linkStyle - Compatible with all versions):**
+
+```mermaid
+flowchart LR
+    A[Start]
+    B[Process]
+    C[End]
+    A -->|Step 1| B
+    B -->|Step 2| C
+
+    linkStyle 0 stroke:#333,stroke-width:2px
+    linkStyle 1 stroke:#333,stroke-width:2px
+```
+
+### Example (With Unicode Text)
+
+Use quotes to enclose unicode text in nodes:
+
+```mermaid
+flowchart LR
+    id["This ❤ Unicode"]
+```
+
+### Example (With Markdown Formatting)
+
+Use double quotes and backticks to enclose markdown text:
+
+```mermaid
+---
+config:
+  flowchart:
+    htmlLabels: false
+---
+flowchart LR
+    markdown["`This **is** _Markdown_`"]
+    newLines["`Line1
+    Line 2
+    Line 3`"]
+    markdown --> newLines
+```
+
+### Example (With Invisible Links)
+
+Use `~~~` to create invisible links for positioning:
+
+```mermaid
+flowchart LR
+    A ~~~ B
+    B --> C
+```
+
+### Example (With Multi-directional Arrows)
+
+Use circle and cross edge types for multi-directional arrows:
+
+```mermaid
+flowchart LR
+    A o--o B
+    B <--> C
+    C x--x D
+```
+
+### Example (With Circle and Cross Edges)
+
+Use `--o` for circle edge and `--x` for cross edge:
+
+```mermaid
+flowchart LR
+    A --o B
+    C --x D
+```
+
+### Example (With Minimum Link Length)
+
+Add extra dashes to make links span more ranks:
+
+```mermaid
+flowchart TD
+    A[Start] --> B{Is it?}
+    B -->|Yes| C[OK]
+    C --> D[Rethink]
+    D --> B
+    B ---->|No| E[End]
+```
+
+### Example (With Entity Codes)
+
+Use entity codes to escape special characters:
+
+```mermaid
+flowchart LR
+    A["A double quote:#quot;"] --> B["A dec char:#9829;"]
+```
+
+### Example (With Icon Shape - v11.3.0+)
+
+**Note**: Icon shapes require Mermaid v11.3.0+ and registered icon packs.
+
+```mermaid
+flowchart TD
+    A@{ icon: "fa:user", form: "square", label: "User Icon", pos: "t", h: 60 }
+```
+
+### Example (With Image Shape - v11.3.0+)
+
+**Note**: Image shapes require Mermaid v11.3.0+.
+
+```mermaid
+flowchart TD
+    A@{ img: "https://mermaid.js.org/favicon.svg", label: "My example image label", pos: "t", h: 60, constraint: "on" }
+```
+
+### Example (With Edge Animations - v11.10.0+)
+
+**Note**: Edge animations require Mermaid v11.10.0+.
+
+```mermaid
+flowchart LR
+    A e1@--> B
+    e1@{ animation: fast }
+```
+
+### Example (With Click Events and Link Targets)
+
+Bind click events to nodes with tooltips and link targets:
+
+```mermaid
+flowchart LR
+    A-->B
+    B-->C
+    C-->D
+    click A "https://www.github.com" _blank
+    click B "https://www.github.com" "Open this in a new tab" _blank
+    click C href "https://www.github.com" _blank
+```
+
+### Example (With Chaining Links)
+
+Declare multiple links in the same line:
+
+```mermaid
+flowchart LR
+    A -- text --> B -- text2 --> C
+```
+
+### Example (With Multiple Node Links)
+
+Declare multiple node links in the same line:
+
+```mermaid
+flowchart TB
+    A & B --> C & D
+```
+
+### Example (With CSS Classes)
+
+Apply predefined CSS classes to nodes:
+
+```mermaid
+flowchart LR
+    A-->B[AAA<span>BBB</span>]
+    B-->D
+    class A cssClass
+```
+
+### Example (With Default Class)
+
+Define a default class that applies to all nodes without specific class definitions:
+
+```mermaid
+flowchart LR
+    A --> B
+    B --> C
+    
+    classDef default fill:#f9f,stroke:#333,stroke-width:4px
 ```

skills/mermaid/examples/gantt.md

@@ -1,31 +1,299 @@
 ## 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
+    title A Gantt Diagram
+    dateFormat YYYY-MM-DD
+    section Section
+        A task          :a1, 2014-01-01, 30d
+        Another task    :after a1, 20d
+    section Another
+        Task in Another :2014-01-12, 12d
+        another task    :24d
+```
+
+### Example (With Task IDs and Dependencies)
+
+```mermaid
+gantt
+    dateFormat  YYYY-MM-DD
+    title       Adding GANTT diagram functionality to mermaid
+    excludes    weekends
+    %% (`excludes` accepts specific dates in YYYY-MM-DD format, days of the week ("sunday") or "weekends", but not the word "weekdays".)
+
+    section A section
+    Completed task            :done,    des1, 2014-01-06,2014-01-08
+    Active task               :active,  des2, 2014-01-09, 3d
+    Future task               :         des3, after des2, 5d
+    Future task2              :         des4, after des3, 5d
+
+    section Critical tasks
+    Completed task in the critical line :crit, done, 2014-01-06,24h
+    Implement parser and jison          :crit, done, after des1, 2d
+    Create tests for parser             :crit, active, 3d
+    Future task in critical line        :crit, 5d
+    Create tests for renderer           :2d
+    Add to mermaid                      :until isadded
+    Functionality added                 :milestone, isadded, 2014-01-25, 0d
+
+    section Documentation
+    Describe gantt syntax               :active, a1, after des1, 3d
+    Add gantt diagram to demo page      :after a1  , 20h
+    Add another diagram to demo page    :doc1, after a1  , 48h
+
+    section Last section
+    Describe gantt syntax               :after doc1, 3d
+    Add gantt diagram to demo page      :20h
+    Add another diagram to demo page    :48h
+```
+
+### Example (With Multiple Task Dependencies)
+
+```mermaid
+gantt
+    apple :a, 2017-07-20, 1w
+    banana :crit, b, 2017-07-23, 1d
+    cherry :active, c, after b a, 1d
+    kiwi   :d, 2017-07-20, until b c
+```
+
+### 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 A Gantt Diagram Excluding Fri - Sat weekends
+    dateFormat YYYY-MM-DD
+    excludes weekends
+    weekend friday
+    section Section
+        A task          :a1, 2024-01-01, 30d
+        Another task    :after a1, 20d
+```
+
+### Example (With Milestones)
+
+```mermaid
+gantt
+    dateFormat HH:mm
+    axisFormat %H:%M
+    Initial milestone : milestone, m1, 17:49, 2m
+    Task A : 10m
+    Task B : 5m
+    Final milestone : milestone, m2, 18:08, 4m
+```
+
+### Example (With Vertical Markers)
+
+**Note**: Vertical markers (`vert`) may not be supported in all Mermaid versions. If this example doesn't work, use milestones instead.
+
+```mermaid
+gantt
+    dateFormat HH:mm
+    axisFormat %H:%M
+    Initial milestone : milestone, m1, 17:30, 0m
+    Task A : 3m
+    Task B : 8m
+    Final milestone : milestone, m2, 17:58, 0m
+```
+
+### Example (With Tick Interval)
+
+**Note**: `tickInterval` requires Mermaid v10.3.0+. This example includes tasks to demonstrate the tick interval.
 
 ```mermaid
 gantt
     title Project Timeline
     dateFormat YYYY-MM-DD
+    tickInterval 1week
+    weekday monday
     section Phase 1
-    Design :done, des1, 2024-01-01, 2024-01-15
-    Development :active, dev1, 2024-01-16, 2024-02-15
-    section Phase 2
-    Testing :test1, after dev1, 10d
-    Deployment :milestone, deploy1, after test1, 1d
+    Design :des1, 2024-01-01, 2024-01-15
+    Development :dev1, after des1, 20d
+```
+
+### Example (With Comments)
+
+```mermaid
+gantt
+    title A Gantt Diagram
+    %% This is a comment
+    dateFormat YYYY-MM-DD
+    section Section
+        A task          :a1, 2014-01-01, 30d
+        Another task    :after a1, 20d
+    section Another
+        Task in Another :2014-01-12, 12d
+        another task    :24d
+```
+
+### Example (Compact Mode)
+
+```mermaid
+---
+displayMode: compact
+---
+gantt
+    title A Gantt Diagram
+    dateFormat  YYYY-MM-DD
+
+    section Section
+    A task           :a1, 2014-01-01, 30d
+    Another task     :a2, 2014-01-20, 25d
+    Another one      :a3, 2014-02-10, 20d
+```
+
+### Example (Bar Chart using Gantt)
+
+```mermaid
+gantt
+    title Git Issues - days since last update
+    dateFormat X
+    axisFormat %s
+    section Issue19062
+    71   : 0, 71
+    section Issue19401
+    36   : 0, 36
+    section Issue193
+    34   : 0, 34
+    section Issue7441
+    9    : 0, 9
+    section Issue1300
+    5    : 0, 5
+```
+
+### Example (Timeline with Comments, CSS, and Config in Frontmatter)
+
+A comprehensive example demonstrating frontmatter configuration, custom CSS styling, milestones, and vertical markers:
+
+```mermaid
+---
+# Frontmatter config, YAML comments
+title: Ignored if specified in chart
+displayMode: compact
+config:
+    themeCSS: |
+        #item36 { fill: CadetBlue }
+        rect[id^=workaround] {
+            height: calc(100% - 50px);
+            transform: translate(9px, 25px);
+            y: 0;
+            width: 1.5px;
+            stroke: none;
+            fill: red;
+        }
+        text[id^=workaround] {
+            fill: red;
+            y: 100%;
+            font-size: 15px;
+        }
+    gantt:
+        useWidth: 400
+        rightPadding: 0
+        topAxis: true
+        numberSectionStyles: 2
+---
+gantt
+    title Timeline - Gantt Sampler
+    dateFormat YYYY
+    axisFormat %y
+    tickInterval 1decade
+    section Issue19062
+    71   : item71, 1900, 1930
+    section Issue19401
+    36   : item36, 1913, 1935
+    section Issue1300
+    94   : item94, 1910, 1915
+    5    : item5, 1920, 1925
+    0    : milestone, item0, 1918, 1s
+    9    : vert, 1906, 1s
+    64   : workaround, 1923, 1s
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If Gantt charts are not supported, use this flowchart alternative:
+
+```mermaid
+flowchart TD
+    Start([Project Start]) --> PlanningPhase[Planning Phase]
+    PlanningPhase --> DesignPhase[Design Phase]
+    DesignPhase --> DevelopmentPhase[Development Phase]
+    DevelopmentPhase --> TestingPhase[Testing Phase]
+    TestingPhase --> Deployment([Deployment])
+    
+    subgraph Planning["Planning"]
+        Req[Requirements<br/>Gathering]
+        Sys[System Design]
+        Req --> Sys
+    end
+    
+    subgraph Development["Development"]
+        Front[Frontend<br/>Development]
+        Back[Backend<br/>Development]
+        DB[Database<br/>Setup]
+    end
+    
+    subgraph Testing["Testing"]
+        Unit[Unit Testing]
+        Integration[Integration<br/>Testing]
+        Unit --> Integration
+    end
+    
+    PlanningPhase --> Req
+    DesignPhase --> Front
+    DesignPhase --> Back
+    DesignPhase --> DB
+    Front --> Unit
+    Back --> Unit
+    DB --> Unit
+    Integration --> Deployment
+    
+    style Start fill:#e1f5,stroke:#333
+    style Deployment fill:#e1f5,stroke:#333
+    style PlanningPhase fill:#bbf,stroke:#333
+    style DevelopmentPhase fill:#bbf,stroke:#333
+    style TestingPhase fill:#bbf,stroke:#333
 ```

skills/mermaid/examples/gitgraph.md

@@ -1,27 +1,601 @@
 ## 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 id: "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`, `showBranches`, `showCommitLabel`, `rotateCommitLabel`
 
-### Example
+Reference: [Mermaid GitGraph Documentation](https://mermaid.js.org/syntax/gitgraph.html)
+
+### Example (Basic GitGraph)
+
+A simple gitgraph showing three commits on the default (`main`) branch:
+
+```mermaid
+gitGraph
+    commit
+    commit
+    commit
+```
+
+### Example (Adding custom commit id)
+
+For a given commit you may specify a custom ID at the time of declaring it using the `id` attribute, followed by `:` and your custom value within `""` quotes. For example: `commit id: "your_custom_id"`
+
+```mermaid
+gitGraph
+    commit id: "Alpha"
+    commit id: "Beta"
+    commit id: "Gamma"
+```
+
+In this example, we have given our custom IDs to the commits.
+
+### Example (Modifying commit type)
+
+In Mermaid, a commit can be of three type, which render a bit different in the diagram. These types are:
+
+- `NORMAL`: Default commit type. Represented by a solid circle in the diagram
+- `REVERSE`: To emphasize a commit as a reverse commit. Represented by a crossed solid circle in the diagram.
+- `HIGHLIGHT`: To highlight a particular commit in the diagram. Represented by a filled rectangle in the diagram.
+
+For a given commit you may specify its type at the time of declaring it using the `type` attribute, followed by `:` and the required type option discussed above. For example: `commit type: HIGHLIGHT`
+
+**NOTE**: If no commit type is specified, `NORMAL` is picked as default.
+
+```mermaid
+gitGraph
+    commit id: "Normal"
+    commit
+    commit id: "Reverse" type: REVERSE
+    commit
+    commit id: "Highlight" type: HIGHLIGHT
+    commit
+```
+
+In this example, we have specified different types to each commit. Also, see how we have included both `id` and `type` together at the time of declaring our commits.
+
+### Example (Adding Tags)
+
+For a given commit you may decorate it as a **tag**, similar to the concept of tags or release version in git world. You can attach a custom tag at the time of declaring a commit using the `tag` attribute, followed by `:` and your custom value within `""` quotes. For example: `commit tag: "your_custom_tag"`
+
+```mermaid
+gitGraph
+    commit
+    commit id: "Normal" tag: "v1.0.0"
+    commit
+    commit id: "Reverse" type: REVERSE tag: "RC_1"
+    commit
+    commit id: "Highlight" type: HIGHLIGHT tag: "8.8.4"
+    commit
+```
+
+In this example, we have given custom tags to the commits. Also, see how we have combined all these attributes in a single commit declaration. You can mix-match these attributes as you like.
+
+### Example (Create a new branch)
+
+In Mermaid, in-order to create a new branch, you make use of the `branch` keyword. You also need to provide a name of the new branch. The name has to be unique and cannot be that of an existing branch. A branch name that could be confused for a keyword must be quoted within `""`. Usage examples: `branch develop`, `branch "cherry-pick"`
+
+When Mermaid, reads the `branch` keyword, it creates a new branch and sets it as the current branch. Equivalent to you creating a new branch and checking it out in Git world.
+
+```mermaid
+gitGraph
+    commit
+    commit
+    branch develop
+    commit
+    commit
+    commit
+```
+
+In this example, see how we started with default `main` branch, and pushed two commits on that. Then we created the `develop` branch, and all commits afterwards are put on the `develop` branch as it became the current branch.
+
+### Example (Checking out an existing branch)
+
+In Mermaid, in order to switch to an existing branch, you make use of the `checkout` keyword. You also need to provide a name of an existing branch. If no branch is found with the given name, it will result in console error. Usage example: `checkout develop`
+
+When Mermaid, reads the `checkout` keyword, it finds the given branch and sets it as the current branch. Equivalent to checking out a branch in the Git world.
+
+**NOTE**: `checkout` and `switch` can be used interchangeably.
+
+```mermaid
+gitGraph
+    commit
+    commit
+    branch develop
+    commit
+    commit
+    commit
+    checkout main
+    commit
+    commit
+```
+
+In this example, see how we started with default `main` branch, and pushed two commits on that. Then we created the `develop` branch, and all three commits afterwards are put on the `develop` branch as it became the current branch. After this we made use of the `checkout` keyword to set the current branch as `main`, and all commit that follow are registered against the current branch, i.e. `main`.
+
+### Example (Merging two branches)
+
+In Mermaid, in order to merge or join to an existing branch, you make use of the `merge` keyword. You also need to provide the name of an existing branch to merge from. If no branch is found with the given name, it will result in console error. Also, you can only merge two separate branches, and cannot merge a branch with itself. In such case an error is throw.
+
+Usage example: `merge develop`
+
+When Mermaid, reads the `merge` keyword, it finds the given branch and its head commit (the last commit on that branch), and joins it with the head commit on the **current branch**. Each merge results in a **merge commit**, represented in the diagram with **filled double circle**.
+
+```mermaid
+gitGraph
+    commit
+    commit
+    branch develop
+    commit
+    commit
+    commit
+    checkout main
+    commit
+    commit
+    merge develop
+    commit
+    commit
+```
+
+In this example, see how we started with default `main` branch, and pushed two commits on that. Then we created the `develop` branch, and all three commits afterwards are put on the `develop` branch as it became the current branch. After this we made use of the `checkout` keyword to set the current branch as `main`, and all commits that follow are registered against the current branch, i.e. `main`. After this we merge the `develop` branch onto the current branch `main`, resulting in a merge commit. Since the current branch at this point is still `main`, the last two commits are registered against that.
+
+You can also decorate your merge with similar attributes as you did for the commit using:
+
+- `id` --> To override the default ID with custom ID
+- `tag` --> To add a custom tag to your merge commit
+- `type` --> To override the default shape of merge commit. Here you can use other commit type mentioned earlier.
+
+And you can choose to use none, some or all of these attributes together. For example: `merge develop id: "my_custom_id" tag: "my_custom_tag" type: REVERSE`
+
+```mermaid
+gitGraph
+    commit id: "1"
+    commit id: "2"
+    branch nice_feature
+    checkout nice_feature
+    commit id: "3"
+    checkout main
+    commit id: "4"
+    checkout nice_feature
+    branch very_nice_feature
+    checkout very_nice_feature
+    commit id: "5"
+    checkout main
+    commit id: "6"
+    checkout nice_feature
+    commit id: "7"
+    checkout main
+    merge nice_feature id: "customID" tag: "customTag" type: REVERSE
+    checkout very_nice_feature
+    commit id: "8"
+    checkout main
+    commit id: "9"
+```
+
+### Example (Cherry Pick commit from another branch)
+
+Similar to how 'git' allows you to cherry-pick a commit from **another branch** onto the **current** branch, Mermaid also supports this functionality. You can also cherry-pick a commit from another branch using the `cherry-pick` keyword.
+
+To use the `cherry-pick` keyword, you must specify the id using the `id` attribute, followed by `:` and your desired commit id within a `""` quote. For example: `cherry-pick id: "your_custom_id"`
+
+Here, a new commit representing the cherry-pick is created on the current branch, and is visually highlighted in the diagram with a **cherry** and a tag depicting the commit id from which it is cherry-picked from.
+
+A few important rules to note here are:
+
+- You need to provide the `id` for an existing commit to be cherry-picked. If given commit id does not exist it will result in an error. For this, make use of the `commit id:$value` format of declaring commits. See the examples from above.
+- The given commit must not exist on the current branch. The cherry-picked commit must always be a different branch than the current branch.
+- Current branch must have at least one commit, before you can cherry-pick, otherwise it will cause an error is throw.
+- When cherry-picking a merge commit, providing a parent commit ID is mandatory. If the parent attribute is omitted or an invalid parent commit ID is provided, an error will be thrown.
+- The specified parent commit must be an immediate parent of the merge commit being cherry-picked.
 
 ```mermaid
 gitGraph
-    commit id: "Initial commit"
+    commit id: "ZERO"
     branch develop
+    branch release
+    commit id:"A"
+    checkout main
+    commit id:"ONE"
+    checkout develop
+    commit id:"B"
+    checkout main
+    merge develop id:"MERGE"
+    commit id:"TWO"
+    checkout release
+    cherry-pick id:"MERGE" parent:"B"
+    commit id:"THREE"
     checkout develop
-    commit id: "Add feature A"
-    commit id: "Add feature B"
+    commit id:"C"
+```
+
+### Example (Left to Right - default, LR:)
+
+In Mermaid, the default orientation is for commits to run from left to right and for branches to be stacked on top of one another.
+
+However, you can set this explicitly with `LR:` after `gitGraph`.
+
+```mermaid
+gitGraph LR:
+    commit
+    commit
+    branch develop
+    commit
+    commit
+    checkout main
+    commit
+    commit
+    merge develop
+    commit
+    commit
+```
+
+### Example (Top to Bottom - TB:)
+
+In `TB` (**Top-to-Bottom**) orientation, the commits run from top to bottom of the graph and branches are arranged side-by-side.
+
+To orient the graph this way, you need to add `TB:` after gitGraph.
+
+```mermaid
+gitGraph TB:
+    commit
+    commit
+    branch develop
+    commit
+    commit
+    checkout main
+    commit
+    commit
+    merge develop
+    commit
+    commit
+```
+
+### Example (Bottom to Top - BT:) (v11.0.0+)
+
+In `BT` (**Bottom-to-Top**) orientation, the commits run from bottom to top of the graph and branches are arranged side-by-side.
+
+To orient the graph this way, you need to add `BT:` after gitGraph.
+
+```mermaid
+gitGraph BT:
+    commit
+    commit
+    branch develop
+    commit
+    commit
     checkout main
-    commit id: "Update README"
+    commit
+    commit
     merge develop
-    commit id: "Release v1.0"
+    commit
+    commit
+```
+
+### Example (Hiding Branch names and lines)
+
+Sometimes you may want to hide the branch names and lines from the diagram. You can do this by using the `showBranches` keyword. By default its value is `true`. You can set it to `false` using directives.
+
+```mermaid
+---
+config:
+  logLevel: 'debug'
+  theme: 'base'
+  gitGraph:
+    showBranches: false
+---
+gitGraph
+    commit
+    branch hotfix
+    checkout hotfix
+    commit
+    branch develop
+    checkout develop
+    commit id:"ash" tag:"abc"
+    branch featureB
+    checkout featureB
+    commit type:HIGHLIGHT
+    checkout main
+    checkout hotfix
+    commit type:NORMAL
+    checkout develop
+    commit type:REVERSE
+    checkout featureB
+    commit
+    checkout main
+    merge hotfix
+    checkout featureB
+    commit
+    checkout develop
+    branch featureA
+    commit
+    checkout develop
+    merge hotfix
+    checkout featureA
+    commit
+    checkout featureB
+    commit
+    checkout develop
+    merge featureA
+    branch release
+    checkout release
+    commit
+    checkout main
+    commit
+    checkout release
+    merge main
+    checkout develop
+    merge release
+```
+
+### Example (Commit labels Layout: Rotated or Horizontal)
+
+Mermaid supports two types of commit labels layout. The default layout is **rotated**, which means the labels are placed below the commit circle, rotated at 45 degrees for better readability. This is particularly useful for commits with long labels.
+
+The other option is **horizontal**, which means the labels are placed below the commit circle centred horizontally, and are not rotated. This is particularly useful for commits with short labels.
+
+You can change the layout of the commit labels by using the `rotateCommitLabel` keyword in the directive. It defaults to `true`, which means the commit labels are rotated.
+
+**Usage example: Rotated commit labels**
+
+```mermaid
+---
+config:
+  logLevel: 'debug'
+  theme: 'base'
+  gitGraph:
+    rotateCommitLabel: true
+---
+gitGraph
+  commit id: "feat(api): ..."
+  commit id: "a"
+  commit id: "b"
+  commit id: "fix(client): .extra long label.."
+  branch c2
+  commit id: "feat(modules): ..."
+  commit id: "test(client): ..."
+  checkout main
+  commit id: "fix(api): ..."
+  commit id: "ci: ..."
+  branch b1
+  commit
+  branch b2
+  commit
+```
+
+**Usage example: Horizontal commit labels**
+
+```mermaid
+---
+config:
+  logLevel: 'debug'
+  theme: 'base'
+  gitGraph:
+    rotateCommitLabel: false
+---
+gitGraph
+  commit id: "feat(api): ..."
+  commit id: "a"
+  commit id: "b"
+  commit id: "fix(client): .extra long label.."
+  branch c2
+  commit id: "feat(modules): ..."
+  commit id: "test(client): ..."
+  checkout main
+  commit id: "fix(api): ..."
+  commit id: "ci: ..."
+  branch b1
+  commit
+  branch b2
+  commit
+```
+
+### Example (Hiding commit labels)
+
+Sometimes you may want to hide the commit labels from the diagram. You can do this by using the `showCommitLabel` keyword. By default its value is `true`. You can set it to `false` using directives.
+
+```mermaid
+---
+config:
+  logLevel: 'debug'
+  theme: 'base'
+  gitGraph:
+    showBranches: false
+    showCommitLabel: false
+---
+gitGraph
+    commit
+    branch hotfix
+    checkout hotfix
+    commit
+    branch develop
+    checkout develop
+    commit id:"ash"
+    branch featureB
+    checkout featureB
+    commit type:HIGHLIGHT
+    checkout main
+    checkout hotfix
+    commit type:NORMAL
+    checkout develop
+    commit type:REVERSE
+    checkout featureB
+    commit
+    checkout main
+    merge hotfix
+    checkout featureB
+    commit
+    checkout develop
+    branch featureA
+    commit
+    checkout develop
+    merge hotfix
+    checkout featureA
+    commit
+    checkout featureB
+    commit
+    checkout develop
+    merge featureA
+    branch release
+    checkout release
+    commit
+    checkout main
+    commit
+    checkout release
+    merge main
+    checkout develop
+    merge release
+```
+
+### Example (Customizing main branch name)
+
+Sometimes you may want to customize the name of the main/default branch. You can do this by using the `mainBranchName` keyword. By default its value is `main`. You can set it to any string using directives.
+
+```mermaid
+---
+config:
+  logLevel: 'debug'
+  theme: 'base'
+  gitGraph:
+    showBranches: true
+    showCommitLabel: true
+    mainBranchName: 'MetroLine1'
+---
+gitGraph
+    commit id:"NewYork"
+    commit id:"Dallas"
+    branch MetroLine2
+    commit id:"LosAngeles"
+    commit id:"Chicago"
+    commit id:"Houston"
+    branch MetroLine3
+    commit id:"Phoenix"
+    commit type: HIGHLIGHT id:"Denver"
+    commit id:"Boston"
+    checkout MetroLine1
+    commit id:"Atlanta"
+    merge MetroLine3
+    commit id:"Miami"
+    commit id:"Washington"
+    merge MetroLine2 tag:"MY JUNCTION"
+    commit id:"Boston"
+    commit id:"Detroit"
+    commit type:REVERSE id:"SanFrancisco"
+```
+
+Look at the imaginary railroad map created using Mermaid. Here, we have changed the default main branch name to `MetroLine1`.
+
+### Example (Customizing branch ordering)
+
+In Mermaid, by default the branches are shown in the order of their definition or appearance in the diagram code.
+
+Sometimes you may want to customize the order of the branches. You can do this by using the `order` keyword next the branch definition. You can set it to a positive number.
+
+Mermaid follows the given precedence order of the `order` keyword.
+
+- Main branch is always shown first as it has default order value of `0`. (unless its order is modified and changed from `0` using the `mainBranchOrder` keyword in the config)
+- Next, All branches without an `order` are shown in the order of their appearance in the diagram code.
+- Next, All branches with an `order` are shown in the order of their `order` value.
+
+To fully control the order of all the branches, you must define `order` for all the branches.
+
+```mermaid
+---
+config:
+  logLevel: 'debug'
+  theme: 'base'
+  gitGraph:
+    showBranches: true
+    showCommitLabel: true
+---
+gitGraph
+    commit
+    branch test1 order: 3
+    branch test2 order: 2
+    branch test3 order: 1
+```
+
+Look at the diagram, all the branches are following the order defined.
+
+```mermaid
+---
+config:
+  logLevel: 'debug'
+  theme: 'base'
+  gitGraph:
+    showBranches: true
+    showCommitLabel: true
+    mainBranchOrder: 2
+---
+gitGraph
+    commit
+    branch test1 order: 3
+    branch test2
+    branch test3
+    branch test4 order: 1
+```
+
+Look at the diagram, here, all the branches without a specified order are drawn in their order of definition. Then, `test4` branch is drawn because the order of `1`. Then, `main` branch is drawn because the order of `2`. And, lastly `test1` is drawn because the order of `3`.
+
+**NOTE**: Because we have overridden the `mainBranchOrder` to `2`, the `main` branch is not drawn in the beginning, instead follows the ordering.
+
+### Example (Parallel commits) (v10.8.0+)
+
+Commits in Mermaid display temporal information in gitgraph by default. For example if two commits are one commit away from its parent, the commit that was made earlier is rendered closer to its parent. You can turn this off by enabling the `parallelCommits` flag.
+
+**Temporal Commits (default, parallelCommits: false)**
+
+```mermaid
+---
+config:
+  gitGraph:
+    parallelCommits: false
+---
+gitGraph:
+  commit
+  branch develop
+  commit
+  commit
+  checkout main
+  commit
+  commit
+```
+
+**Parallel commits (parallelCommits: true)**
+
+```mermaid
+---
+config:
+  gitGraph:
+    parallelCommits: true
+---
+gitGraph:
+  commit
+  branch develop
+  commit
+  commit
+  checkout main
+  commit
+  commit
+```
+
+### 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,31 +1,148 @@
 ## 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`
-- Steps: `Step Name: Score: Actor1, Actor2`
-- Score: 1-5 (satisfaction level)
-- Actors: Who performs the step
+- Title: `title Title Text` (optional)
+- Sections: `section Section Name` (groups steps into stages)
+- Steps: `Task name: <score>: <comma separated list of actors>`
+- 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.js.org/syntax/userJourney.html)
+
+### Example (Basic User Journey)
+
+A user journey split into sections, with tasks showing scores and actors:
+
+```mermaid
+journey
+    title My working day
+    section Go to work
+      Make tea: 5: Me
+      Go upstairs: 3: Me
+      Do work: 1: Me, Cat
+    section Go home
+      Go downstairs: 5: Me
+      Sit down: 5: Me
+```
+
+### Example (E-commerce Purchase)
+
+A complete e-commerce purchase journey with multiple sections:
 
 ```mermaid
 journey
-    title User Shopping Journey
-    section Browse
-      Visit Website: 5: User
-      Search Products: 4: User
-      View Product Details: 5: User
+    title Online Shopping Experience
+    section Discovery
+      Browse products: 4: Customer
+      Search for item: 3: Customer
+      View product details: 5: Customer
+    section Decision
+      Compare prices: 4: Customer
+      Read reviews: 5: Customer
+      Add to cart: 4: Customer
     section Purchase
-      Add to Cart: 4: User
-      Checkout: 3: User
-      Payment: 4: User, Payment System
-    section Delivery
-      Order Confirmation: 5: System
-      Shipping: 4: Logistics
-      Receive Product: 5: User
+      Checkout: 3: Customer
+      Enter payment info: 2: Customer
+      Confirm order: 4: Customer
+    section Fulfillment
+      Receive confirmation: 5: Customer
+      Track shipment: 4: Customer
+      Receive product: 5: Customer
+```
+
+### Example (Product Onboarding)
+
+A product onboarding journey for new users:
+
+```mermaid
+journey
+    title New User Onboarding
+    section Sign Up
+      Visit website: 4: User
+      Create account: 3: User
+      Verify email: 2: User
+    section First Steps
+      Complete profile: 3: User
+      Take tutorial: 4: User
+      Explore features: 5: User
+    section Engagement
+      Invite friends: 4: User
+      Use core feature: 5: User
+      Subscribe to plan: 4: User
+```
+
+### Example (Customer Support)
+
+A customer support journey showing different touchpoints:
+
+```mermaid
+journey
+    title Customer Support Experience
+    section Issue Discovery
+      Encounter problem: 1: Customer
+      Search help center: 3: Customer
+      Contact support: 2: Customer
+    section Resolution
+      Explain issue: 3: Customer, Support Agent
+      Receive solution: 4: Customer, Support Agent
+      Test solution: 4: Customer
+    section Follow-up
+      Confirm resolution: 5: Customer
+      Provide feedback: 4: Customer
+```
+
+### Example (App Installation)
+
+A mobile app installation and setup journey:
+
+```mermaid
+journey
+    title Mobile App Installation
+    section Discovery
+      See app in store: 4: User
+      Read app description: 4: User
+      Check reviews: 5: User
+    section Installation
+      Download app: 4: User
+      Install app: 3: User
+      Open app: 4: User
+    section Setup
+      Grant permissions: 2: User
+      Create account: 3: User
+      Complete setup: 4: User
+```
+
+### Example (Simple Journey)
+
+A simple journey without title, showing basic syntax:
+
+```mermaid
+journey
+    section Morning Routine
+      Wake up: 3: Person
+      Exercise: 4: Person
+      Have breakfast: 5: Person
+    section Work
+      Commute: 2: Person
+      Attend meetings: 3: Person
+      Complete tasks: 4: Person
+```
+
+### 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,99 @@ 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)
+- Configuration: `ticketBaseUrl` for linking tickets to external systems
 
-### Example
+Reference: [Mermaid Kanban Documentation](https://mermaid.js.org/syntax/kanban.html)
+
+### Example (Basic Kanban)
+
+A simple kanban board with columns and tasks:
+
+```mermaid
+kanban
+  column1[Column Title]
+    task1[Task Description]
+```
+
+### Example (With Metadata)
+
+Add metadata to tasks using `@{ ... }` syntax:
+
+```mermaid
+kanban
+todo[Todo]
+  id3[Update Database Function]@{ ticket: MC-2037, assigned: 'knsv', priority: 'High' }
+```
+
+### Example (With Configuration)
+
+Configure ticket base URL for linking tickets:
+
+```mermaid
+---
+config:
+  kanban:
+    ticketBaseUrl: 'https://yourproject.atlassian.net/browse/#TICKET#'
+---
+kanban
+  todo[Todo]
+    task1[Task 1]@{ ticket: MC-123 }
+```
+
+### Example (Full Example)
+
+A complete kanban board with multiple columns, tasks, and metadata:
 
 ```mermaid
+---
+config:
+  kanban:
+    ticketBaseUrl: 'https://mermaidchart.atlassian.net/browse/#TICKET#'
+---
 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
+    [Create Documentation]
+    docs[Create Blog about the new diagram]
+  [In progress]
+    id6[Create renderer so that it works in all cases. We also add some extra text here for testing purposes. And some more just for the extra flare.]
+  id9[Ready for deploy]
+    id8[Design grammar]@{ assigned: 'knsv' }
+  id10[Ready for test]
+    id4[Create parsing tests]@{ ticket: MC-2038, assigned: 'K.Sveidqvist', priority: 'High' }
+    id66[last item]@{ priority: 'Very Low', assigned: 'knsv' }
+  id11[Done]
+    id5[define getData]
+    id2[Title of diagram is more than 100 chars when user duplicates diagram with 100 char]@{ ticket: MC-2036, priority: 'Very High'}
+    id3[Update DB function]@{ ticket: MC-2037, assigned: knsv, priority: 'High' }
+  id12[Can't reproduce]
+    id3[Weird flickering in Firefox]
+```
+
+### 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,34 +1,210 @@
 ## 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
-
-### Example
-
-```mermaid
-mindmap
-    root((Mermaid))
-        Flowcharts
-            Basic Flowchart
-            Subgraph
-            Styling
-        Sequence Diagrams
-            Participants
-            Messages
-            Activations
-        Class Diagrams
-            Classes
-            Relationships
-            Interfaces
-        Other Diagrams
-            State Diagrams
-            ER Diagrams
-            Gantt Charts
+- 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
+- Configuration: `layout: tidy-tree` for alternative layout
+
+Reference: [Mermaid Mindmap Documentation](https://mermaid.js.org/syntax/mindmap.html)
+
+### Example (Basic Mindmap with Icons)
+
+A complete mindmap example with icons:
+
+```mermaid
+mindmap
+  root((mindmap))
+    Origins
+      Long history
+      ::icon(fa fa-book)
+      Popularisation
+        British popular psychology author Tony Buzan
+    Research
+      On effectiveness<br/>and features
+      On Automatic creation
+        Uses
+            Creative techniques
+            Strategic planning
+            Argument mapping
+    Tools
+      Pen and paper
+      Mermaid
+```
+
+### Example (Basic Syntax)
+
+A simple mindmap with hierarchical structure:
+
+```mermaid
+mindmap
+    Root
+        A
+            B
+            C
+```
+
+### Example (Square Shape)
+
+Use square shape for a node:
+
+```mermaid
+mindmap
+    id[I am a square]
+```
+
+### Example (Rounded Square Shape)
+
+Use rounded square shape for a node:
+
+```mermaid
+mindmap
+    id(I am a rounded square)
+```
+
+### Example (Circle Shape)
+
+Use circle shape for a node:
+
+```mermaid
+mindmap
+    id((I am a circle))
+```
+
+### Example (Bang Shape)
+
+Use bang shape for a node:
+
+```mermaid
+mindmap
+    id))I am a bang((
+```
+
+### Example (Cloud Shape)
+
+Use cloud shape for a node:
+
+```mermaid
+mindmap
+    id)I am a cloud(
+```
+
+### Example (Hexagon Shape)
+
+Use hexagon shape for a node:
+
+```mermaid
+mindmap
+    id{{I am a hexagon}}
+```
+
+### Example (Default Shape)
+
+Default shape (no delimiters):
+
+```mermaid
+mindmap
+    I am the default shape
+```
+
+### Example (With Icons)
+
+Add icons to nodes (requires icon fonts to be loaded):
+
+```mermaid
+mindmap
+    Root
+        A
+        ::icon(fa fa-book)
+        B(B)
+        ::icon(mdi mdi-skull-outline)
+```
+
+### Example (With CSS Classes)
+
+Apply CSS classes to style nodes:
+
+```mermaid
+mindmap
+    Root
+        A[A]
+        :::urgent large
+        B(B)
+        C
+```
+
+### Example (Unclear Indentation)
+
+Mermaid handles unclear indentation by finding the nearest parent:
+
+```mermaid
+mindmap
+    Root
+        A
+            B
+          C
+```
+
+### Example (Markdown Strings)
+
+Use markdown formatting in labels with automatic text wrapping:
+
+```mermaid
+mindmap
+    id1["`**Root** with
+a second line
+Unicode works too: 🤓`"]
+      id2["`The dog in **the** hog... a *very long text* that wraps to a new line`"]
+      id3[Regular labels still works]
+```
+
+### Example (With Configuration - Tidy Tree Layout)
+
+Configure alternative layout using tidy-tree:
+
+```mermaid
+---
+config:
+  layout: tidy-tree
+---
+mindmap
+root((mindmap is a long thing))
+  A
+  B
+  C
+  D
+```
+
+### 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,75 @@
 ## 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"` or `--- 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.js.org/syntax/packet.html)
+
+### Example (TCP Packet with Configuration)
+
+A complete TCP packet example using configuration block and traditional bit range syntax:
+
+```mermaid
+---
+title: "TCP Packet"
+---
+packet
+0-15: "Source Port"
+16-31: "Destination Port"
+32-63: "Sequence Number"
+64-95: "Acknowledgment Number"
+96-99: "Data Offset"
+100-105: "Reserved"
+106: "URG"
+107: "ACK"
+108: "PSH"
+109: "RST"
+110: "SYN"
+111: "FIN"
+112-127: "Window"
+128-143: "Checksum"
+144-159: "Urgent Pointer"
+160-191: "(Options and Padding)"
+192-255: "Data (variable length)"
+```
+
+### Example (UDP Packet with Bit Count Syntax)
+
+A UDP packet example using bit count syntax (v11.7.0+):
+
+```mermaid
+packet
+title UDP Packet
++16: "Source Port"
++16: "Destination Port"
+32-47: "Length"
+48-63: "Checksum"
+64-95: "Data (variable length)"
+```
+
+### 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,20 +1,74 @@
 ## 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
+- Configuration: `textPosition` (0.0 to 1.0, default: 0.75) - axial position of pie slice labels
 
-### Example
+Reference: [Mermaid Pie Chart Documentation](https://mermaid.js.org/syntax/pie.html)
+
+### Example (Basic Pie Chart)
+
+A simple pie chart with title and data:
+
+```mermaid
+pie title Pets adopted by volunteers
+    "Dogs" : 386
+    "Cats" : 85
+    "Rats" : 15
+```
+
+### Example (With showData)
+
+Use `showData` to render the actual data values after the legend text:
+
+```mermaid
+pie showData
+    title Key elements in Product X
+    "Calcium" : 42.96
+    "Potassium" : 50.05
+    "Magnesium" : 10.01
+    "Iron" : 5
+```
+
+### Example (With Configuration)
+
+Configure text position and theme variables:
+
+```mermaid
+---
+config:
+  pie:
+    textPosition: 0.5
+  themeVariables:
+    pieOuterStrokeWidth: "5px"
+---
+pie showData
+    title Key elements in Product X
+    "Calcium" : 42.96
+    "Potassium" : 50.05
+    "Magnesium" : 10.01
+    "Iron" : 5
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If pie charts are not supported, use this flowchart alternative:
 
 ```mermaid
-pie title Sales by Product
-    "Product A" : 42.5
-    "Product B" : 30.2
-    "Product C" : 15.8
-    "Product D" : 11.5
+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,29 +1,109 @@
 ## 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`
+- Configuration: `chartWidth`, `chartHeight`, `titlePadding`, `titleFontSize`, etc.
+- Theme variables: `quadrant1Fill`, `quadrant1TextFill`, `quadrantPointFill`, etc.
 
-### Example
+Reference: [Mermaid Quadrant Chart Documentation](https://mermaid.js.org/syntax/quadrantChart.html)
+
+### Example (Basic Quadrant Chart)
+
+A complete quadrant chart example:
+
+```mermaid
+quadrantChart
+    title Reach and engagement of campaigns
+    x-axis Low Reach --> High Reach
+    y-axis Low Engagement --> High Engagement
+    quadrant-1 We should expand
+    quadrant-2 Need to promote
+    quadrant-3 Re-evaluate
+    quadrant-4 May be improved
+    Campaign A: [0.3, 0.6]
+    Campaign B: [0.45, 0.23]
+    Campaign C: [0.57, 0.69]
+    Campaign D: [0.78, 0.34]
+    Campaign E: [0.40, 0.34]
+    Campaign F: [0.35, 0.78]
+```
+
+### Example (With Configuration and Theme)
+
+Configure chart dimensions and theme variables:
 
 ```mermaid
+---
+config:
+  quadrantChart:
+    chartWidth: 400
+    chartHeight: 400
+  themeVariables:
+    quadrant1TextFill: "ff0000"
+---
 quadrantChart
-    title Product Prioritization
-    x-axis Low Effort --> High Effort
-    y-axis Low Impact --> High Impact
-    quadrant-1 Should Do
-    quadrant-2 Must Do
-    quadrant-3 Won't Do
-    quadrant-4 Nice to Have
-    Feature A: [0.3, 0.8]
-    Feature B: [0.7, 0.9]
-    Feature C: [0.2, 0.3]
-    Feature D: [0.8, 0.2]
+  x-axis Urgent --> Not Urgent
+  y-axis Not Important --> "Important ❤"
+  quadrant-1 Plan
+  quadrant-2 Do
+  quadrant-3 Delegate
+  quadrant-4 Delete
+```
+
+### Example (With Point Styling)
+
+Style points directly with radius, color, stroke-color, and stroke-width:
+
+```mermaid
+quadrantChart
+  title Reach and engagement of campaigns
+  x-axis Low Reach --> High Reach
+  y-axis Low Engagement --> High Engagement
+  quadrant-1 We should expand
+  quadrant-2 Need to promote
+  quadrant-3 Re-evaluate
+  quadrant-4 May be improved
+  Campaign A: [0.9, 0.0] radius: 12
+  Campaign B:::class1: [0.8, 0.1] color: #ff3300, radius: 10
+  Campaign C: [0.7, 0.2] radius: 25, color: #00ff33, stroke-color: #10f0f0
+  Campaign D: [0.6, 0.3] radius: 15, stroke-color: #00ff0f, stroke-width: 5px ,color: #ff33f0
+  Campaign E:::class2: [0.5, 0.4]
+  Campaign F:::class3: [0.4, 0.5] color: #0000ff
+  classDef class1 color: #109060
+  classDef class2 color: #908342, radius : 10, stroke-color: #310085, stroke-width: 10px
+  classDef class3 color: #f00fff, radius : 10
+```
+
+### 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,106 @@
 ## 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` or `--- title: "Title" ---` (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)
+- Configuration: `width`, `height`, `marginTop`, `marginBottom`, `marginLeft`, `marginRight`, `axisScaleFactor`, `axisLabelFactor`, `curveTension`
+- Theme variables: `cScale0`, `cScale1`, etc. for curve colors, `radar.axisColor`, `radar.curveOpacity`, etc.
 
-### Example
+Reference: [Mermaid Radar Diagram Documentation](https://mermaid.js.org/syntax/radar.html)
+
+### Example (Basic Radar Diagram with Configuration)
+
+A radar diagram with title configuration and multiple axes:
+
+```mermaid
+---
+title: "Grades"
+---
+radar-beta
+  axis m["Math"], s["Science"], e["English"]
+  axis h["History"], g["Geography"], a["Art"]
+  curve a["Alice"]{85, 90, 80, 70, 75, 90}
+  curve b["Bob"]{70, 75, 85, 80, 90, 85}
+
+  max 100
+  min 0
+```
+
+### Example (Restaurant Comparison with Polygon Graticule)
+
+A radar diagram with polygon graticule and multiple curves:
+
+```mermaid
+radar-beta
+  title Restaurant Comparison
+  axis food["Food Quality"], service["Service"], price["Price"]
+  axis ambiance["Ambiance"],
+
+  curve a["Restaurant A"]{4, 3, 2, 4}
+  curve b["Restaurant B"]{3, 4, 3, 3}
+  curve c["Restaurant C"]{2, 3, 4, 2}
+  curve d["Restaurant D"]{2, 2, 4, 3}
+
+  graticule polygon
+  max 5
+```
+
+### Example (With Configuration and Theme)
+
+Configure radar diagram dimensions, scale factors, and theme variables:
 
 ```mermaid
+---
+config:
+  radar:
+    axisScaleFactor: 0.25
+    curveTension: 0.1
+  theme: base
+  themeVariables:
+    cScale0: "#FF0000"
+    cScale1: "#00FF00"
+    cScale2: "#0000FF"
+    radar:
+      curveOpacity: 0
+---
 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 A, B, C, D, E
+  curve c1{1,2,3,4,5}
+  curve c2{5,4,3,2,1}
+  curve c3{3,3,3,3,3}
+```
+
+### 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,41 +1,240 @@
 ## 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.js.org/syntax/requirementDiagram.html)
+
+### Example (Basic Requirement Diagram)
+
+A simple requirement diagram with requirement and element:
+
+```mermaid
+requirementDiagram
+
+    requirement test_req {
+    id: 1
+    text: the test text.
+    risk: high
+    verifymethod: test
+    }
+
+    element test_entity {
+    type: simulation
+    }
+
+    test_entity - satisfies -> test_req
+```
+
+### Example (With Markdown Formatting)
+
+Use markdown formatting in requirement names and text:
+
+```mermaid
+requirementDiagram
+
+requirement "__test_req__" {
+    id: 1
+    text: "*italicized text* **bold text**"
+    risk: high
+    verifymethod: test
+}
+```
+
+### Example (Larger Example - All Features)
+
+A complete example using all requirement types and relationships:
+
+```mermaid
+requirementDiagram
+
+    requirement test_req {
+    id: 1
+    text: the test text.
+    risk: high
+    verifymethod: test
+    }
+
+    functionalRequirement test_req2 {
+    id: 1.1
+    text: the second test text.
+    risk: low
+    verifymethod: inspection
+    }
+
+    performanceRequirement test_req3 {
+    id: 1.2
+    text: the third test text.
+    risk: medium
+    verifymethod: demonstration
+    }
+
+    interfaceRequirement test_req4 {
+    id: 1.2.1
+    text: the fourth test text.
+    risk: medium
+    verifymethod: analysis
+    }
+
+    physicalRequirement test_req5 {
+    id: 1.2.2
+    text: the fifth test text.
+    risk: medium
+    verifymethod: analysis
+    }
+
+    designConstraint test_req6 {
+    id: 1.2.3
+    text: the sixth test text.
+    risk: medium
+    verifymethod: analysis
+    }
+
+    element test_entity {
+    type: simulation
+    }
+
+    element test_entity2 {
+    type: word doc
+    docRef: reqs/test_entity
+    }
+
+    element test_entity3 {
+    type: "test suite"
+    docRef: github.com/all_the_tests
+    }
+
+
+    test_entity - satisfies -> test_req2
+    test_req - traces -> test_req2
+    test_req - contains -> test_req3
+    test_req3 - contains -> test_req4
+    test_req4 - derives -> test_req5
+    test_req5 - refines -> test_req6
+    test_entity3 - verifies -> test_req5
+    test_req <- copies - test_entity2
+```
+
+### Example (With Direction)
+
+Change diagram direction using direction keyword:
+
+```mermaid
+requirementDiagram
+
+direction LR
+
+requirement test_req {
+    id: 1
+    text: the test text.
+    risk: high
+    verifymethod: test
+}
+
+element test_entity {
+    type: simulation
+}
+
+test_entity - satisfies -> test_req
+```
+
+### Example (With Direct Styling)
+
+Apply CSS styles directly to requirements and elements:
+
+```mermaid
+requirementDiagram
+
+requirement test_req {
+    id: 1
+    text: styling example
+    risk: low
+    verifymethod: test
+}
+
+element test_entity {
+    type: simulation
+}
+
+style test_req fill:#ffa,stroke:#000, color: green
+style test_entity fill:#f9f,stroke:#333, color: blue
+```
+
+### Example (With Class Definitions)
+
+Define reusable styles using classDef:
+
+```mermaid
+requirementDiagram
+
+requirement test_req {
+    id: 1
+    text: "class styling example"
+    risk: low
+    verifymethod: test
+}
+
+element test_entity {
+    type: simulation
+}
+
+classDef important fill:#f96,stroke:#333,stroke-width:4px
+classDef test fill:#ffa,stroke:#000
+```
+
+### Example (Combined Example - Class and Style)
+
+Combine class definitions with direct styling and shorthand syntax:
 
 ```mermaid
 requirementDiagram
-    requirement R1 {
-        id: 1
-        text: System must handle 1000 concurrent users
-        risk: high
-        verifymethod: test
-    }
-    requirement R2 {
-        id: 2
-        text: System must respond within 2 seconds
-        risk: medium
-        verifymethod: test
-    }
-    
-    element E1 {
-        type: System
-        docref: docs/system.md
-    }
-    
-    R1 satisfies E1
-    R2 satisfies E1
+
+requirement test_req:::important {
+    id: 1
+    text: "class styling example"
+    risk: low
+    verifymethod: test
+}
+
+element test_entity {
+    type: simulation
+}
+
+classDef important font-weight:bold
+
+class test_entity important
+style test_entity fill:#f9f,stroke:#333
+```
+
+### 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

@@ -1,22 +1,190 @@
 ## Instructions
 
-Sankey diagrams visualize flow and relationships between entities, showing the magnitude of flows between nodes.
+Sankey diagrams visualize flow and relationships between entities, showing the magnitude of flows between nodes. A sankey diagram is a visualization used to depict a flow from one set of values to another. The things being connected are called nodes and the connections are called links.
+
+**Note**: This is an experimental diagram. Its syntax are very close to plain CSV, but it is to be extended in the nearest future.
 
 ### 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
+- Configuration: `showValues`, `width`, `height`, `linkColor`, `nodeAlignment`
+
+Reference: [Mermaid Sankey Documentation](https://mermaid.js.org/syntax/sankey.html)
+
+### Example (Basic Sankey)
+
+A simple sankey diagram with CSV format:
+
+```mermaid
+sankey
+%% source,target,value
+Electricity grid,Over generation / exports,104.453
+Electricity grid,Heating and cooling - homes,113.726
+Electricity grid,H2 conversion,27.14
+```
+
+### Example (With Empty Lines)
+
+Empty lines are allowed for visual separation:
+
+```mermaid
+sankey
+Bio-conversion,Losses,26.862
+Bio-conversion,Solid,280.322
+Bio-conversion,Gas,81.144
+```
+
+### Example (With Commas in Node Names)
+
+Wrap node names containing commas in double quotes:
+
+```mermaid
+sankey
+Pumped heat,"Heating and cooling, homes",193.026
+Pumped heat,"Heating and cooling, commercial",70.672
+```
+
+### Example (With Double Quotes in Node Names)
 
-### Example
+Use two double quotes inside quoted strings:
 
 ```mermaid
-sankey-beta
-    Energy Production -->|100| Electricity
-    Energy Production -->|30| Heat
-    Electricity -->|80| Residential
-    Electricity -->|20| Industrial
-    Heat -->|25| Residential
-    Heat -->|5| Industrial
+sankey
+Pumped heat,"Heating and cooling, ""homes""",193.026
+Pumped heat,"Heating and cooling, ""commercial""",70.672
+```
+
+### Example (With Configuration)
+
+Configure sankey diagram with showValues, dimensions, linkColor, and nodeAlignment:
+
+```mermaid
+---
+config:
+  sankey:
+    showValues: false
+---
+sankey
+Agricultural 'waste',Bio-conversion,124.729
+Bio-conversion,Liquid,0.597
+Bio-conversion,Losses,26.862
+Bio-conversion,Solid,280.322
+Bio-conversion,Gas,81.144
+Electricity grid,Over generation / exports,104.453
+Electricity grid,Heating and cooling - homes,113.726
+Electricity grid,Industry,342.165
+```
+
+### Example (Full Energy Flow Diagram)
+
+Complete energy flow diagram with all data (example taken from observable):
+
+```mermaid
+---
+config:
+  sankey:
+    showValues: false
+---
+sankey
+Agricultural 'waste',Bio-conversion,124.729
+Bio-conversion,Liquid,0.597
+Bio-conversion,Losses,26.862
+Bio-conversion,Solid,280.322
+Bio-conversion,Gas,81.144
+Biofuel imports,Liquid,35
+Biomass imports,Solid,35
+Coal imports,Coal,11.606
+Coal reserves,Coal,63.965
+Coal,Solid,75.571
+District heating,Industry,10.639
+District heating,Heating and cooling - commercial,22.505
+District heating,Heating and cooling - homes,46.184
+Electricity grid,Over generation / exports,104.453
+Electricity grid,Heating and cooling - homes,113.726
+Electricity grid,H2 conversion,27.14
+Electricity grid,Industry,342.165
+Electricity grid,Road transport,37.797
+Electricity grid,Agriculture,4.412
+Electricity grid,Heating and cooling - commercial,40.858
+Electricity grid,Losses,56.691
+Electricity grid,Rail transport,7.863
+Electricity grid,Lighting & appliances - commercial,90.008
+Electricity grid,Lighting & appliances - homes,93.494
+Gas imports,Ngas,40.719
+Gas reserves,Ngas,82.233
+Gas,Heating and cooling - commercial,0.129
+Gas,Losses,1.401
+Gas,Thermal generation,151.891
+Gas,Agriculture,2.096
+Gas,Industry,48.58
+Geothermal,Electricity grid,7.013
+H2 conversion,H2,20.897
+H2 conversion,Losses,6.242
+H2,Road transport,20.897
+Hydro,Electricity grid,6.995
+Liquid,Industry,121.066
+Liquid,International shipping,128.69
+Liquid,Road transport,135.835
+Liquid,Domestic aviation,14.458
+Liquid,International aviation,206.267
+Liquid,Agriculture,3.64
+Liquid,National navigation,33.218
+Liquid,Rail transport,4.413
+Marine algae,Bio-conversion,4.375
+Ngas,Gas,122.952
+Nuclear,Thermal generation,839.978
+Oil imports,Oil,504.287
+Oil reserves,Oil,107.703
+Oil,Liquid,611.99
+Other waste,Solid,56.587
+Other waste,Bio-conversion,77.81
+Pumped heat,Heating and cooling - homes,193.026
+Pumped heat,Heating and cooling - commercial,70.672
+Solar PV,Electricity grid,59.901
+Solar Thermal,Heating and cooling - homes,19.263
+Solar,Solar Thermal,19.263
+Solar,Solar PV,59.901
+Solid,Agriculture,0.882
+Solid,Thermal generation,400.12
+Solid,Industry,46.477
+Thermal generation,Electricity grid,525.531
+Thermal generation,Losses,787.129
+Thermal generation,District heating,79.329
+Tidal,Electricity grid,9.452
+UK land based bioenergy,Bio-conversion,182.01
+Wave,Electricity grid,19.013
+Wind,Electricity grid,289.366
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If sankey diagrams are 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,33 +1,388 @@
 ## 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`
-
-### Example
-
-```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
+- 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: `autonumber` (optional)
+
+Reference: [Mermaid Sequence Diagram Documentation](https://mermaid.js.org/syntax/sequenceDiagram.html)
+
+### Example (Basic Sequence Diagram)
+
+A simple sequence diagram showing messages between participants:
+
+```mermaid
+sequenceDiagram
+    Alice->>John: Hello John, how are you?
+    John-->>Alice: Great!
+    Alice-)John: See you later!
+```
+
+### Example (Participants)
+
+Participants can be defined explicitly to control order of appearance:
+
+```mermaid
+sequenceDiagram
+    participant Alice
+    participant Bob
+    Bob->>Alice: Hi Alice
+    Alice->>Bob: Hi Bob
+```
+
+### Example (Actors)
+
+Use `actor` keyword to use actor symbol instead of rectangle:
+
+```mermaid
+sequenceDiagram
+    actor Alice
+    actor Bob
+    Alice->>Bob: Hi Bob
+    Bob->>Alice: Hi Alice
+```
+
+### Example (Participant Types)
+
+Use JSON configuration syntax to specify participant types (requires Mermaid v10.0.0+). Note: This feature may not be supported in all Mermaid versions. If you encounter errors, use standard `participant` or `actor` instead.
+
+```mermaid
+sequenceDiagram
+    participant Alice
+    participant Bob
+    Alice->>Bob: Request
+    Bob->>Alice: Response
+```
+
+For advanced participant types (boundary, control, entity, database, collections, queue), use JSON configuration syntax in supported versions:
+
+```mermaid
+sequenceDiagram
+    participant Alice@{ "type" : "boundary" }
+    participant Bob
+    Alice->>Bob: Request from boundary
+    Bob->>Alice: Response to boundary
+```
+
+### Example (Aliases)
+
+The actor can have a convenient identifier and a descriptive label:
+
+```mermaid
+sequenceDiagram
+    participant A as Alice
+    participant J as John
+    A->>J: Hello John, how are you?
+    J->>A: Great!
+```
+
+### Example (Actor Creation and Destruction)
+
+Create and destroy actors by messages (v10.3.0+):
+
+```mermaid
+sequenceDiagram
+    Alice->>Bob: Hello Bob, how are you ?
+    Bob->>Alice: Fine, thank you. And you?
+    create participant Carl
+    Alice->>Carl: Hi Carl!
+    create actor D as Donald
+    Carl->>D: Hi!
+    destroy Carl
+    Alice-xCarl: We are too many
+    destroy Bob
+    Bob->>Alice: I agree
+```
+
+### Example (Grouping / Box)
+
+Group actors in vertical boxes with color and label:
+
+```mermaid
+sequenceDiagram
+    box Purple Alice & John
+    participant A
+    participant J
+    end
+    box Another Group
+    participant B
+    participant C
+    end
+    A->>J: Hello John, how are you?
+    J->>A: Great!
+    A->>B: Hello Bob, how is Charley?
+    B->>C: Hello Charley, how are you?
+```
+
+### Example (Activations)
+
+Activate and deactivate an actor using dedicated declarations:
+
+```mermaid
+sequenceDiagram
+    Alice->>John: Hello John, how are you?
+    activate John
+    John-->>Alice: Great!
+    deactivate John
+```
+
+Or use shortcut notation with `+`/`-` suffix:
+
+```mermaid
+sequenceDiagram
+    Alice->>+John: Hello John, how are you?
+    John-->>-Alice: Great!
+```
+
+### Example (Stacked Activations)
+
+Activations can be stacked for same actor:
+
+```mermaid
+sequenceDiagram
+    Alice->>+John: Hello John, how are you?
+    Alice->>+John: John, can you hear me?
+    John-->>-Alice: Hi Alice, I can hear you!
+    John-->>-Alice: I feel great!
+```
+
+### Example (Notes)
+
+Add notes to a sequence diagram:
+
+```mermaid
+sequenceDiagram
+    participant John
+    Note right of John: Text in note
+```
+
+Or spanning two participants:
+
+```mermaid
+sequenceDiagram
+    Alice->John: Hello John, how are you?
+    Note over Alice,John: A typical interaction
+```
+
+### Example (Line breaks)
+
+Line break can be added to Note and Message:
+
+```mermaid
+sequenceDiagram
+    Alice->John: Hello John,<br/>how are you?
+    Note over Alice,John: A typical interaction<br/>But now in two lines
+```
+
+### Example (Loops)
+
+Express loops in a sequence diagram:
+
+```mermaid
+sequenceDiagram
+    Alice->John: Hello John, how are you?
+    loop Every minute
+        John-->Alice: Great!
+    end
+```
+
+### Example (Alt - Alternative Paths)
+
+Express alternative paths using `alt`:
+
+```mermaid
+sequenceDiagram
+    Alice->>Bob: Hello Bob, how are you?
+    alt is sick
+        Bob->>Alice: Not so good :(
+    else is well
+        Bob->>Alice: Feeling fresh like a daisy
+    end
+    opt Extra response
+        Bob->>Alice: Thanks for asking
+    end
+```
+
+### Example (Parallel)
+
+Show actions happening in parallel:
+
+```mermaid
+sequenceDiagram
+    par Alice to Bob
+        Alice->>Bob: Hello guys!
+    and Alice to John
+        Alice->>John: Hello guys!
+    end
+    Bob-->>Alice: Hi Alice!
+    John-->>Alice: Hi Alice!
+```
+
+### Example (Nested Parallel)
+
+Parallel blocks can be nested:
+
+```mermaid
+sequenceDiagram
+    par Alice to Bob
+        Alice->>Bob: Go help John
+    and Alice to John
+        Alice->>John: I want this done today
+        par John to Charlie
+            John->>Charlie: Can we do this today?
+        and John to Diana
+            John->>Diana: Can you help us today?
+        end
+    end
+```
+
+### Example (Critical Region)
+
+Show actions that must happen automatically with conditional handling:
+
+```mermaid
+sequenceDiagram
+    critical Establish a connection to the DB
+        Service-->DB: connect
+    option Network timeout
+        Service-->Service: Log error
+    option Credentials rejected
+        Service-->Service: Log different error
+    end
+```
+
+### Example (Break)
+
+Indicate a stop of the sequence within the flow:
+
+```mermaid
+sequenceDiagram
+    Consumer-->API: Book something
+    API-->BookingService: Start booking process
+    break when the booking process fails
+        API-->Consumer: show failure
+    end
+    API-->BillingService: Start billing process
+```
+
+### Example (Background Highlighting)
+
+Highlight flows by providing colored background rects:
+
+```mermaid
+sequenceDiagram
+    participant Alice
+    participant John
+
+    rect rgb(191, 223, 255)
+    note right of Alice: Alice calls John.
+    Alice->>+John: Hello John, how are you?
+    rect rgb(200, 150, 255)
+    Alice->>+John: John, can you hear me?
+    John-->>-Alice: Hi Alice, I can hear you!
+    end
+    John-->>-Alice: I feel great!
+    end
+    Alice ->>+ John: Did you want to go to the game tonight?
+    John -->>- Alice: Yeah! See you there.
+```
+
+### Example (Comments)
+
+Comments need to be on their own line, prefaced with `%%`:
+
+```mermaid
+sequenceDiagram
+    Alice->>John: Hello John, how are you?
+    %% this is a comment
+    John-->>Alice: Great!
+```
+
+### Example (Entity codes)
+
+Escape characters using entity codes:
+
+```mermaid
+sequenceDiagram
+    A->>B: I #9829; you!
+    B->>A: I #9829; you #infin; times more!
+```
+
+### Example (Sequence Numbers)
+
+Get a sequence number attached to each arrow using `autonumber`:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    Alice->>John: Hello John, how are you?
+    loop HealthCheck
+        John->>John: Fight against hypochondria
+    end
+    Note right of John: Rational thoughts!
+    John-->>Alice: Great!
+    John->>Bob: How about you?
+    Bob-->>John: Jolly good!
+```
+
+### Example (Actor Menus)
+
+Actors can have popup-menus containing individualized links:
+
+```mermaid
+sequenceDiagram
+    participant Alice
+    participant John
+    link Alice: Dashboard @ https://dashboard.contoso.com/alice
+    link Alice: Wiki @ https://wiki.contoso.com/alice
+    link John: Dashboard @ https://dashboard.contoso.com/john
+    link John: Wiki @ https://wiki.contoso.com/john
+    Alice->>John: Hello John, how are you?
+    John-->>Alice: Great!
+    Alice-)John: See you later!
+```
+
+### 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,331 @@
 ## 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. In state diagrams systems are described in terms of **states** and how one **state** can change to another **state** via a **transition**.
 
 ### 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.js.org/syntax/stateDiagram.html)
+
+### Example (Basic State Diagram)
+
+A simple state diagram showing states and transitions:
+
+```mermaid
+---
+title: Simple sample
+---
+stateDiagram-v2
+    [*] --> Still
+    Still --> [*]
+
+    Still --> Moving
+    Moving --> Still
+    Moving --> Crash
+    Crash --> [*]
+```
+
+### Example (Define a state)
+
+A state can be declared in multiple ways. The simplest way is to define a state with just an id:
+
+```mermaid
+stateDiagram-v2
+    stateId
+```
+
+Another way is by using the state keyword with a description:
+
+```mermaid
+stateDiagram-v2
+    state "This is a state description" as s2
+```
+
+Or define the state id followed by a colon and the description:
+
+```mermaid
+stateDiagram-v2
+    s2 : This is a state description
+```
+
+### Example (Transitions)
+
+Transitions are path/edges when one state passes into another. Add text to describe the transition:
+
+```mermaid
+stateDiagram-v2
+    s1 --> s2: A transition
+```
+
+### Example (Start and End)
+
+Special states indicating the start and stop of the diagram using `[*]`:
+
+```mermaid
+stateDiagram-v2
+    [*] --> s1
+    s1 --> [*]
+```
+
+### Example (Composite states)
+
+Define composite states using the `state` keyword followed by an id and the body between `{}`:
+
+```mermaid
+stateDiagram-v2
+    [*] --> First
+    state First {
+        [*] --> second
+        second --> [*]
+    }
+
+    [*] --> NamedComposite
+    NamedComposite: Another Composite
+    state NamedComposite {
+        [*] --> namedSimple
+        namedSimple --> [*]
+        namedSimple: Another simple
+    }
+```
+
+### Example (Nested Composite states)
+
+You can do this in several layers:
+
+```mermaid
+stateDiagram-v2
+    [*] --> First
+
+    state First {
+        [*] --> Second
+
+        state Second {
+            [*] --> second
+            second --> Third
+
+            state Third {
+                [*] --> third
+                third --> [*]
+            }
+        }
+    }
+```
+
+### Example (Transitions between composite states)
+
+Define transitions between composite states:
+
+```mermaid
+stateDiagram-v2
+    [*] --> First
+    First --> Second
+    First --> Third
+
+    state First {
+        [*] --> fir
+        fir --> [*]
+    }
+    state Second {
+        [*] --> sec
+        sec --> [*]
+    }
+    state Third {
+        [*] --> thi
+        thi --> [*]
+    }
+```
+
+### Example (Choice)
+
+Model a choice between two or more paths using `<<choice>>`:
 
 ```mermaid
 stateDiagram-v2
-    [*] --> Idle
-    Idle --> Processing : Start
-    Processing --> Completed : Success
-    Processing --> Error : Failure
-    Error --> Idle : Retry
-    Completed --> [*]
+    state if_state <<choice>>
+    [*] --> IsPositive
+    IsPositive --> if_state
+    if_state --> False: if n < 0
+    if_state --> True : if n >= 0
+```
+
+### Example (Forks)
+
+Specify a fork in the diagram using `<<fork>>` and `<<join>>`:
+
+```mermaid
+stateDiagram-v2
+    state fork_state <<fork>>
+    [*] --> fork_state
+    fork_state --> State2
+    fork_state --> State3
+
+    state join_state <<join>>
+    State2 --> join_state
+    State3 --> join_state
+    join_state --> State4
+    State4 --> [*]
+```
+
+### Example (Notes)
+
+Add notes to the right or left of a node:
+
+```mermaid
+stateDiagram-v2
+    State1: The state with a note
+    note right of State1
+        Important information! You can write
+        notes.
+    end note
+    State1 --> State2
+    note left of State2 : This is the note to the left.
+```
+
+### Example (Concurrency)
+
+Specify concurrency using the `--` symbol:
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active
+
+    state Active {
+        [*] --> NumLockOff
+        NumLockOff --> NumLockOn : EvNumLockPressed
+        NumLockOn --> NumLockOff : EvNumLockPressed
+        --
+        [*] --> CapsLockOff
+        CapsLockOff --> CapsLockOn : EvCapsLockPressed
+        CapsLockOn --> CapsLockOff : EvCapsLockPressed
+        --
+        [*] --> ScrollLockOff
+        ScrollLockOff --> ScrollLockOn : EvScrollLockPressed
+        ScrollLockOn --> ScrollLockOff : EvScrollLockPressed
+    }
+```
+
+### Example (Direction)
+
+Set the direction using `direction` statement:
+
+```mermaid
+stateDiagram
+    direction LR
+    [*] --> A
+    A --> B
+    B --> C
+    state B {
+      direction LR
+      a --> b
+    }
+    B --> D
+```
+
+### Example (Comments)
+
+Comments need to be on their own line, prefaced with `%%`:
+
+```mermaid
+stateDiagram-v2
+    [*] --> Still
+    Still --> [*]
+%% this is a comment
+    Still --> Moving
+    Moving --> Still %% another comment
+    Moving --> Crash
+    Crash --> [*]
+```
+
+### Example (Styling with classDefs)
+
+Define a style using `classDef` and apply using `class` statement:
+
+```mermaid
+stateDiagram
+   direction TB
+
+   accTitle: This is the accessible title
+   accDescr: This is an accessible description
+
+   classDef notMoving fill:white
+   classDef movement font-style:italic
+   classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+
+   [*]--> Still
+   Still --> [*]
+   Still --> Moving
+   Moving --> Still
+   Moving --> Crash
+   Crash --> [*]
+
+   class Still notMoving
+   class Moving, Crash movement
+   class Crash badBadEvent
+```
+
+### Example (Using ::: operator)
+
+Apply a classDef style using the `:::` operator:
+
+```mermaid
+stateDiagram
+   direction TB
+
+   accTitle: This is the accessible title
+   accDescr: This is an accessible description
+
+   classDef notMoving fill:white
+   classDef movement font-style:italic;
+   classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+
+   [*] --> Still:::notMoving
+   Still --> [*]
+   Still --> Moving:::movement
+   Moving --> Still
+   Moving --> Crash:::movement
+   Crash:::badBadEvent --> [*]
+```
+
+### Example (Spaces in state names)
+
+Spaces can be added to a state by first defining the state with an id and then referencing the id later:
+
+```mermaid
+stateDiagram
+    classDef yourState font-style:italic,font-weight:bold,fill:white
+
+    yswsii: Your state with spaces in it
+    [*] --> yswsii:::yourState
+    [*] --> SomeOtherState
+    SomeOtherState --> YetAnotherState
+    yswsii --> YetAnotherState
+    YetAnotherState --> [*]
+```
+
+### 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,26 +1,139 @@
 ## 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
+- Configuration: `disableMulticolor` to disable multi-color scheme
+- Theme variables: `cScale0` to `cScale11` for background colors, `cScaleLabel0` to `cScaleLabel11` for foreground colors
+
+Reference: [Mermaid Timeline Diagram Documentation](https://mermaid.js.org/syntax/timeline.html)
+
+### Example (Basic Timeline)
+
+A simple timeline with title and multiple events per period:
+
+```mermaid
+timeline
+    title History of Social Media Platform
+    2002 : LinkedIn
+    2004 : Facebook : Google
+    2005 : YouTube
+    2006 : Twitter
+```
+
+### Example (With Sections)
+
+Group time periods in sections/ages:
+
+```mermaid
+timeline
+    title Timeline of Industrial Revolution
+    section 17th-20th century
+        Industry 1.0 : Machinery, Water power, Steam <br>power
+        Industry 2.0 : Electricity, Internal combustion engine, Mass production
+        Industry 3.0 : Electronics, Computers, Automation
+    section 21st century
+        Industry 4.0 : Internet, Robotics, Internet of Things
+        Industry 5.0 : Artificial intelligence, Big data, 3D printing
+```
+
+### Example (With Text Wrapping)
+
+Use `<br>` to force line breaks in long text:
+
+```mermaid
+timeline
+    title England's History Timeline
+    section Stone Age
+      7600 BC : Britain's oldest known house was built in Orkney, Scotland
+      6000 BC : Sea levels rise and Britain becomes an island.<br> The people who live here are hunter-gatherers.
+    section Bronze Age
+      2300 BC : People arrive from Europe and settle in Britain. <br>They bring farming and metalworking.
+                : New styles of pottery and ways of burying the dead appear.
+      2200 BC : The last major building works are completed at Stonehenge.<br> People now bury their dead in stone circles.
+                : The first metal objects are made in Britain.Some other nice things happen. it is a good time to be alive.
+```
+
+### Example (With Section Title Wrapping)
+
+Use `<br>` in section titles and events:
+
+```mermaid
+timeline
+    title MermaidChart 2023 Timeline
+    section 2023 Q1 <br> Release Personal Tier
+      Bullet 1 : sub-point 1a : sub-point 1b
+           : sub-point 1c
+      Bullet 2 : sub-point 2a : sub-point 2b
+    section 2023 Q2 <br> Release XYZ Tier
+      Bullet 3 : sub-point <br> 3a : sub-point 3b
+           : sub-point 3c
+      Bullet 4 : sub-point 4a : sub-point 4b
+```
+
+### Example (With Configuration - Disable MultiColor)
 
-### Example
+Disable multi-color scheme using configuration:
 
 ```mermaid
+---
+config:
+  logLevel: 'debug'
+  theme: 'base'
+  timeline:
+    disableMulticolor: true
+---
 timeline
-    title Project Milestones
-    section 2024 Q1
-        Project Kickoff : Team formation
-        Requirements Gathering : Stakeholder meetings
-    section 2024 Q2
-        Development Phase 1 : Core features
-        First Release : Beta version
-    section 2024 Q3
-        Development Phase 2 : Advanced features
-        Production Launch : Public release
+    title History of Social Media Platform
+    2002 : LinkedIn
+    2004 : Facebook : Google
+    2005 : YouTube
+    2006 : Twitter
+```
+
+### Example (With Theme Variables)
+
+Customize color scheme using theme variables:
+
+```mermaid
+---
+config:
+  logLevel: 'debug'
+  theme: 'default'
+  themeVariables:
+    cScale0: '#ff0000'
+    cScaleLabel0: '#ffffff'
+    cScale1: '#00ff00'
+    cScale2: '#0000ff'
+    cScaleLabel2: '#ffffff'
+---
+timeline
+    title History of Social Media Platform
+    2002 : LinkedIn
+    2004 : Facebook : Google
+    2005 : YouTube
+    2006 : Twitter
+    2007 : Tumblr
+    2008 : Instagram
+    2010 : Pinterest
+```
+
+### 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,181 @@
 ## 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.
+
+**Note**: This is a new diagram type in Mermaid. Its syntax may evolve in future versions.
 
 ### 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
+- Configuration: `useMaxWidth`, `padding`, `diagramPadding`, `showValues`, `nodeWidth`, `nodeHeight`, `borderWidth`, `valueFontSize`, `labelFontSize`, `valueFormat`
+
+Reference: [Mermaid Treemap Diagram Documentation](https://mermaid.js.org/syntax/treemap.html)
+
+### Example (Basic Treemap)
+
+A simple treemap with categories and items:
+
+```mermaid
+treemap-beta
+"Category A"
+    "Item A1": 10
+    "Item A2": 20
+"Category B"
+    "Item B1": 15
+    "Item B2": 25
+```
+
+### Example (Hierarchical Treemap)
+
+A treemap with multiple levels of hierarchy:
+
+```mermaid
+treemap-beta
+"Products"
+    "Electronics"
+        "Phones": 50
+        "Computers": 30
+        "Accessories": 20
+    "Clothing"
+        "Men's": 40
+        "Women's": 40
+```
+
+### Example (With Styling)
+
+Style nodes using classDef:
+
+```mermaid
+treemap-beta
+"Section 1"
+    "Leaf 1.1": 12
+    "Section 1.2":::class1
+      "Leaf 1.2.1": 12
+"Section 2"
+    "Leaf 2.1": 20:::class1
+    "Leaf 2.2": 25
+    "Leaf 2.3": 12
+
+classDef class1 fill:red,color:blue,stroke:#FFD600;
+```
+
+### Example (Using classDef for Styling)
 
-### Example
+Another example of styling with classDef:
 
 ```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
+"Main"
+    "A": 20
+    "B":::important
+        "B1": 10
+        "B2": 15
+    "C": 5
+
+classDef important fill:#f96,stroke:#333,stroke-width:2px;
+```
+
+### Example (With Theme Configuration)
+
+Configure treemap theme:
+
+```mermaid
+---
+config:
+  theme: 'forest'
+---
+treemap-beta
+"Category A"
+    "Item A1": 10
+    "Item A2": 20
+"Category B"
+    "Item B1": 15
+    "Item B2": 25
+```
+
+### Example (With Diagram Padding)
+
+Adjust padding around the treemap:
+
+```mermaid
+---
+config:
+  treemap:
+    diagramPadding: 200
+---
+treemap-beta
+"Category A"
+    "Item A1": 10
+    "Item A2": 20
+"Category B"
+    "Item B1": 15
+    "Item B2": 25
+```
+
+### Example (With Currency Formatting)
+
+Format values as currency:
+
+```mermaid
+---
+config:
+  treemap:
+    valueFormat: '$0,0'
+---
+treemap-beta
+"Budget"
+    "Operations"
+        "Salaries": 700000
+        "Equipment": 200000
+        "Supplies": 100000
+    "Marketing"
+        "Advertising": 400000
+        "Events": 100000
+```
+
+### Example (With Percentage Formatting)
+
+Format values as percentages:
+
+```mermaid
+---
+config:
+  treemap:
+    valueFormat: '$.1%'
+---
+treemap-beta
+"Market Share"
+    "Company A": 0.35
+    "Company B": 0.25
+    "Company C": 0.15
+    "Others": 0.25
+```
+
+### 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,154 @@
 ## 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
+- Configuration: `width`, `height`, `titlePadding`, `titleFontSize`, `showTitle`, `xAxis`, `yAxis`, `chartOrientation`, `plotReservedSpacePercent`, `showDataLabel`
+- Theme variables: `backgroundColor`, `titleColor`, `xAxisLabelColor`, `xAxisTitleColor`, `xAxisTickColor`, `xAxisLineColor`, `yAxisLabelColor`, `yAxisTitleColor`, `yAxisTickColor`, `yAxisLineColor`, `plotColorPalette`
 
-### Example
+Reference: [Mermaid XY Chart Documentation](https://mermaid.js.org/syntax/xyChart.html)
+
+### Example (Simplest)
+
+The simplest example with only chart name and one data set:
 
 ```mermaid
-xychart-beta
+xychart
+    line [+1.3, .6, 2.4, -.34]
+```
+
+### Example (Bar Chart)
+
+A bar chart with categorical x-axis and numeric y-axis:
+
+```mermaid
+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)
+
+A line chart with categorical x-axis:
+
+```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)
+
+Combine bar and line charts in one diagram:
+
+```mermaid
+xychart
+    title "Sales Revenue"
+    x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
+    y-axis "Revenue (in $)" 4000 --> 11000
+    bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
+    line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
+```
+
+### Example (Horizontal Orientation)
+
+Horizontal chart orientation with numeric x-axis:
+
+```mermaid
+xychart horizontal
+    title "Product Comparison"
+    x-axis "Score" 0 --> 100
+    y-axis "Products"
+    bar [85, 70, 90]
+```
+
+### Example (Numeric X-axis Range)
+
+Use numeric range for x-axis:
+
+```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]
+```
+
+### Example (With Color Palette)
+
+Set custom colors for lines and bars using plotColorPalette:
+
+```mermaid
+---
+config:
+  themeVariables:
+    xyChart:
+      plotColorPalette: '#000000, #0000FF, #00FF00, #FF0000'
+---
+xychart
+title "Different Colors in xyChart"
+x-axis "categoriesX" ["Category 1", "Category 2", "Category 3", "Category 4"]
+y-axis "valuesY" 0 --> 50
+%% Black line
+line [10,20,30,40]
+%% Blue bar
+bar [20,30,25,35]
+%% Green bar
+bar [15,25,20,30]
+%% Red line
+line [5,15,25,35]
+```
+
+### Example (With Configuration and Theme)
+
+Full configuration example with width, height, showDataLabel, and theme variables:
+
+```mermaid
+---
+config:
+  xyChart:
+    width: 900
+    height: 600
+    showDataLabel: true
+  themeVariables:
+    xyChart:
+      titleColor: "#ff0000"
+---
+xychart
+    title "Sales Revenue"
+    x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
+    y-axis "Revenue (in $)" 4000 --> 11000
+    bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
+    line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
+```
+
+### Alternative (Flowchart - compatible with all Mermaid versions)
+
+If XY charts are not supported, use this flowchart alternative:
+
+```mermaid
+flowchart LR
+    Jan[Jan: 500] --> Feb[Feb: 600]
+    Feb --> Mar[Mar: 750]
+    Mar --> Apr[Apr: 800]
+    Apr --> May[May: 950]
+    May --> Jun[Jun: 1000]
 ```

skills/mermaid/examples/zenuml.md

@@ -1,26 +1,264 @@
 ## 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`
+- Title: `title Diagram Title` (optional)
+- 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"` or `A as Alice`
+- Messages:
+  - Sync message: `Participant1.method() -> Participant2` or `A.method()` (blocking)
+  - Async message: `Participant1.method() => Participant2` or `Alice->Bob: message` (non-blocking)
+  - Creation message: `new Participant()` (creates new object)
+  - Reply message: `a = A.SyncMessage()`, `return result`, or `@return A->B: result`
+- 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.js.org/syntax/zenuml.html)
+
+### Example (Basic Sequence)
+
+A simple sequence diagram with implicit participants:
+
+```mermaid
+zenuml
+    title Demo
+    Alice->John: Hello John, how are you?
+    John->Alice: Great!
+    Alice->John: See you later!
+```
+
+### Example (With Participants)
+
+Declare participants explicitly to control their order:
+
+```mermaid
+zenuml
+    title Declare participant (optional)
+    Bob
+    Alice
+    Alice->Bob: Hi Bob
+    Bob->Alice: Hi Alice
+```
+
+### Example (With Annotators)
+
+Use annotators to show symbols instead of rectangles:
+
+```mermaid
+zenuml
+    title Annotators
+    @Actor Alice
+    @Database Bob
+    Alice->Bob: Hi Bob
+    Bob->Alice: Hi Alice
+```
+
+### Example (With Aliases)
+
+Use aliases for convenient identifiers with descriptive labels:
+
+```mermaid
+zenuml
+    title Aliases
+    A as Alice
+    J as John
+    A->J: Hello John, how are you?
+    J->A: Great!
+```
+
+### Example (Sync Message)
+
+Sync (blocking) messages with nesting:
 
 ```mermaid
 zenuml
-    participant User
-    participant System
-    participant Database
-    
-    User.login() -> System
-    System.validate() -> Database
-    Database.query() -> System
-    System.response() -> User
+    title Sync message
+    A.SyncMessage
+    A.SyncMessage(with, parameters) {
+      B.nestedSyncMessage()
+    }
+```
+
+### Example (Async Message)
+
+Async (non-blocking) messages:
+
+```mermaid
+zenuml
+    title Async message
+    Alice->Bob: How are you?
+```
+
+### Example (Creation Message)
+
+Create new objects using the new keyword:
+
+```mermaid
+zenuml
+    new A1
+    new A2(with, parameters)
+```
+
+### Example (Reply Message - Three Ways)
+
+Three ways to express reply messages:
+
+```mermaid
+zenuml
+    // 1. assign a variable from a sync message.
+    a = A.SyncMessage()
+
+    // 1.1. optionally give the variable a type
+    SomeType a = A.SyncMessage()
+
+    // 2. use return keyword
+    A.SyncMessage() {
+    return result
+    }
+
+    // 3. use @return or @reply annotator on an async message
+    @return
+    A->B: result
+```
+
+### Example (Reply Message - Complex)
+
+Complex reply message with early return:
+
+```mermaid
+zenuml
+    title Reply message
+    Client->A.method() {
+      B.method() {
+        if(condition) {
+          return x1
+          // return early
+          @return
+          A->Client: x11
+        }
+      }
+      return x2
+    }
+```
+
+### Example (With Nesting)
+
+Nest sync messages naturally with braces:
+
+```mermaid
+zenuml
+    A.method() {
+      B.nested_sync_method()
+      B->C: nested async message
+    }
+```
+
+### Example (With Comments)
+
+Add comments with Markdown support:
+
+```mermaid
+zenuml
+    // a comment on a participant will not be rendered
+    BookService
+    // a comment on a message.
+    // **Markdown** is supported.
+    BookService.getBook()
+```
+
+### Example (With Loops)
+
+Express loops using while, for, forEach, or loop:
+
+```mermaid
+zenuml
+    Alice->John: Hello John, how are you?
+    while(true) {
+      John->Alice: Great!
+    }
+```
+
+### Example (With Alt - Alternative Paths)
+
+Express alternative paths with if/else:
+
+```mermaid
+zenuml
+    Alice->Bob: Hello Bob, how are you?
+    if(is_sick) {
+      Bob->Alice: Not so good :(
+    } else {
+      Bob->Alice: Feeling fresh like a daisy
+    }
+```
+
+### Example (With Opt - Optional)
+
+Render optional fragments:
+
+```mermaid
+zenuml
+    Alice->Bob: Hello Bob, how are you?
+    Bob->Alice: Not so good :(
+    opt {
+      Bob->Alice: Thanks for asking
+    }
+```
+
+### Example (With Parallel)
+
+Show actions happening in parallel:
+
+```mermaid
+zenuml
+    par {
+        Alice->Bob: Hello guys!
+        Alice->John: Hello guys!
+    }
+```
+
+### Example (With Try/Catch/Finally)
+
+Indicate exception handling with try/catch/finally:
+
+```mermaid
+zenuml
+    try {
+      Consumer->API: Book something
+      API->BookingService: Start booking process
+    } catch {
+      API->Consumer: show failure
+    } finally {
+      API->BookingService: rollback status
+    }
+```
+
+### 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
 ```