這篇文件講什麼

Skill 管理 介紹了 Skill 的概念和操作流程，內建 Skill 一覽 列了 19 個開箱即用的 Skill。這篇文件是實作指南：

• frontmatter 每個欄位什麼時候用、踩坑點在哪；
• 正文怎麼結構化寫，照搬內建 Skill 的成熟範本；
• 怎麼用輔助檔案（指令稿、參考資料、子文件）讓 Skill 更強大；
• 端到端寫一個《MySQL 慢查詢排障 Runbook》Skill，從空白到上線。

前置條件：先在 LLM 管理 裡配一條預設 LLM，否則寫完 Skill 也沒法測試。

一、Skill 的基本形態

一個 Skill 就是一份帶 YAML frontmatter 的 Markdown 檔案，檔名固定為 SKILL.md。最簡形態：

---
name: my-first-skill
description: 當使用者問到 XXX 時使用，覆蓋 YYY 場景
---

# 這裡是正文

你的領域知識 / 操作指引 / 範本 / 範例……

加上輔助檔案就是一個 Skill 包：

my-first-skill/
├── SKILL.md              # 主檔案（必須）
├── runbooks/
│   ├── disk-full.md
│   └── oom.md
└── scripts/
    └── collect-context.sh

打包成 .zip 或 .tar.gz 上傳即可。

二、Frontmatter 欄位速查

下面這些欄位都是可選的，只有 name 和 description 是必填。

核心欄位

觸發與匹配增強欄位

執行行為欄位（進階）

元資料 / 合規欄位

完整範例：內建 n9e-create-alert-rule 的 frontmatter

---
name: n9e-create-alert-rule
description: 在夜莺(n9e)平台上创建告警规则。支持 Prometheus/Loki/ES/MySQL/TDengine/ClickHouse/Doris/Host 等所有数据源类型。
max_iterations: 20
builtin_tools:
  - create_alert_rule
  - list_busi_groups
  - list_datasources
  - list_metrics
  - list_notify_rules
  - list_files
  - read_file
  - list_databases
  - list_tables
  - describe_table
---

注意到三個關鍵點：

1. description 一句話點題 + 列舉範圍——先講清主場景（建立告警規則），再列出支援的資料來源類型，讓 AI 在不該用的時候不會誤觸發；
2. max_iterations: 20——建立告警規則是多步驟動作（選業務組 → 選資料來源 → 找指標 → 看標籤 → 讀範本 → 拼 payload → 建立），預設 10 步不夠；
3. builtin_tools 區分「動作工具」和「探索工具」——create_alert_rule 是最終落地的寫操作工具；其它 list_* / read_file / describe_table 等是輔助 AI 拿元資料的唯讀工具。寫 Skill 時這兩類都要列全，否則 Agent 拿不到工具就只能瞎猜。

三、寫好 description：讓 AI 準確命中你的 Skill

如果一句話只能記住一個建議：description 欄位決定一切。

為什麼這麼重要

夜鶯 AI 是這樣決定要不要用你的 Skill 的：

1. 使用者輸入 → 擷取關鍵字；
2. 把關鍵字 + 所有啟用 Skill 的 description 餵給 LLM；
3. LLM 選出最匹配的 1-2 個 Skill 載入到上下文。

如果你 description 寫「故障處理」，LLM 看到使用者說「我這台機器為什麼慢」時，匹配置信度極低，你的 Skill 不會被載入。

4 個 description 寫法範式

範式 1：動詞驅動 + 多語言關鍵字

description: 幫使用者判斷一台機器到底是 真宕機 / agent 假死 / 網路抖動 / 維護中。
當使用者問「為什麼這台機器失聯」、「host 失聯告警是不是誤報」、「categraf 卡住了嗎」、
「心跳停了為啥還能 ping 通」等觸發本技能。

要點：動詞在前（判斷 / 失聯 / 卡住）、典型使用者原話直接抄進來（使用者問什麼就匹配什麼）。

範式 2：場景列表 + 排他宣告

description: 在夜鶯平台上建立告警規則。支援 Prometheus/Loki/ES/MySQL/TDengine/ClickHouse/
Doris/Host 等所有資料來源類型。

要點：先一句話講清主場景 + 列舉覆蓋範圍，避免 AI 在不該用的時候用上。

範式 3：英文動詞 + 中文動詞全覆蓋

description: This skill should be used when the user asks to "troubleshoot",
"diagnose", "debug alert", "investigate incident", "故障定位", "告警排查",
"问题诊断", "排障", "查告警", "分析告警", "根因分析", or discusses
monitoring/alerting/observability issues...

要點：英文/中文都要寫，團隊裡可能兩種說法都有人用。

範式 4：核心立場 + 適用邊界

description: 協助使用者產生、修改或排障夜鶯告警自癒指令稿。當使用者要求「寫一個磁碟清理/重啟服務/
清理日誌/dump 程序/reload nginx」等自癒指令稿，或問「自癒指令稿怎麼拿告警傳過來的參數」、「stdin
是什麼格式」、「timeout 應該填多少」等時使用。**本技能專注指令稿正文層**——若使用者要改告警規則、
接收人或通知範本，引導到對應 skill。

要點：寫明邊界（「專注 XX 層」、「不涉及 YY」）能避免 AI 在不該用的場景誤觸發。

Description 不要這麼寫

❌ description: 故障處理
❌ description: 這是一個有用的 skill
❌ description: 協助維運人員
❌ description: SOP for ops team

這種寬泛、抽象、沒有任何具體關鍵字的描述，AI 幾乎不會命中。

四、正文結構範本：抄就行

看了 19 個內建 Skill，幾乎所有「重型」Skill 都按這套範本寫。照搬就能寫出高品質 Skill。

---
name: <你的 skill 名>
description: <按前面四個範式寫好>
builtin_tools:
  - <你要用的工具>
---

# Skill: <這個 Skill 的中文標題>

## 適用範圍

**進本 skill**：
- 使用者原話場景 1
- 使用者原話場景 2
- 使用者原話場景 3

**不進本 skill**：
- 容易混淆但不該走本 skill 的場景 1 → 轉 `xxx-skill`
- 容易混淆但不該走本 skill 的場景 2 → 轉 `yyy-skill`

## 一句話原則

<一句最重要的立場，比如「只看一層證據下結論幾乎都是錯的」。模型讀了會先入為主，
後面所有步驟都會圍繞這個原則展開。>

## 工作流程

### 第 1 步：<動作名>
<具體怎麼做、呼叫什麼工具、看什麼欄位、怎麼判斷>

### 第 2 步：<動作名>
<具體怎麼做……>

### 第 3 步：<動作名>
<具體怎麼做……>

## 輸出格式

<明確告訴模型 Final Answer 長什麼樣，最好給一份 Markdown 骨架>

## 注意事項 / 紅線

1. **<不要做什麼>**：原因是 ……
2. **<必須做什麼>**：原因是 ……

## 範例

### 使用者輸入
<一句真實的使用者原話>

### 工作流程
1. <一步一步做了什麼>
2. <呼叫了什麼工具，拿到什麼結果>

### 輸出
<最終回答的樣子>

五個寫法心法

1. 開頭一句話點題——用最簡潔的語言說清楚這個 Skill 是幹啥的、什麼時候該用。
2. 結構化——用 ## 子任務 把大任務拆開，每個子任務下再用列表/程式碼區塊寫步驟。Markdown 結構越清晰，模型越容易穩定執行。
3. 少用「我建議」、多用祈使句——模型會模仿你的語氣。寫「請執行 top -c 並截圖前 10 行」比「建議你可以試試 top」更確定。
4. 明確邊界——寫清楚「不要做什麼」。例如「不要主動修改生產環境設定，只輸出建議命令」。
5. 配範例——給一個具體的「輸入 → 輸出」例子，比千言萬語都管用。

五、輔助檔案：讓 Skill 更強大

Skill 包不只是一份 SKILL.md。根目錄下可以放任意輔助檔案，正文裡透過相對路徑引用，AI 會用 read_file / list_files / grep_files 工具按需讀取。

用法 1：分場景範本

內建 n9e-create-alert-rule Skill 就是個好例子：

n9e-create-alert-rule/
├── SKILL.md
└── datasources/
    ├── clickhouse.md
    ├── doris.md
    ├── elasticsearch.md
    ├── host.md
    ├── loki.md
    ├── mysql.md
    ├── pgsql.md
    ├── prometheus.md
    ├── tdengine.md
    └── victorialogs.md

SKILL.md 裡寫：

通用路徑——傳 `cate` + `rule_config_json`，`rule_config_json` 的結構
**先透過 `read_file` 讀取 `datasources/<cate>.md` 取得範本**，再填充實際值

這樣 SKILL.md 本身就不用塞 11 種資料來源的範本細節，Agent 按需讀對應的子文件。SKILL.md 上限 64KB，單檔案上限 16MB——大而全的內容用輔助檔案承載。

用法 2：指令稿片段

如果你的 Skill 是「寫自癒指令稿」類，把常用指令稿片段單獨存成檔案：

disk-cleanup-skill/
├── SKILL.md
└── scripts/
    ├── clean-logs.sh
    ├── clean-docker.sh
    └── clean-yum-cache.sh

SKILL.md 引導：「按使用者場景，先 read_file 讀 scripts/<場景>.sh 作為骨架，再按需修改」。

用法 3：參考資料 / Cheat Sheet

promql-skill/
├── SKILL.md
└── cheatsheet/
    ├── common-queries.md   # 常用 PromQL 範本
    └── label-conventions.md  # 公司內部標籤命名規範

打包限制

• 單個歸檔最多 100 個檔案
• 解壓後總大小 ≤ 50MB
• 單檔案 ≤ 16MB
• SKILL.md 本身 ≤ 64KB
• 不允許：符號連結、絕對路徑、.. 路徑穿越
• 自動過濾：.DS_Store、._*、__MACOSX/ 等系統雜訊

六、上傳打包

方式 1：線上建立（簡單 Skill）

適用：只有一份 SKILL.md、沒有輔助檔案、內容簡短的場景。

操作流程：

1. 進入 AI 設定 → Skill 管理，點 + → 線上建立 Skill；
2. 填表：名稱、描述、提示詞指令（SKILL.md 的正文），進階設定裡可填授權條款/相容性/預先授權工具/元資料；
3. 儲存。

詳見 Skill 管理 → 線上建立。

方式 2：本機上傳（推薦）

適用：帶輔助檔案、有版本管理需求、要在團隊/實例間分發的場景。

操作流程：

1. 本機按上面「基本形態」組織好目錄結構：

   my-skill/
   ├── SKILL.md
   └── (其它輔助檔案)
   

2. 打包成 .zip 或 .tar.gz：

   # zip
   cd my-skill && zip -r ../my-skill.zip . -x "*.DS_Store" "__MACOSX/*"
   
   # 或 tar.gz
   tar czf my-skill.tar.gz -C parent_dir my-skill
   

   可以帶頂層目錄（如 my-skill/SKILL.md），也可以直接把 SKILL.md 放包根。兩種都能解。

3. 進入 AI 設定 → Skill 管理，點 + → 本機上傳 Skill，選檔案上傳。

4. 上傳成功後，Skill 出現在列表裡，預設啟用。

替換 / 下載 / 刪除

• 替換：詳情頁三點選單選「替換」上傳新歸檔，完全覆蓋目前 Skill（包括所有輔助檔案）。
• 下載：把目前 Skill 匯出成壓縮包。這是團隊內分發、版本備份的標準動作——一份 Skill 在一個實例打磨好，下載下來上傳到其它實例。
• 刪除：二次確認後刪除，所有關聯檔案級聯刪除，無法復原。建議先「下載」做一份備份再刪。

七、除錯 Skill：怎麼知道它工作了？

寫完一個 Skill，最常見的尷尬是**「我啟用了，但 AI 好像沒用上」**。下面是排查流程：

第 1 步：description 命中檢查

問一句應該命中你 Skill 的話，看 AI 回答的開頭是否引用了你的領域知識 / 用了你定義的術語 / 走了你寫的流程。

• 沒引用、答案泛泛 → description 沒命中，回去把 description 改具體；
• 引用了但沒按你的方法答 → 正文不夠明確，把工作流程寫得更祈使句；
• 完全在答別的事情 → 使用者輸入和 description 偏差太大，可能是 description 關鍵字錯配。

第 2 步：手動指定 Skill 驗證

在對話框裡直接說「用 <你的 skill 名> 這個 skill 幫我處理 XXX」。如果手動指定後效果好，但自動不命中——問題在 description，不在正文。

第 3 步：看其它 Skill 搶了你的活

如果使用者的問題被別的 Skill 接走了（看 AI 答案的措辭像哪個內建 Skill 的風格），說明那個 Skill 的 description 比你寫得更具體。兩條出路：

• 寫明邊界：在你 Skill 的 description 裡加一句「不涉及 XX」，把容易混淆的場景甩出去；
• 改名字 + 關掉衝突 Skill：極端情況下把你 Skill 命名得和那個內建 Skill 同名，讓使用者版蓋掉內建版。

第 4 步：max_iterations 不夠

如果 AI 中途停了，沒給完整答案，看是不是工具呼叫次數被截斷了。把 max_iterations 調高（20-25）。

第 5 步：builtin_tools 缺漏

AI 答「我沒法查這個」——大機率是 builtin_tools 沒列對應工具。回 frontmatter 加上。

八、端到端實戰：寫一份《MySQL 慢查詢排障 Runbook》Skill

下面把一個真實的 Skill 從空白到上線走一遍。

場景

你的團隊每週都收到 MySQL 慢查詢告警。資深 DBA 排查動作是固定的：拉慢日誌 Top 10 → 看 EXPLAIN → 看 SHOW PROCESSLIST 有沒有鎖 → 看緩衝池命中率。但新人接到告警只會一句「重啟 mysql 試試」。

把 DBA 的排障動作寫成 Skill。

第 1 步：建目錄

mkdir -p mysql-slow-query-runbook/queries
cd mysql-slow-query-runbook

第 2 步：寫 SKILL.md

---
name: mysql-slow-query-runbook
description: MySQL 慢查询告警排障 Runbook。当用户问"MySQL 慢了 / 慢查询告警怎么处理 / DB 响应慢 /
qps 上升延迟变高 / lock 等待 / 缓冲池命中率"等时使用。覆盖：慢日志 Top 10、EXPLAIN 解读、
ProcessList 锁分析、innodb_buffer_pool 命中率检查。**不涉及**：MySQL 部署/初始化（转
`agent_deploy_guide`）、写新告警规则（转 `n9e-create-alert-rule`）。
max_iterations: 20
builtin_tools:
  - list_databases
  - list_tables
  - describe_table
  - query_log
  - search_active_alerts
  - get_alert_event_detail
  - read_file
metadata:
  owner: dba-team
  version: 1.0
---

# MySQL 慢查詢排障 Runbook

## 適用範圍

**進本 skill**：
- 使用者告警標籤裡有 `service=mysql` 或 `category=db` 的慢查詢/延遲告警
- 使用者原話：「MySQL 慢了」、「DB 響應變慢」、「慢查詢變多」、「鎖等待」、「qps 高但延遲也高」

**不進本 skill**：
- MySQL 安裝 / 初始化 → 轉 `agent_deploy_guide`
- 想新加一條告警規則 → 轉 `n9e-create-alert-rule`
- 非 MySQL 資料庫（PostgreSQL / TDengine 等）→ 直接答使用者目前 DB 類型不在本 Runbook 範圍

## 一句話原則

**先看現象，再看症狀，最後才看程式碼層 SQL。** 不要一上來就讓使用者 EXPLAIN——80% 的「慢」是池子和鎖。

## 排障四步法

### 第 1 步：拿現象 —— 用 `query_log` 拉慢日誌 Top 10

讀 `queries/top10_slow_queries.sql` 作為骨架，按使用者事件的時間視窗替換 `WHERE` 子句。
聚焦 `query_time > 1s` 的 query，按 `count * avg_query_time` 排序拿 Top 10。

如果 Top 10 集中在同一張表 → 大機率是該表索引/鎖問題；
分散在多表 → 偏向資源瓶頸（IO / CPU / 池子）。

### 第 2 步：看池子 —— `innodb_buffer_pool` 命中率

讀 `queries/buffer_pool_hit_rate.sql`，關注：

- `Innodb_buffer_pool_read_requests` / `Innodb_buffer_pool_reads` 比值
- 比值 < 99% → 池子設定過小或冷資料存取占比高
- 比值 > 99% 但慢查詢仍多 → 走第 3 步

### 第 3 步：看鎖 —— `SHOW PROCESSLIST`

讀 `queries/processlist.sql`，重點看：

- `State` 欄含 "Waiting for table metadata lock" / "Waiting for row lock" → DDL 或長交易卡住
- `Time` 欄超過 30s 的 `Sleep` 狀態連線 → 應用層連線池洩漏

### 第 4 步：到這裡仍未定位 —— 才讓使用者 EXPLAIN

對第 1 步拿到的 Top 1 慢 query 執行 `EXPLAIN`，看：
- `type=ALL` → 全表掃，缺索引；
- `type=index` 但 `rows` 很大 → 索引選擇性差，需要複合索引；
- `Extra=Using filesort/temporary` → ORDER BY / GROUP BY 無法走索引。

## 輸出格式

最終回答用 Markdown，結構：

## 結論
<一句話定位是哪一類問題：池子小 / 鎖等待 / 缺索引 / 全表掃 / 其他>

## 關鍵證據
- 慢日誌 Top 10：……
- 池子命中率：……
- 鎖/長交易：……
- EXPLAIN 關鍵欄位：……

## 建議動作
1-3 條具體可執行項，每條註明影響範圍與回滾方式

## 誤報風險
說明這個結論可能在什麼情況下不準

## 注意事項 / 紅線

1. **不要主動修改生產 my.cnf**——只能輸出建議改動 + 備份命令，讓使用者自己執行。
2. **不要建議直接 `kill <thread_id>`**——必須先解釋這個連線在做什麼，讓使用者判斷。
3. **慎用 `OPTIMIZE TABLE`**——大表會鎖表，要先評估是否在低峰期。

## 範例

### 使用者輸入
「剛才收到 MySQL 慢查詢告警，order_db 上 P99 延遲從 20ms 漲到 800ms」

### 工作流程
1. 第 1 步：`query_log` 拉 order_db 最近 10 分鐘慢日誌 Top 10
2. 發現 Top 1 是 `SELECT * FROM orders WHERE user_id=?` 跑了 9000 次，avg 600ms
3. 第 2 步：池子命中率 99.7%，排除池子問題
4. 第 4 步：`EXPLAIN` 看到 `type=ALL`，`rows=12000000`，缺 `user_id` 索引
5. 給出結論 + 加索引的 DDL + 線上 DDL 風險評估

第 3 步：寫輔助 SQL 檔案

queries/top10_slow_queries.sql：

SELECT
    DIGEST_TEXT AS query,
    COUNT_STAR AS exec_count,
    AVG_TIMER_WAIT/1e9 AS avg_ms,
    SUM_TIMER_WAIT/1e9 AS total_ms
FROM performance_schema.events_statements_summary_by_digest
WHERE LAST_SEEN > NOW() - INTERVAL 10 MINUTE
ORDER BY total_ms DESC
LIMIT 10;

queries/buffer_pool_hit_rate.sql：

SHOW STATUS WHERE Variable_name IN (
    'Innodb_buffer_pool_read_requests',
    'Innodb_buffer_pool_reads',
    'Innodb_buffer_pool_pages_total',
    'Innodb_buffer_pool_pages_free'
);

queries/processlist.sql：

SELECT id, user, host, db, command, time, state, info
FROM information_schema.processlist
WHERE time > 30
  AND command != 'Sleep'
ORDER BY time DESC;

第 4 步：打包

cd mysql-slow-query-runbook
zip -r ../mysql-slow-query-runbook.zip . -x "*.DS_Store"

或：

tar czf mysql-slow-query-runbook.tar.gz mysql-slow-query-runbook

第 5 步：上傳 + 測試

1. 進入 AI 設定 → Skill 管理，點 + → 本機上傳 Skill，選 mysql-slow-query-runbook.zip；

2. 上傳後 Skill 自動啟用；

3. 打開右上角 Nightingale AI，問一句應該命中的話：

   剛才收到一條 MySQL 慢查詢告警，order_db 延遲變高了，幫我看下
   

4. AI 應該按 Runbook 4 步法走，先拉慢日誌、看池子、看鎖，最後才讓你 EXPLAIN。

如果它沒按 Runbook 走，回頭看「七、除錯 Skill」一節排查。

第 6 步：分發到團隊

打磨滿意後，從 Skill 詳情頁下載匯出壓縮包，提交到團隊 Git 儲存庫的 nightingale-skills/ 目錄，作為團隊 Runbook 的數位資產。其它夜鶯實例直接上傳同一份包就能用。

九、Skill 來源：除了自己寫還能從哪拿

夜鶯的 Skill 包格式與 Anthropic Agent Skills 規範 完全相容——根目錄的 SKILL.md + YAML frontmatter 一致。這意味著：

• 直接用社群 Skill 庫——anthropics/skills 儲存庫裡很多開源 Skill 可以直接打包上傳。
• 複用 Claude / Cursor 等 AI 用戶端的 Skill——只要是 Anthropic Skills 格式，夜鶯都能識別。
• 跨實例遷移——開發實例打磨完下載匯出，生產實例直接上傳。

十、常見問題

Q1：Skill 太多會怎樣？

模型會從啟用列表裡選 1-2 個最相關的載入到上下文。Skill 數量本身沒硬上限，但每條都要讓模型讀 description 做匹配判斷——一般 30 條以內不會有明顯感知開銷。超過這個數建議：

• 同主題的 Skill 合併成一個，用 ## 子章節 分隔；
• 用 compatibility 欄位寫明先決條件，讓 AI 在條件不滿足時跳過；
• 關掉長期不用的 Skill（啟用開關）。

Q2：能不能讓某個 Skill「永遠」被載入？

可以——在 Agent 設定裡用 SkillConfig.SkillNames 顯式指定。但不推薦，會讓上下文變重影響所有問答。正確做法仍然是寫好 description，讓 AI 在該用的時候自動用。

Q3：輔助檔案能呼叫網路/執行指令稿嗎？

不能。輔助檔案就是被 AI read_file 讀出來當上下文的素材，沒有執行權。如果你要讓 Skill 真的「動手做事」，靠 builtin_tools 裡掛的工具（這些是夜鶯受控的內建工具）。

Q4：能不能在 Skill 裡加密敏感資訊（如 DB 密碼）？

不要。Skill 全文會進模型上下文，等於上傳給你接的 LLM。所有金鑰/密碼/Token 都要從工具層注入（夜鶯的工具本身用目前使用者的會話憑證），SKILL.md 裡只寫參數名占位。

Q5：寫 Skill 用什麼 IDE 體驗最好？

任何能編輯 Markdown + YAML 的編輯器都行。推薦 VSCode + YAML 外掛，能在 frontmatter 階段校驗語法。

關聯文件

• Skill 管理——基礎概念與產品操作
• 內建 Skill 一覽——19 個內建 Skill 是最好的寫法參考
• LLM 管理——Skill 跑起來需要的底層模型
• 夜鶯 AI 整體介紹——從產品視角理解 Skill 在整套 AI 能力裡的位置
• Anthropic Agent Skills 規範——Skill 包格式參考
• anthropics/skills——社群 Skill 儲存庫