diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1360d13..456aab7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -53,8 +53,11 @@ registry/components/my_component/
 所有語言共用相同的合約格式：
 
 ```yaml
-canonical_id: "my_component"       # 小寫底線，全庫唯一
-display_name: "我的零件"
+canonical_id: "string_reverse"     # 見下方命名規範
+display_name: "字串反轉"            # 人類可讀，可中文，供 UI 顯示用
+description: >                     # 語意搜尋用，見下方說明
+  將字串內容倒序排列，適合測試、資料清洗、回文判斷等場景。
+  不依賴外部服務，純本地運算。
 category: "data"                   # api / logic / data / ai / style / anim / ui
 version: "v1"
 author: "@your-github-username"
@@ -104,6 +107,42 @@ credentials_required:
     inject_as: api_token
 ```
 
+### canonical_id 命名規範
+
+`canonical_id` 是零件的永久識別符，一旦上架不能更改（改名 = 新零件）。命名不統一會導致功能重複，請遵守以下規則：
+
+| category | 格式 | 範例 |
+|----------|------|------|
+| `api`（整合類） | `{服務名}` 或 `{服務名}_{動作}` | `gmail`、`gmail_send`、`google_sheets`、`google_sheets_append`、`telegram` |
+| `data`（資料處理） | `{資料型別}_ops` 或 `{動詞}_{名詞}` | `string_ops`、`array_ops`、`json_transform`、`csv_parse` |
+| `logic`（控制流） | `{結構名}_control` 或單詞動詞 | `if_control`、`foreach_control`、`try_catch`、`switch`、`wait` |
+| `ai`（AI 類） | `ai_{動作}` | `ai_transform_compile`、`ai_summarize`、`ai_classify` |
+
+**規則：**
+- 全部小寫、底線分隔、最多 4 個單詞
+- 禁止：中文、空格、大寫、連字號（`-`）、版本號混入（用 `version` 欄位表達）
+- `display_name` 才是人類可讀名稱，可以是「宇宙無敵 gsheets 新增一列」，`canonical_id` 不行
+
+**提交前自問：** 如果有人想用 AI 搜尋「幫我找一個可以新增 Google Sheets 列的零件」，他搜到的名字應該是什麼？答案就是你的 `canonical_id`。
+
+### description 寫法（語意搜尋）
+
+`description` 是語意搜尋的索引來源，用自然語言描述「能做什麼、適合什麼情境」，而不是重複零件名稱。
+
+**好的 description：**
+```yaml
+description: >
+  傳送 Gmail 電子郵件，適合 Workflow 完成後通知使用者、發送訂閱確認信、
+  錯誤警報通知等場景。支援自訂主旨、內文與收件人。需要 Gmail OAuth token。
+```
+
+**不好的 description（等於沒有）：**
+```yaml
+description: "Gmail 發信零件"   # 只是名稱的同義詞，搜不到任何額外資訊
+```
+
+原則：把這個 description 給一個不知道這個零件存在的人看，他能判斷「這就是我要的東西」嗎？
+
 ---
 
 ## TinyGo 零件開發