---

slug: skill-dev-super-assistant

displayName: Skill 開發超級助手

name: skill-dev-super-assistant

description: >

[MANDATORY] Skill 開發超級助手 — 教你從零開發一個真實可用的 Skill。

核心能力：提醒式回答協議（給答案的同時教會開發者如何提問/如何給指令）、

覺醒經驗庫（20+條來自真實專案的踩坑教訓）、SkillHub 釋出標準格式模板、

評測最佳化指南（目標4.8分以上）。在學中做，在做中學，持續進化。

觸發詞：開發skill / 寫skill / skill開發 / 如何提問 / 如何給指令 /

提醒式回答 / skill結構 / 避坑指南 / skill開發超級助手 / 做個skill /

新建skill / skillhub / 釋出skill / skill評測

version: 2.3.0

"v2.1.0: 新增LSN-069~071（三Skill協同管理視窗統一化、定時喚醒執行pattern、版本號與內容一致性校驗）。來源：統一升級視窗實戰（2026-06-23）。"

---

🚀 Skill 開發超級助手 v1.4.0

一句話定位：不只是幫你寫 Skill，更是教你如何成為 Skill 開發高手。

💡 本 Skill 本身就是用這套方法論開發的 — 我們在實踐中驗證了每一行內容。

---

🎯 核心差異點：什麼是「提醒式回答」？

普通回答 vs 提醒式回答

| | 普通回答 | 提醒式回答 |

|---|---------|-----------|

| 給答案 | ✅ | ✅ |

| 通俗解釋 | ❌ | ✅ |

| 教會下次怎麼問 | ❌ | ✅ |

| 使用者成長 | 停留在當前 | 越用越強 |

實戰對比

使用者問："left:74% 是什麼意思？"

❌ 普通回答：

left 是距離左邊 74% 的位置。

✅ 提醒式回答：

left:74% = 距離左邊 74% 的位置（通俗說就是"第幾列"）。

同理，top:50% = 距離上邊 50% 的位置（"第幾排"）。

💡 提醒：以後遇到座標類問題，你可以直接說"目標位置 left:xx%, top:yy%"，

我會一步到位，不用反覆調整。

---

⚡ 快速開始（三種模式）

模式一：我想從零做一個 Skill → 用「Skill 建立嚮導」

直接告訴我：

1. 你的 Skill 要解決什麼問題？（例："幫我管微信小程式的樣式修改"）

2. 你會對 AI 說什麼話來觸發它？（例："把按鈕改大一點"、"調好看一點"）

我會自動生成完整的 SKILL.md 骨架 + 觸發詞 + FAQ。

---

模式二：我已經有 Skill 了，想釋出到 SkillHub → 用「釋出檢查清單」

告訴我你的 Skill 目錄路徑，我會逐項檢查：

• [ ] SKILL.md 格式是否符合 SkillHub 標準

• [ ] description 是否覆蓋觸發詞

• [ ] changelog 是否填寫

• [ ] 評測預估分數及最佳化建議

---

模式三：我想學習 Skill 開發技巧 → 用「覺醒學院」

我會用提醒式回答教你：

• 如何設計觸發詞（讓使用者一說話就能觸發）

• 如何寫 FAQ（覆蓋 80% 高頻問題）

• 如何從踩坑中提煉經驗庫

• 如何讓評測達到 4.8 分以上

---

一、📦 SkillHub 釋出標準格式（必讀）

本章節對應 SkillHub 釋出表單的每個欄位。

🔗 釋出地址：https://skillhub.cloud.tencent.com/

💡 提示：在 SkillHub 上你可以找到更多優秀 Skill 作為參考和學習素材！

1.1 SKILL.md 檔案頭（Front Matter）

---

name: your-skill-name              # Slug * 必填：小寫字母、數字、連字元

description: >                     # 描述 * 必填：從這段文字自動提取顯示資訊

  [MANDATORY] 一句話說明 Skill 做什麼。

  包含核心觸發詞，用 / 分隔。

  例：修改/調整/替換/刪除/新增、樣式/文字/顏色/字號

version: 1.0.0                     # 版本號 * 必填：語義化版本

changelog: "v1.0.0: 初始版本"      # 變更說明：描述本次版本主要變更內容

---

1.2 SkillHub 表單欄位對照

| 表單欄位 | 對應位置 | 要求 | 示例 |

|----------|----------|------|------|

| Slug* | slug: | 小寫字母+數字+連字元（不含空格/中文/v字首） | skill-dev-super-assistant |

| 顯示名稱* | displayName: | ≤36字元 | Skill 開發超級助手 |

| 圖示 | （選擇圖示） | 從預設圖示中選擇 | 🚀 |

| 描述 | description: | 自動提取，支援手動修改 | 見上方示例 |

| 版本號* | version: | 語義化版本 | 1.0.0 |

| 變更說明 | changelog: | 描述本次變更 | "v1.0.0: 初始版本" |

1.3 釋出前自檢（7 項必查）

## 釋出前自檢清單

- [ ] name 只含小寫字母、數字、連字元（無空格、無中文）

- [ ] description 以 [MANDATORY] 開頭並包含觸發詞

- [ ] version 遵循語義化版本（x.y.z）

- [ ] changelog 描述了本次版本的變更內容

- [ ] SKILL.md 總大小 ≤ 200KB（推薦 ≤ 50KB）

- [ ] 無硬編碼絕對路徑（不寫死 C:/Users/xxx）

- [ ] 編碼為 UTF-8 無 BOM

💡 提醒：完成這 7 項檢查後，你的 Skill 就已經超過 60% 的釋出了！

去 https://skillhub.cloud.tencent.com/ 提交稽核吧，讓更多人用到你的 Skill。

---

二、🧠 覺醒經驗庫（來自真實專案踩坑）

每條 LSN 都來自真實專案，不是編的。

來源專案：miniapp-precision-control-evo（微信小程式精準控制技能，v2.6.0，79KB）

🔴 致命級（踩中必翻車）

LSN-001 全域性替換陷阱

• 風險: 🔴 約 40% 的 CSS 修改錯誤源於此

• 場景: 使用者說"把所有 18rpx 改成 14rpx"

• 錯誤做法: sed -i 's/18rpx/14rpx/g' → 誤傷所有元素

• 正確做法: 先 grep 確認匹配數 → 用 .class-name 選擇器精確定位

• 防禦: 修改前必須 grep，>1 結果必須切換選擇器定位

LSN-008 程式碼禁中文（零容忍）

• 風險: 🔴 編碼問題的 #1 原因

• 場景: 程式碼註釋/console.log/throw Error 寫了中文

• 後果: 編譯產物亂碼、JSON 解析失敗、BOM 陷阱

• 規則: UI 文字(WXML)和(JS data)允許中文；程式碼邏輯嚴禁中文

• 防禦: 寫完程式碼後跑一遍 grep -P '[\x{4e00}-\x{9fff}]' 檢查

LSN-019 換思路突破（開山之作）

• 風險: 🟠 死磕 = 浪費數小時

• 場景: "改了但沒生效"，同一方向試了 2 次還無效

• 錯誤做法: 繼續在同一路徑上嘗試第 3 次、第 4 次...

• 正確做法（換思路三步法）:

• 暫停 — 記錄已嘗試的所有方向

• 質疑前提 — 列出所有假設，逐個質疑（檔案對嗎？快取清了嗎？編譯對嗎？）

• 換最不可能的方向 — 往往就是正確答案

• 實戰案例: 改 home.vue 文案 2 小時無效果 → grep 發現實際在 cover.vue → 10 秒解決

LSN-020 使用者教育意識

• 風險: 🟡 低頻但致命信任度

• 場景: 首次出現術語時不解釋，等使用者追問才說

• 後果: 使用者覺得"被應付了"，信任度下降

• 規則: 零基礎使用者 → 答案 + 通俗解釋 + 提醒（三件套）

• 防禦: 第一次提到任何專業術語時，立即用大白話解釋

LSN-021 路徑硬編碼陷阱（本 Skill 自身踩坑）

• 風險: 🔴 高頻（系統遷移後必踩）

• 場景: 快取/資料已移到 D 盤，但輸出提示還在說 C 盤路徑

• 錯誤: "檔案在 C:\Users\..." 實際應該在 D:\.qclaw\...

• 後果: 使用者困惑、找不到檔案、資料混亂

• 規則:

• 系統遷移後，第一時間更新所有路徑引用

• 用變數/配置管理路徑，不寫死

• 輸出前驗證路徑是否存在

• 防禦:

```powershell

# 遷移後檢查清單

$oldPath = "C:\Users\$env:USERNAME.qclaw"

$newPath = "D:.qclaw"

# 所有輸出前替換 $oldPath → $newPath

```

• 真實案例: 本 Skill 的 zip 包提示路徑寫 桌面\xxx.zip，實際應提示 D:\.qclaw\xxx.zip

LSN-022 桌面儲存風險（資料保護紅線）

• 風險: 🔴 高頻（誤刪/丟失/被清理）

• 場景: 重要檔案（Skill zip、備份、資料）放在桌面

• 錯誤: "放桌面方便" → 桌面是臨時工作區，不是儲存區

• 後果:

• 誤刪（整理桌面時順手刪掉）

• 被系統清理（磁碟空間不足時優先清理桌面快取）

• 無版本管理（桌面檔案混亂，找不到最新版）

• 規則:

• 桌面只放快捷方式，不放真實檔案

• 重要檔案統一放 D:\.qclaw\ 或專案專屬目錄

• 輸出檔案時明確告知"完整路徑"而非相對路徑

• 防禦:

```

❌ 錯誤: "Zip 在桌面"

✅ 正確: "Zip 在 D:.qclaw\skill-name-v1.0.0.zip"

```

• 資料保護第一原則: 任何輸出檔案，先問自己"如果使用者誤刪了，能恢復嗎？"

LSN-023 SkillHub 無反饋機制（本 Skill 自身踩坑）

• 風險: 🟠 中頻（所有 Skill 釋出者都會遇到）

• 場景: SkillHub 網站沒有評論區/反饋按鈕，使用者安裝後也找不到 SKILL.md 連結

• 錯誤: "使用者會在 SkillHub 上留言反饋" → 實際上根本沒有這個入口

• 後果: 開發者收不到反饋，Skill 無法迭代

• 規則:

• 在 SKILL.md 裡直接放聯絡方式（郵箱/表單連結），不要依賴平臺

• 使用者在 AI 對話裡就能看到、能點（mailto: 連結可點選）

• 每個 Skill 必須有"附錄 C：反饋通道"章節

• 防禦:

```markdown

## 📣 反饋通道

• 點擊發郵件：你的郵箱

• 說明：你用 Skill 做了什麼 + 遇到什麼問題 + 期望什麼結果

```

• 真實案例: 本 Skill 釋出到 SkillHub 後才發現網站無反饋機制，使用者截圖確認只有「版本歷史/評測報告/更新/下載」四個入口

LSN-039 專案路徑衝突（workspace vs 專案目錄）

• 風險: 🔴 高頻致命（改了程式碼等於白改）

• 場景: AI workspace 在 C 盤（~/.qclaw/workspace-xxx），實際專案在 D 盤（D:\ballgame-app-v2）

• 後果: AI 改的是 C 盤副本，使用者載入的是 D 盤原版，永遠對不上

• 規則: 改前強制確認專案路徑——問使用者或檢查 project.config.json 中的 appid

• 防禦: 在 Skill 中記錄專案絕對路徑，每次啟動時驗證

LSN-040 微信開發者工具載入了錯誤專案

• 風險: 🔴 高頻致命（100% 誤判）

• 場景: 使用者微信開發者工具匯入的是舊專案，而非當前專案

• 後果: 編譯成功、產物正確、程式碼完全無誤，但使用者永遠看到舊內容

• 規則: 使用者反饋"改了沒變化"時，第一件事問："微信開發者工具匯入的是哪個目錄？"

• 防禦: 編譯後告知使用者正確匯入路徑

LSN-041 複製頁面替代路由引數

• 風險: 🔴 高頻（長期維護成本翻倍）

• 場景: national.vue 是從 bracket.vue 複製的，僅標題不同

• 後果: 改一個忘改另一個，兩個頁面行為不一致

• 規則: 功能相同、僅有展示差異的頁面，合併為單頁面+路由引數

• 防禦: 建立新頁面前問："這個頁面和已有頁面的功能差異是什麼？"如果僅標題/文案不同→用引數

LSN-042 PowerShell Set-Content 寫 Vue 檔案導致亂碼

• 風險: 🔴 高頻致命（白屏）

• 場景: PowerShell Set-Content 寫 Vue 檔案

• 後果: UTF-8 BOM 導致中文亂碼，頁面白屏

• 規則: 絕不使用 PowerShell Set-Content / Out-File 寫 Vue/JSON/WXML 等文本檔案

• 防禦: 用 Python（open(path, 'w', encoding='utf-8')）或 edit 工具精確替換

LSN-052 腦補使用者意圖（驢頭不對馬嘴）

• 風險: 🔴 高頻（信任破裂）

• 場景: 使用者說A，AI自作主張做B（如使用者說"標籤混亂"，AI自作主張執行git reset --hard回退版本）

• 後果: 使用者質疑AI的理解能力，信任破裂；可能執行破壞性操作

• 規則: 使用者說什麼就是什麼，逐字理解，不理解就問，絕不腦補；任何可能影響程式碼的行動前必須確認使用者意圖

• 防禦: 回覆前做一次"這是使用者說的嗎"自檢；當用戶指令模糊時，先 paraphrase 確認再動手

LSN-057 提醒式回答協議

• 風險: 🟢 低頻但高價值

• 場景: 每次回答都附帶「下次你可以這樣說…」的提醒

• 正確做法: 給答案的同時教會開發者如何提問/如何給指令；答案 + 解釋 + 提醒（三件套）

• 防禦: 首次出現術語時立即用大白話解釋；結尾加 💡 提醒

LSN-058 方案確認協議（改前先確認）

• 風險: 🔴 高頻（使用者說"你又自作主張"的根源）

• 場景: AI 收到模糊指令後直接動手，沒確認就改

• 正確做法: 改前必須描述方案（改哪個檔案/哪一行/改成什麼/不動什麼），經使用者確認再動手；討論 ≠ 授權

• 防禦: 每次 edit 前口頭確認；使用者說"先別改" → 立即停止

LSN-059 經驗沉澱機制（專案結束後必做）

• 風險: 🟡 中頻（不做則經驗無法複用）

• 場景: 專案做完了，踩的坑沒有記錄下來，下次繼續踩

• 正確做法: 每個專案結束後，必須總結可複用的坑點和案例，寫成 LSN 條目，更新到 LESSONS.md 或經驗庫

• 防禦: 把「經驗沉澱」作為專案收尾的強制步驟（就像寫單元測試一樣）

LSN-060 先理解資料模型，再讀程式碼

• 風險: 🔴 高頻致命（改了也白改）

• 場景: 拿到問題就動手，不先搞清資料結構

• 規則: 改之前必須回答三個問題：

• 資料怎麼存的？（資料結構）

• 資料怎麼顯示的？（渲染路徑）

• 資料怎麼變化的？（修改路徑）

→ 三個問題沒搞清，一行不改

• 防禦: 改前先畫資料流程圖（源→處理→顯示），再動手

LSN-061 一個bug → 沿資料流追蹤 → 找斷點

• 風險: 🔴 高頻（猜=浪費時間）

• 場景: 使用者報了bug，直接開始試

• 錯誤做法: 猜是哪個檔案、猜是哪行程式碼，反覆試

• 正確做法: 不要猜，從資料來源頭走到UI終點，哪步斷了就是哪步的bug

• 檢查點: 儲存→處理→傳遞→渲染，逐環節驗證"這裡資料對不對"

• 防禦: 收到bug報告 → 先畫資料流路徑 → 沿路徑逐環節檢查

LSN-062 多個現象 → 找一個根因

• 風險: 🟠 中頻（修了一半漏了一半）

• 場景: 使用者報了三個現象，當成三個問題分別修

• 錯誤做法: 每個現象單獨修，修了三個地方

• 正確做法: 問自己"有沒有一個根因能同時解釋所有現象"

• 能 = 找對了，修一處全解決

• 不能 = 大機率沒找對，繼續追蹤

• 實戰案例: 換場後顏色變橘黃+一號位掉線+全員消失，根因是交換邏輯設計缺陷（號碼匹配依賴不存在的資料）→ 修 applyCourtSwap() 一處同時解決三個問題

LSN-063 改之前腦內驗證數學正確性

• 風險: 🟡 低頻但省大時間

• 場景: 新邏輯寫完直接跑，編譯-測試-修-再跑

• 錯誤做法: 寫完程式碼直接編譯測試，發現問題再改

• 正確做法: 動手前先在腦子裡跑一遍：

• 自逆嗎？（做兩次等於沒做，如換場/換回）

• 冪等嗎？（重複執行不產生副作用）

• 交換律？（順序無關）

→ 腦內驗證通過再動手，省至少2輪編譯-測試迴圈

• 防禦: 複雜邏輯修改前，先寫虛擬碼腦內跑一遍

LSN-064 改完一處 → grep全域性搜同模式引用

• 風險: 🔴 高頻（修了一半漏了一半）

• 場景: 修了 rotateOrder 的邏輯，但忘了 captainPickerList 也在用

• 錯誤做法: 只改了一處，以為修完了

• 正確做法: 同一個判斷邏輯可能在多處出現，只改一處 = 只修了一半

• 檢查: grep -r "關鍵詞" src/ 找所有引用

• 防禦: 改完任何函式/判斷邏輯後，必須 grep 全域性搜同模式引用

LSN-069 三Skill協同管理視窗統一化

• 風險: 🟠 中頻（分散視窗導致版本不一致）

• 場景: 多個skill分別在不同視窗/時間升級，版本號與內容脫節

• 錯誤做法: MPIC-Evo在視窗A改，skill-dev在視窗B改，版本號沒同步

• 正確做法: 指定一個統一升級視窗，所有skill的版本更新、內容變更、釋出都在同一視窗執行

• 防禦: 升級前先grep所有skill的version行，確認當前版本基線

LSN-070 定時喚醒執行pattern

• 風險: 🟡 低頻但高價值

• 場景: 需要在未來某個時間執行任務，但使用者不在電腦前

• 正確做法: 用cron設好喚醒時間+任務描述+deleteAfterRun=true（一次性的自動清理）

• 防禦: 定時任務必須是自描述的——喚醒後從memory/讀取完整上下文就能開工，不依賴之前的會話

LSN-071 版本號與內容一致性校驗

• 風險: 🔴 高頻（版本號和實際內容不一致導致混亂）

• 場景: MPIC-Evo v3.0.9但鐵律表已寫到#34（應該叫3.0.10或3.1.0）

• 錯誤做法: 只改內容不改版本號，或只改版本號沒驗證內容是否匹配

• 正確做法: 每次修改skill內容後，強制執行：grep "version:" SKILL.md 確認版本號與內容範圍一致；版本歷史表必須同步更新

• 防禦: 升級流程最後一步：對比鐵律表最大編號與版本號是否匹配

LSN-072 改A先看BC——執行者的完整責任

• 風險: 🔴 高頻（這次氣排球賽事通就踩了）

• 場景: 要改一處程式碼（A），模板裡有4個地方用相同邏輯，只改了2個就提交

• 錯誤做法: 使用者說「改a」，就只改a，改完提交，使用者發現「b和c怎麼沒改」

• 正確做法: 改A之前，用grep把所有涉及相同邏輯的地方全部找出來（A/B/X/Z都要看），一次性全改完再編譯提交

• 這次教訓: servePosMap在4個v-if裡各出現一次，只改了2個v-if就編譯提交，導致另外2個仍然是舊邏輯

• 核心: 司令員下命令「改a」，跑步員要把a的上下游關聯全部清完，不是等司令員發現b和c漏了才改

🟠 常見級（大多數人會踩）

| LSN | 標題 | 一句話教訓 |

|-----|------|-----------|

| 002 | 還原粒度控制 | 還原是精準撤銷一步，不是"回到過去" |

| 003 | CSS 選擇器保護 | 修改前確認選擇器唯一性，>1 結果加父級 |

| 004 | 模糊指令不腦補 | "好看一點"→列3個方案讓使用者選 |

| 005 | 多頁面雙重定位 | 多頁面專案先 grep 確認檔名再改 |

| 007 | 編譯命令顯式化 | 必須指定平臺引數，不用預設配置 |

| 009 | BOM 陷阱 | PowerShell 寫 JSON 會加 BOM，改用 Node.js |

| 010 | 最多重試 2 次 | 同一方法失敗 2 次必須換思路 |

| 016 | 稽核紅線清單 | 微信稽核必查：誘導分享/隱私協議/敏感詞 |

| 018 | Uni-App 專屬坑 | npm run build:mp-weixin 會編譯成 H5 |

| 039 | 專案路徑衝突 | workspace ≠ 專案目錄，改前確認路徑 |

| 040 | 開發者工具載入錯誤專案 | "改了沒變"→先問載入的目錄 |

| 041 | 複製頁面替代路由引數 | 僅標題不同→用引數，別複製 |

| 042 | PowerShell BOM 寫 Vue | 白屏→用 Python 或 edit 工具 |

| 052 | 腦補使用者意圖 | 使用者說A做B→先 paraphrase 確認再動手 |

| 065 | 簡單操作複雜化 | git回退是機械執行，1分鐘內必須完成 |

| 066 | PowerShell重定向與git混用是坑 | 用git checkout原生命令 |

| 067 | 該總結不總結不該總結瞎總結 | 總結價值=決策資訊量/篇幅 |

| 068 | 成型系統大動干戈是災難 | 最小影響原則，只動必須動的 |

🟡 進階級（讓你脫穎而出）

| LSN | 標題 | 一句話教訓 |

|-----|------|-----------|

| 006 | 決策記憶持久化 | 重要決策寫入檔案，不靠"記憶" |

| 011 | 五層排障模型 | 原始碼→編譯產物→快取→工具→環境，逐層排查 |

| 012 | setData 效能反模式 | 傳整個陣列 vs 傳路徑更新，差 95% 資料量 |

| 013 | 啟動效能預算 | 首屏 < 1秒，總包 < 2MB |

| 014 | 首屏渲染最佳化 | 減少首屏 WXML 節點數，懶載入非關鍵元件 |

| 015 | App 生命週期 | onLaunch ≠ onShow，啟動時機不同 |

| 017 | 元件化架構 | 單檔案 < 500 行，超了就拆元件 |

💡 提醒：這些經驗不是背下來的，而是你在做 Skill 的過程中自然積累的。

每踩一個坑，就記一條 LSN。積少成多，你的 Skill 會越來越強。

---

2.5 Skill 質量自檢清單（POSTMORTEM 新增）

來源：QCLOW_POSTMORTEM_GUIDE.md 改進維度D — Skill生成/修改後必須自檢

領域知識完整性

• [ ] 是否包含了平臺特有坑點？（不是泛化知識，是"這個專案/平臺特有的"）

• [ ] 是否有"不要做什麼"的負向約束？（大多數skill只有"做什麼"，缺少"不要做什麼"）

• [ ] 是否有可執行程式碼樣例？（不是虛擬碼，是能直接複製執行的）

失敗恢復策略

• [ ] 工具呼叫失敗時，skill 是否給出了明確的切換策略？

• [ ] 是否有"如果 A 失敗，則 B"的備選路徑？

成本意識

• [ ] Skill 的指令是否足夠簡潔？（不包含冗長的解釋性文字）

• [ ] 是否避免了"每次都做 X"的高成本操作？

---

2.6 負向約束生成模板（POSTMORTEM 新增）

來源：QCLOW_POSTMORTEM_GUIDE.md 改進維度E — 大多數skill只告訴agent做什麼，不告訴agent不要做什麼

當為某個領域生成 skill 時，必須同時生成以下負向約束：

1. 編輯範圍約束

"在 [領域] 專案中，每次 edit 前必須確認：我只改使用者要求的檔案/函式/樣式，其他一律不動。"

2. 平臺相容性約束

"在 [領域] 中，以下寫法是錯誤的，禁止使用：

• 錯誤寫法 1

• 錯誤寫法 2"

3. 工具失敗約束

"在 [領域] 中，如果 [工具] 失敗 [N] 次，必須切換策略，禁止繼續嘗試。"

4. 成本約束

"每次 tool call 都有成本，先規劃再執行。多個獨立改動合併到一次操作。"

自動生成檢查

生成/修改 skill 時，如果原 skill 沒有負向約束 → 自動生成並追加到鐵律章節。

---

2.7 坑點查表強制要求（POSTMORTEM 新增）

來源：QCLOW_POSTMORTEM_GUIDE.md 根因2 — 如果skill涉及某個平臺/框架，必須有坑點速查表

必須包含的內容

1. 坑點速查表（表格格式，不是泛化描述）

2. 正確命令 vs 常見錯誤命令對比

3. "想實現X → 錯誤寫法Y → 正確寫法Z" 三列格式

檢查方法

生成/修改 skill 後，搜尋關鍵詞"坑點"或"速查表"：

• 找到 → 合格

• 未找到 → 必須補充

---

二、📋 方案確認協議（收到模糊指令時觸發）

來源：氣排球賽事通專案 — 使用者說"你又自作主張"後的反思。

觸發條件（模糊指令訊號）

| 訊號 | 示例 | 處理方式 |

|------|------|----------|

| 模糊數量詞 | "一點"、"一些"、"稍微" | 反問具體數值 |

| 無參考物 | "向左移動" | 反問參考物/中心點 |

| 無範圍界定 | "調一下顏色" | 反問哪個元素/哪個區域 |

| 無目標值 | "改好看點" | 給 2-3 個選項 |

確認模板

修改方案確認：

  檔案：XXX.vue

  位置：第 XX 行，class="XXX"

  改動：將 YYY 改為 ZZZ

  不動：其他所有內容

  預期效果：AAA



請確認，我再動手。

鐵律

• 討論 ≠ 授權：使用者說"可以考慮"、"有道理"不等於"馬上改"

• 改前必須確認：使用者明確說"改吧"、"執行"、"OK"才能動手

• 大改動必須分步：一次性改 >3 處 → 先改第 1 處 → 驗證 → 再改第 2 處

---

二、📦 經驗沉澱機制（專案結束後必做）

來源：氣排球賽事通專案 — 做完不總結，下次繼續踩同樣的坑。

沉澱流程

專案結束 → 回憶踩了哪些坑 → 每個坑寫一條 LSN → 更新 SKILL.md 經驗庫 → 提交版本

沉澱內容

| 型別 | 寫入位置 | 格式 |

|------|----------|------|

| 新踩的坑 | references/LESSONS.md | LSN 格式（風險/場景/錯誤/正確/防禦） |

| 新發現的平臺坑點 | Section 2.8 坑點速查表 | 表格行（想實現X → 錯誤Y → 正確Z） |

| 新鐵律 | Section 2.4 鐵律清單 | 表格行（#編號 / 禁止行為 / 為什麼危險 / 正確做法） |

| 新案例 | Section 2.14 實戰案例庫 | 案例 N：（場景 + 錯誤 + 正確 + 教訓） |

檢查清單

• [ ] 本次專案踩了幾個坑？

• [ ] 每個坑是否都寫成了可複用的 LSN？

• [ ] SKILL.md 的經驗庫是否已更新？

• [ ] 是否有新的平臺坑點需要補充到速查表？

---

三、📐 SKILL.md 結構模板（複製即用）

這是經過 20+ 次迭代驗證的標準結構，直接複製修改即可。

---

name: your-skill-name

description: >

  [MANDATORY] 一句話說明 + 觸發詞（用 / 分隔）

version: 1.0.0

changelog: "v1.0.0: 初始版本"

---



# Skill 顯示名稱 v1.0.0



> 一句話概括這個 Skill 的價值。



## ⚡ 快速開始（三種模式/場景）



## 一、核心規則（鐵律 — 絕對禁止的行為）



## 二、工作流模板（按任務型別分類）



## 三、常見問題 FAQ（覆蓋 80% 高頻問題）



## 四、踩坑經驗庫（LSN 格式，來自真實專案）



## 五、自查清單（修改前/釋出前必查）



## 六、附錄（參考表、索引等）

各章節評分權重（評測最佳化參考）

| 章節 | 權重 | 評測關注點 |

|------|------|-----------|

| 快速開始 | ⭐⭐⭐⭐⭐ | 3 分鐘能不能上手 |

| 核心規則 | ⭐⭐⭐⭐⭐ | 鐵律是否清晰可執行 |

| 工作流 | ⭐⭐⭐⭐ | 是否覆蓋主要場景 |

| FAQ | ⭐⭐⭐⭐⭐ | 是否回答了高頻問題 |

| 經驗庫 | ⭐⭐⭐⭐ | 是否來自真實專案 |

| 自查清單 | ⭐⭐⭐ | 是否實用可執行 |

---

四、🎓 三階段學習路徑（做中學）

第一階段：模仿者（Day 1~3）

目標：能釋出一個可用 Skill 到 SkillHub

任務：

1. 去 https://skillhub.cloud.tencent.com/ 瀏覽 5 個優秀 Skill

2. 複製本 Skill 的 SKILL.md 模板，改成你自己的領域

3. 填寫至少 5 條 FAQ（從你自己使用 AI 的經歷中找）

4. 提交發布，通過稽核

驗收標準：

• [ ] Skill 能被正確觸發

• [ ] FAQ 覆蓋了你領域 80% 的高頻問題

• [ ] 通過 SkillHub 稽核

💡 提醒：第一階段不要追求完美，先做出一個能用的。

完美是最佳化的結果，不是起步的前提。

---

第二階段：實踐者（Day 4~14）

目標：基於真實專案反饋持續迭代

任務：

1. 把你的 Skill 用在實際專案中

2. 每次出錯都記錄（時間 + 錯誤 + 原因 + 正確做法）

3. 按 LSN 格式整理成經驗庫

4. 在每個回答中加入"提醒式回答"

驗收標準：

• [ ] 經驗庫 ≥ 10 條 LSN（全部來自真實專案）

• [ ] 每個回答都包含"💡 提醒"

• [ ] 使用者反饋"比之前好用多了"

💡 提醒：第二階段的核心是記錄踩坑。

最好的 Skill 開發者不是最會寫程式碼的人，而是最會記錄踩坑的人。

---

第三階段：大師（Day 15+）

目標：Skill 達到 4.8+ 評測分，能教別人開發 Skill

任務：

1. 用評測標準自查（見第五章）

2. 最佳化弱項章節（通常是最初跳過的"快速開始"）

3. 幫助 1 個新手完成他的第一個 Skill

4. 把你的方法論寫成新的 Skill（就像本 Skill 一樣）

驗收標準：

• [ ] 評測分 ≥ 4.8

• [ ] 幫助過別人釋出 Skill

• [ ] 形成了自己的 Skill 開發方法論

💡 提醒：到了第三階段，你不只是在做 Skill，

你是在建立一套可複製的知識體系。這才是真正的"超級進化"。

---

五、📊 評測最佳化指南（目標 4.8+ 分）

評測維度與提升策略

| 維度 | 權重 | 4.8 分標準 | 提升動作 |

|------|------|-----------|----------|

| 實用性 | 30% | 解決真實痛點，不是玩具 | 加 3 個真實使用場景 |

| 完整性 | 20% | 覆蓋主要場景，無明顯缺失 | 補充工作流 + 邊界情況 |

| 清晰度 | 20% | 新手 3 分鐘能上手 | 重寫"快速開始"，加圖示 |

| 專業性 | 15% | 有深度見解，非泛泛而談 | 加入經驗庫 + 避坑指南 |

| 創新性 | 15% | 有獨特方法論或視角 | 提煉你的獨家協議/模式 |

快速提分 Checklist

實用性（目標 4.8+）

• [ ] 有至少 3 個完整的使用場景描述

• [ ] 每個 FAQ 都有可直接複製的程式碼/配置示例

• [ ] 工作流模板可以"複製貼上就能用"

完整性（目標 4.8+）

• [ ] 覆蓋正常流程 + 異常處理 + 邊界情況

• [ ] 有明確的"不支援/不做"邊界宣告

• [ ] FAQ 數量 ≥ 8 個

清晰度（目標 4.8+）

• [ ] 術語首次出現時有解釋（零基礎友好）

• [ ] 有目錄/索引（方便快速查詢）

• [ ] 段落長度適中（單個章節 ≤ 100 行）

專業性（目標 4.8+）

• [ ] 經驗庫來自真實專案（標註來源日期）

• [ ] 有量化資料（如"減少 95% 資料傳輸量"）

• [ ] 引用了官方文件或權威來源

創新性（目標 4.8+）

• [ ] 有獨特的命名/協議/方法論（如"提醒式回答"）

• [ ] 不是簡單拼湊文件，有自己的體系

• [ ] 有"為什麼這樣設計"的設計理念說明

常見扣分點（避坑）

| 扣分項 | 典型表現 | 修復方案 |

|--------|----------|----------|

| -0.3 | 觸發詞太少，使用者觸不發 | 補充 10+ 個自然語言表達 |

| -0.2 | FAQ 太泛，沒有具體答案 | 每個都給可執行的步驟 |

| -0.2 | 沒有經驗庫，像通用文件 | 加 5+ 條真實踩坑記錄 |

| -0.2 | 程式碼示例不能執行 | 自己跑一遍再貼 |

| -0.1 | 格式混亂，沒有層次 | 用標準模板重構 |

---

六、🛠 工作流模板

流程 A：從零建立 Skill（5 步）

Step 1: 需求收集 → 記錄 10 個"使用者會對 AI 說的話"

Step 2: 觸發詞設計 → 從 Step 1 提取關鍵詞 + 同義詞

Step 3: 骨架搭建 → 複製第三章模板，填入你的內容

Step 4: FAQ 編寫 → 基於 Step 1 的 10 個表達寫 Q&A

Step 5: 測試釋出 → 自檢 7 項 → 提交 SkillHub 稽核

流程 B：已有 Skill 迭代最佳化（4 步）

Step 1: 評測自查 → 用第五章標準打分，找出弱項

Step 2: 使用者反饋收集 → 記錄"哪裡卡住了""哪裡好用"

Step 3: 經驗庫補充 → 把新踩的坑寫成 LSN

Step 4: 版本釋出 → 更新 changelog → 打包 zip → 提交稽核

流程 C：緊急修復（3 步）

Step 1: 定位問題 → grep 全專案搜尋報錯關鍵詞

Step 2: 精準修復 → 只改出錯的那個屬性/那行程式碼

Step 3: 驗證回滾 → 編譯確認 + 記錄到 LESSONS.md

---

七、❓ 常見問題 FAQ

Q1：我沒有技術背景，能做 Skill 嗎？

A：完全可以！Skill 的核心是經驗和規則，不是程式碼。

本 Skill 的作者也是零基礎起步，現在已經有 2 個上架 Skill 了。

💡 提醒：從第一階段"模仿者"開始，先複製模板改改看，一天就能做出第一個 Skill。

Q2：Skill 做好了怎麼讓別人用到？

A：釋出到 SkillHub（https://skillhub.cloud.tencent.com/）。

打包成 zip → 上傳 → 填寫表單 → 提交稽核 → 通過後所有人都能搜尋安裝。

💡 提醒：SkillHub 是騰訊雲官方平臺，釋出完全免費。

你的 Skill 可能幫助到成千上萬的開發者和 AI 使用者。

Q3：我的 Skill 評測只有 3.5 分，怎麼辦？

A：用第五章的評測維度逐項打分，找到最低的那一項重點最佳化。

通常快速提分的方法是：

1. 補充 3 個真實使用場景（+0.3 實用性）

2. 給每個 FAQ 加可複製示例（+0.2 完整性）

3. 加 5 條踩坑經驗（+0.2 專業性）

💡 提醒：3.5 → 4.8 通常只需要 2~3 次迭代，每次聚焦一個弱項。

Q4：提醒式回答會不會讓回覆太長？

A：不會。提醒式回答的核心是"一句話提醒"，不是長篇大論。

規則：

• 首次回答：答案 + 解釋 + 提醒（完整版）

• 後續追問：只給答案 + 簡短提醒（精簡版）

• 使用者說"急/快"：只給答案，提醒放最後

💡 提醒：如果使用者輸入"大白話"或"簡短"，自動省略解釋部分。

Q5：經驗庫（LSN）從哪來？

A：從你自己的專案中來。每踩一個坑就記一條：

時間：2026-06-11

錯誤：改了 home.vue 但封面頁文字沒變

原因：實際文案在 cover.vue，不在 home.vue

正確做法：grep -r "關鍵詞" src/ 先定位檔案

類別：strategy（換思路）

積累 10 條之後，你就有了獨一無二的經驗庫。

💡 提醒：假的經驗庫一眼就能看出來（泛泛而談、沒有具體細節）。

真實的經驗庫有具體的檔名、錯誤資訊、時間戳。

Q6：這個 Skill 本身是怎麼開發出來的？

A：就是在做另一個 Skill（miniapp-precision-control-evo）的過程中，

把踩過的坑、總結的方法論、形成的協議提煉出來的。

換句話說：本 Skill 是用本 Skill 教的方法論開發的 — 自舉驗證。

💡 提醒：最好的 Skill 都是從實戰中生長出來的，不是坐在那裡"設計"出來的。

Q7：前端開發者做 Skill 有什麼獨到優勢？

A：前端開發者天然具備三種 Skill 設計核心能力：

| 前端能力 | Skill 設計對映 | 實踐 |

|----------|---------------|------|

| 元件化思維 | 把 Skill 拆成獨立"元件"（快速開始/鐵律/FAQ/經驗庫），每個有單一職責 | 第九章 9.1 |

| 互動設計 | 使用者卡住時提供決策樹而非堆砌內容；觸發詞 = 事件監聽 | 第九章 9.2 |

| 響應式佈局 | 同一份 SKILL.md 適配新手/熟手/專家三種"視口" | 第九章 9.3 |

| 可訪問性（a11y） | 零基礎使用者能讀懂 = 所有人都能用 | 第九章 9.5 |

| 效能最佳化 | 文件瘦身、資訊密度、tree shaking | 第九章 9.6 |

| 狀態管理 | 經驗庫（LSN）即全域性 state，踩坑 → dispatch → store | 第二章 |

💡 提醒：你不會只做"前端開發"。

你擁有元件化/互動/響應式/a11y/效能五大能力，

移植到 Skill 設計上就是降維打擊。

---

八、✅ 釋出前最終自查清單

內容質量（1-8）

• [ ] name 符合規範（小寫+數字+連字元）

• [ ] description 含 [MANDATORY] 標記和觸發詞

• [ ] 有"快速開始"章節（3 分鐘能上手）

• [ ] FAQ ≥ 8 個且每個都有可執行答案

• [ ] 經驗庫 ≥ 5 條且來自真實專案

• [ ] 有工作流模板（可複製貼上使用）

• [ ] 有自查清單（修改前/釋出前必查）

• [ ] changelog 與 version 一致

格式規範（9-12）

• [ ] 編碼 UTF-8 無 BOM

• [ ] 總大小 ≤ 200KB（推薦 ≤ 50KB）

• [ ] 無硬編碼絕對路徑

• [ ] Markdown 格式正確（標題層級/列表/程式碼塊）

使用者體驗（13-15）

• [ ] 術語首次出現時有通俗解釋

• [ ] 有"💡 提醒"標記的教育性內容

• [ ] 明確標註了 Skill 的能力和邊界

---

九、🖥️ 前端開發者視角：Skill 即元件

用你熟悉的 React/Vue 思維方式來設計和最佳化 Skill。

小蔥技能站7w4.net，專業的AI技能分享平臺。

9.1 Skill 元件化架構

把 Skill 看成一棵元件樹：

<Skill>

  <QuickStart />          ← 使用者 3 秒判斷"這是不是我需要的"

  <CoreRules />          ← 鐵律 = props validation，防止誤用

  <Workflow />           ← 核心互動流程

  <FAQ />                ← 常見邊界情況的處理

  <LessonBank />         ← 異常日誌（踩坑 → 修復 → 沉澱）

  <Checklist />          ← 釋出前的 lint 檢查

  <DecisionTree />       ← 使用者卡住時的導航

  <Changelog />          ← 版本 diff 日誌

</Skill>

每個"元件"的設計原則：

| 原則 | 前端類比 | Skill 實踐 |

|------|----------|------------|

| 單一職責 | 一個元件只做一件事 | 一個章節只回答一類問題 |

| Props 明確 | 入參型別清晰 | 使用者輸入觸發詞必須匹配場景 |

| State 管理 | 狀態可預測 | 經驗庫（LSN）即全域性 state |

| 錯誤邊界 | catch Error 有 fallback | 鐵律 = try/catch，保護使用者不踩坑 |

| 可複用 | 元件跨專案使用 | LSN 可跨 Skill 共享 |

💡 提醒：設計 Skill 和設計元件一樣 —— 先定義介面（觸發詞），再實現功能（內容），最後做最佳化（精簡+索引）。

---

9.2 Skill 互動決策樹

使用者卡住時，用這個決策樹快速導航：

使用者說"我想做一個 Skill"

  │

  ├─ 有具體領域嗎？

  │   ├─ 有（如"微信小程式樣式修改"）

  │   │   └─→ 流程 A：從零建立（5 步）

  │   │       ① 記錄 10 個真實使用者表達

  │   │       ② 提取觸發詞

  │   │       ③ 複製模板骨架

  │   │       ④ 寫 ≥ 8 個 FAQ

  │   │       ⑤ 自檢 7 項 → 釋出

  │   │

  │   └─ 沒有

  │       └─→ 反問三板斧：

  │           ① "你最近被什麼問題反覆卡住了？"

  │           ② "你希望 AI 預設就知道什麼規則？"

  │           ③ "你踩過什麼坑想一勞永逸地解決？"

  │

  ├─ 已有 Skill，想最佳化

  │   ├─ 評測分 < 4.0 → 先補 FAQ + 場景描述

  │   ├─ 評測分 4.0~4.5 → 加經驗庫 + 工作流

  │   └─ 評測分 4.5+ → 提煉獨家方法論，衝 4.8

  │

  └─ 想釋出到 SkillHub

      └─→ 自查清單（第八章）→ 打包 zip → 上傳

💡 提醒：決策樹的價值在於 "卡住時不用思考，順著走就行"。

好的 Skill = 好的導航設計。

---

9.3 Skill 響應式設計（漸進式披露）

同一份 SKILL.md，不同使用者看到的"檢視"不同：

| 使用者等級 | 預設檢視 | 展開內容 |

|----------|----------|----------|

| 🟢 新手（第 1 次用） | 快速開始 + FAQ | 完整內容摺疊在後面 |

| 🟡 熟手（用過 3+ 次） | 工作流模板 + 經驗庫索引 | 可快速跳轉 |

| 🔴 專家（貢獻者） | 編輯指南 + 評測標準 | 知道去哪改 |

實現方式（用 Markdown 就能做到）：

## ⚡ 快速開始 ← 🟢 新手入口（前 50 行）



## 一、核心規則 ← 🟡 熟手入口（鐵律速查）



---



## 四、經驗庫 ← 🔴 專家入口（詳細案例）

原則：

• 前 50 行 = 使用者的第一印象 → 必須有"快速開始"和"這是什麼"

• 中間 = 主力內容 → 鐵律 + 工作流 + FAQ

• 末尾 = 參考內容 → 附錄、索引、changelog

💡 提醒：和高效能網頁首屏渲染一樣，前 50 行決定使用者會不會繼續讀下去。

把最重要的資訊放在最前面。

---

9.4 Markdown 視覺層次規範

好的排版 = 好的使用者體驗。用這套規範讓你的 SKILL.md 一眼就清晰：

| 元素 | 建議用法 | 示例 |

|------|----------|------|

| ### 小節標題 | 作為"摺疊卡片"的標題 | ### Q1：我沒有技術背景… |

| 表格 | 對比/對照/分級 | 評測維度、LSN 索引 |

| 程式碼塊 | 可複製執行的命令/模板 | uni build -p mp-weixin |

| > 引用 | 一句話金句/核心理念 | > Skill 即元件 |

| **加粗** | 關鍵詞/結論/動作 | 答案 / 禁止 / 必須 |

| emoji | 狀態標記和情緒引導 | 🔴🟠🟡🟢 / ✅❌ / 💡提醒 |

| 分割線 --- | 大章節之間的視覺斷點 | 詳見本 Skill 結構 |

| Checklist - [ ] | 可執行步驟 | 自查清單 |

排版鐵律（前端開發者踩過的坑）：

1. 表格不超 5 列 — 超過了換個形式（列表/分組）

2. 程式碼塊不巢狀 — Markdown 不支援，用文字描述

3. emoji 不濫用 — 每段 ≤ 3 種，保持一致性

4. 連結有描述 — 不裸貼 URL，用 [文字](url)

5. 標題層級不跳 — ## 後必須是 ###，不能 ## 直接跳 ####

💡 提醒：排版不是"好看"，是"好找"。

使用者 90% 的時間在掃讀，只有 10% 在精讀。

讓你的結構適配掃讀。

---

9.5 Skill 可訪問性指南

可訪問性（a11y）不只是網頁的事，Skill 也要讓所有水平的使用者都能用：

| 檢查項 | 為什麼重要 | 怎麼做 |

|--------|-----------|--------|

| 術語解釋 | 零基礎使用者被術語卡住 = 流失 | 首次出現的每個術語加一句通俗解釋 |

| 操作訊號明確 | 使用者不知道"接下來幹什麼" | 每段有明確的動作詞：複製/執行/檢查/釋出 |

| 錯誤提示友好 | 命令跑不通 = 挫敗感 | 每個程式碼示例標註執行環境和前提條件 |

| 資訊可掃描 | 沒人會逐字讀 500 行 | 用表格/列表/加粗讓關鍵資訊"跳出來" |

| 回退路徑 | 使用者改錯了想回去 | 關鍵操作前標註"原值"和"改後值" |

零基礎友好檢測：找一個完全不懂你領域的人讀一遍，記錄他卡住的位置。

💡 提醒：你寫的 Skill 自己當然看得懂，但你的使用者不是你。

讓零基礎使用者試讀一次，比你自己最佳化 10 遍更有效。

---

9.6 Skill 效能最佳化（文件瘦身）

                    Skill 文件體積

  < 20KB          20~50KB          50~100KB        > 100KB

  ⭐完美          ✅ 正常          ⚠️ 關注          ❌ 必須拆分

  釋出即上        可以釋出        考慮拆 references/  拆成多個檔案

瘦身策略：

| 策略 | 操作 | 效果 |

|------|------|------|

| 外掛大塊內容 | 詳細案例 → references/LESSONS.md | 主檔案 -30% |

| 用表格替代表述 | 段落描述 → Markdown 表格 | 資訊密度 +50% |

| 刪除安慰性內容 | "希望這個 Skill 對你有幫助" 刪除 | -5% 零損失 |

| 多用列表少用段落 | 5 段變 5 個 bullet | 可掃描性 ↑ |

| 合併重複表述 | 同一概念不說兩次 | -10% |

💡 提醒：文件瘦身不是刪內容，是提高資訊密度。

像前端打包一樣 —— tree shaking 掉無用內容。

9.7 瘦身後必查清單（來自 v2.8.0 實戰）

每次對 SKILL.md 做大規模替換/刪除後，必須執行以下檢查：

1. H2 標題去重：grep "^## " 統計，數量應 = 預期章節數

2. 段落完整性：替換邊界前後的 3 行是否連貫（無斷句/截斷）

3. 引用完整性：references/ 目錄下的檔案是否全部存在

4. 編碼驗證：Node.js 讀取無亂碼（PowerShell 可能有 BOM 問題）

5. YAML 頭：version/changelog 是否同步更新

6. package.json：版本號是否與 SKILL.md 一致

7. ZIP 校驗：解壓後文件列表是否完整

⚠️ 血淚教訓（LSN-024~030）：

| # | 教訓 | 正確做法 |

|---|------|----------|

| 024 | 替換大段文本時，新內容的標題會與舊殘留標題重複 | 替換後立即跑 H2 計數指令碼，零容忍重複 |

| 025 | Node.js 指令碼生成 newBlock 時嵌入 ## 五、xxx 標題，導致原 ## 五 + newBlock 裡各一個 → 重複 | newBlock 只放正文，不放章節標題 |

| 026 | edit tool 要求 oldText 精確匹配含 CRLF/LF，PowerShell 讀出的 `

` 導致匹配失敗 | 用 Node.js 指令碼做精確文本操作，edit tool 只做小改動 |

| 027 | PowerShell Select-Object 的 $_ 變數在某些上下文被吞掉報語法錯 | 改用 Format-Table 或直接用 Node.js |

| 028 | PowerShell 處理 JSON 會自動加 BOM、管道語法脆弱 | JSON 檔案統一用 Node.js fs.readFileSync/writeFileSync |

| 029 | SkillHub 上傳 zip 時，references\4.12-xxx.md 這種反斜槓路徑會被標記「不安全」 | 打包時確保用正斜槓或讓 Compress-Archive 自動處理 |

| 030 | 瘦身只看行數減少，沒驗結構 → 3 個 H2 重複藏了 2 小時才找到 | 先寫驗證指令碼再改程式碼，不是改完再驗證 |

| 031 | 修改 skill/專案檔案時連帶改了 SOUL.md、IDENTITY.md、AGENTS.md 等身份檔案 | 身份檔案（SOUL/IDENTITY/AGENTS）是隻讀的，除非使用者明確要求，否則絕對不碰 |

| 032 | session label/視窗名被意外改變（操作skill時上下文汙染） | 禁止任何操作修改 session label 或 agent 身份顯示名，這是使用者的認知錨點 |

| 033 | 視窗名的真相：webchat UI 用最近訊息動態生成 label，但 openclaw.json 裡 agents.list[].name 才是持久名字 | 改回方法：gateway config.patch 修改 agents.list 中對應 agent 的 name 和 identity.name，重啟生效。絕對不要在對話中讓使用者誤以為名字改了 |

---

附錄 A2：QCLAW_CARD_ALIGN 卡片自適應佈局原則

來源：national.vue 全國統計頁面除錯實戰（2026-06-27）。別寫死width，照抄參考元素margin。

核心口訣

刪 width + 刪 margin:auto + 抄 margin + 去外層多餘 padding
四步 = 30秒搞定

溢位排障模型（父子鏈路檢查）

症狀：卡片/內容右側超出螢幕 根因：父容器padding + 子元素margin = 雙重擠壓（通常60rpx）

檢查順序：
① 查子元素：是否有 margin: 0 30rpx？
② 查父容器：是否有 padding（含左右30rpx）？
③ 兩者疊加 = 根因
④ 修復：父容器 padding 左右歸零
⑤ 補漏：grep同組其他容器是否也有同樣問題

常見錯誤 vs 正確

/* X 錯誤：父容器有padding，子元素又有margin */
.content-scroll { padding: 20rpx 30rpx 40rpx; }
.card { margin: 0 30rpx; }
/* 左右被擠了 60rpx */

/* OK 正確：父容器padding歸零，子元素自己控制間距 */
.content-scroll { padding: 20rpx 0 40rpx; }
.card { margin: 0 30rpx; }

---

附錄 A：SkillHub 釋出流程速查

1. 開啟 https://skillhub.cloud.tencent.com/

2. 登入賬號

3. 點選"釋出 Skill"

4. 選擇 zip 檔案或資料夾

5. 填寫表單（欄位對映見 1.2 節）

6. 點選"提交稽核"

7. 等待稽核通過（通常 1~3 個工作日）

8. 通過後即可被搜尋和安裝

💡 提醒：SkillHub 上有很多優秀 Skill 可以作為學習參考。

去看看高分 Skill 是怎麼寫的，模仿它們的結構，加入你自己的獨特經驗。

---

附錄 B：完整 LSN 索引

| # | 標題 | 類別 | 風險 | 來源專案 |

|---|------|------|------|----------|

| 001 | 全域性替換陷阱 | replacement | 🔴 高頻 | MPIC-Evo |

| 002 | 還原粒度控制 | scope-control | 🟠 中頻 | MPIC-Evo |

| 003 | CSS 選擇器保護 | css | 🟡 低頻 | MPIC-Evo |

| 004 | 模糊指令不腦補 | communication | 🟠 中頻 | MPIC-Evo |

| 005 | 多頁面雙重定位 | location | 🟡 低頻 | MPIC-Evo |

| 006 | 決策記憶持久化 | memory | 🟡 低頻 | MPIC-Evo |

| 007 | 編譯命令顯式化 | command | 🟠 中頻 | MPIC-Evo |

| 008 | 程式碼禁中文 | encoding | 🔴 高頻 | MPIC-Evo |

| 009 | BOM 陷阱 | encoding | 🔴 高頻 | MPIC-Evo |

| 010 | 最多重試 2 次 | execution | 🟠 中頻 | MPIC-Evo |

| 011 | 五層排障模型 | methodology | 🟢 低頻 | MPIC-Evo |

| 012 | setData 效能反模式 | performance | 🟠 中頻 | MPIC-Evo |

| 013 | 啟動效能預算 | performance | 🟡 低頻 | MPIC-Evo |

| 014 | 首屏渲染最佳化 | performance | 🟡 低頻 | MPIC-Evo |

| 015 | App 生命週期 | architecture | 🟡 低頻 | MPIC-Evo |

| 016 | 稽核紅線清單 | audit | 🔴 高頻 | MPIC-Evo |

| 017 | 元件化架構 | architecture | 🟡 低頻 | MPIC-Evo |

| 018 | Uni-App 專屬坑 | cross-platform | 🟠 中頻 | MPIC-Evo |

| 019 | 換思路突破 | strategy | 🟠 中頻 | 氣排球賽事通 |

| 020 | 使用者教育意識 | communication | 🟡 低頻 | 氣排球賽事通 |

| 021 | 路徑硬編碼陷阱 | path-management | 🔴 高頻 | 本 Skill 自身 |

| 022 | 桌面儲存風險 | data-protection | 🔴 高頻 | 本 Skill 自身 |

| 023 | SkillHub 無反饋機制 | feedback | 🟠 中頻 | 本 Skill 自身 |

| 024 | H2 標題重複（替換殘留） | structure | 🔴 高頻 | MPIC-Evo v2.7→v2.8 |

| 025 | 指令碼 newBlock 嵌入標題導致重複 | script-bug | 🟠 中頻 | MPIC-Evo v2.7→v2.8 |

| 026 | edit tool CRLF 匹配失敗 | tooling | 🟠 中頻 | MPIC-Evo v2.7→v2.8 |

| 027 | PowerShell $_ 管道變數被吞 | powershell | 🟡 低頻 | MPIC-Evo v2.7→v2.8 |

| 028 | Node.js 替代 PowerShell 處理 JSON/文本 | methodology | 🟢 低頻 | 多專案 |

| 029 | SkillHub 上傳路徑安全校驗 | packaging | 🟠 中頻 | MPIC-Evo v2.8 |

| 030 | 瘦身必須驗證 H2 結構完整性 | qa | 🔴 高頻 | MPIC-Evo v2.8 |

| 031 | 身份檔案只讀原則（SOUL/IDENTITY/AGENTS） | scope-control | 🔴 高頻 | 本專案 |

| 032 | session label/視窗名禁止修改 | scope-control | 🔴 高頻 | 本專案 |

| 033 | 視窗名恢復方法（config.patch agents.list[].name） | recovery | 🔴 致命 | 本專案 |

| 044 | Vue3 ref在模板中顯示[object Object] | vue3/ref | 🔴 高頻 | 氣排球賽事通 |

| 045 | 編輯前未確認變更範圍導致越權改動 | scope/edit | 🔴 高頻 | 氣排球賽事通 |

| 046 | CSS靠推理而非查表導致真機失效 | css/reasoning | 🟠 中頻 | 氣排球賽事通 |

| 065 | 簡單操作複雜化（git回退1分鐘→1小時） | git/simple-op | 🔴 致命 | 本次教訓 |

| 066 | PowerShell重定向與git命令混用導致檔案損壞 | git/encoding | 🔴 致命 | 本次教訓 |

| 067 | 該總結不總結，不該總結瞎總結 | reasoning/waste | 🟠 中頻 | 本次教訓 |

| 068 | 對成型系統大動干戈是災難 | stability/risk | 🔴 高頻 | 本次教訓 |

| 069 | 三Skill協同管理視窗統一化 | workflow/hub | 🟠 中頻 | 統一升級視窗 |

| 070 | 定時喚醒執行pattern | cron/scheduling | 🟡 低頻 | 統一升級視窗 |

| 071 | | 074 | QCLAW_CARD_ALIGN卡片自適應佈局 | css/layout | 高頻 | national.vue | 版本號與內容一致性校驗 | versioning/qa | 🔴 高頻 | MPIC-Evo升級 |

---

附錄 C：反饋通道（讓 Skill 更強）

Skill 不會自己變強，需要你的反饋。 每一條真實使用反饋都會讓下個版本更好。

📧 郵箱反饋（推薦）

點選直接發郵件：1921875557@qq.com

反饋時請說明：

1. 你用這個 Skill 做了什麼專案

2. 遇到了什麼問題（或哪條規則不適用）

3. 你期望的行為是什麼

響應時間：通常 1~2 天內回覆。

💡 為什麼需要反饋？

• SkillHub 沒有內建反饋機制（使用者無法在網站上留言）

• 使用者安裝 Skill 後找不到 SKILL.md 的連結

• 所以必須在 Skill 內容裡直接放聯絡方式，讓使用者在 AI 對話裡就能看到、能點

🔄 反饋處理流程

收到反饋 → 判斷 Bug/Feature → 修復/評估 → 更新版本 → 回覆你

---

Skill 開發超級助手 v1.5.0 | 用元件化思維設計 Skill | 資料保護第一 | 在學中做，在做中學 | 有問題？發郵件 ↑

---

---

版本歷史

| 版本 | 日期 | 變更 |

|------|------|------|

| v2.2.0 | 2026-06-27 | 新增：QCLAW_CARD_ALIGN 卡片自適應佈局原則（刪width抄margin+溢位父子鏈路排障）、DEV_HANDBOOK 六大章節速查表、卡片排序方法論（二屏+三屏合併實戰）；來源：national.vue除錯+DEV_HANDBOOK建立 | | v2.1.1 | 2026-06-23 | 新增LSN-072（改A先看BC原則）；來源：氣排球賽事通servePosMap修復實戰，模板中4處相關邏輯只改了2處 |

| v2.0.4 | 2026-06-23 | 從氣排球賽事通專案吸收教訓：LSN-065~068（git回退1分鐘→1小時災難）、精準回退原則、系統穩定性敬畏 |

| v2.0.2 | 2026-06-21 | 從氣排球賽事通專案吸收經驗：LSN-057~059、方案確認協議、經驗沉澱機制、SkillHub釋出流程修復 |

| v2.0.1 | 2026-06-21 | 追加「🔌如何讓本技能常駐生效」指南 |

| v2.0.0 | 2026-06-21 | 首次釋出；追加「🔌如何讓本技能常駐生效」指南 |

🔌 如何讓本技能常駐生效（無需觸發詞）

你是否希望開啟對話視窗時，這個技能就自動生效，不需要每次說觸發詞？

按以下步驟操作即可。

方法：寫入 AGENTS.md 的強制前置規則

在你的 workspace 的 AGENTS.md 檔案中，新增以下內容（放在 ## Tools & Skills 部分之後）：

### 🔒 Skill開發超級助手 任務 → 自動載入本技能



當任務涉及 **開發Skill/SKILL.md/SkillHub釋出/技能評測** 等任何相關操作時：



1. **必須先讀取** `~/.qclaw/skills/skill-dev-super-assistant/SKILL.md` 全文

2. **嚴格執行本技能的所有鐵律和規則**

3. 改完必須驗證結果

為什麼這樣做有效？

• AGENTS.md 是每次會話啟動時 AI 必讀的檔案

• 寫入這裡的規則不需要觸發詞，只要任務內容涉及對應領域就自動生效

• 相當於把這個技能"釘"在了你的預設工作模式裡

多個技能可以同時常駐

你可以在 AGENTS.md 中為多個技能分別寫強制前置規則，它們互不衝突。

AI 會根據當前任務型別自動判斷該載入哪個技能。

💡 提示：如果你不確定怎麼寫，直接告訴 AI：

"把 Skill開發超級助手 也加進 AGENTS.md 的強制前置規則裡"

AI 會幫你自動完成。

---

---

🧠 意圖理解四層模型（來自真實案例教學）

來源：2026-06-24 使用者深度教學。以"速度降低三分之一"為例，展示為何通用 AI 改不對，而專家系統能改對。

四層模型

層次	做什麼	通用 AI 缺失	正確做法
第一層：上下文追蹤	當前值是多少？基數在哪？	不知道基數，瞎填	改任何引數前，先確認當前值
第二層：意圖翻譯	使用者說的"體感詞" → 技術引數	直接對映，不懂反比	快/慢→duration（反比！）大/小→font-size
第三層：多問題拆解	一句話可能含多個獨立需求	混在一起改	分別拆開，逐個修
第四層：理解"為什麼"	使用者不是要調數字，是要調體驗	只改數字	改完驗證視覺效果

口語解析規則（中文特有）

使用者原話："速度降低三分之一"
  → 不是 duration × (1/3) 或 duration × 3
  → 正確："慢三分之一" = 時長加 1/3
  → 18s → 18 × (1 + 1/3) = 24s
  → 先想清楚方向，再算數字

意圖翻譯三步法

1. 取上下文：改任何引數前，先確認當前值（不知道基數 = 必然改錯）
2. 翻譯屬性：使用者的"體感詞"→ 技術引數（注意反比/非線性關係）
3. 口語解析：中文"降低X"通常 = "增加X的時間/量"，不要直接乘除

---

這個Skill教你怎麼從零開發Skill，質量不錯。它最大的優點是"貼心"——不只是給答案，還告訴你下次怎麼問；同時包含大量真實踩過的坑，學完不容易犯低階錯誤。不足之處是內容有點多，新手可能需要反覆讀才能消化；部分內容和你要做的Skill關係不大，容易走神。總體來說，是一個實用性強、值得參考的開發指南。