---
name: writing-markdown
description: >
  協助撰寫、整理、輸出結構清晰的 Markdown 技術文件，包含流程圖、表格、架構圖等視覺化元素。
  當使用者提出以下任何需求時必須載入此技能：「幫我整理成文件」、「把這個寫成 md」、「輸出技術文件」、
  「寫一份設計文件」、「整理成 Markdown」、「幫我產出文件」、「write a technical doc」，
  或任何需要將對話內容、技術討論、架構設計、流程說明整理成結構化 Markdown 文件的情境。
  注意：此技能專注於技術文件撰寫（含 Mermaid 圖表、ASCII 架構圖），不涉及對話匯出（請用 export-conversation）。
argument-hint: "[輸出檔案路徑]"
---

# 文件撰寫指南

## 核心原則

1. **專注概念層次**：不包含詳細的程式實作細節，專注於概念、流程和架構
2. **視覺化優先**：多使用流程圖、表格、架構圖來說明概念，可使用 ASCLL ART
3. **標準格式**：使用標準 Markdown 語法，時序圖與流程圖使用 Mermaid Code  
4. **繁體中文**：所有內容使用繁體中文撰寫

## 文件結構範本

根據文件類型選擇適當的結構：

### 技術設計文件
```
# 標題
## 問題背景（為何需要）
## 解決方案概述
## 架構設計（含圖表）
## 優缺點分析（使用表格）
## 適用場景
## 結論
```

### 流程說明文件
```
# 標題
## 流程概述
## 流程圖（Mermaid）
## 各步驟說明
## 注意事項
```

## 視覺化元素使用指南

### 表格：用於比較與分析
- 欄位清晰、對齊一致
- 使用 emoji 標記狀態（✅ ❌ ⚠️）

### 流程圖：用於說明處理流程
```mermaid
flowchart TD
    A[開始] --> B{條件判斷}
    B -->|是| C[處理A]
    B -->|否| D[處理B]
```

### 時序圖：用於說明元件互動
```mermaid
sequenceDiagram
    participant A as 服務A
    participant B as 服務B
    A->>B: 請求
    B-->>A: 回應
```

### ASCII 架構圖：用於說明系統結構
```
┌─────────────────┐
│  元件名稱        │
│  ├── 子項目 A   │
│  └── 子項目 B   │
└─────────────────┘
```

## 範例參考

參考 `references/technical-design-example.md` 作為文件撰寫範本

## 輸出位置

- 如果用戶指定了輸出路徑 `$1`，將文件寫入該路徑
- 如果未指定路徑，詢問用戶要存放的位置與檔名