incident-postmortem/
├── SKILL.md
├── assets/
│   └── template.md
└── reference/
    └── severity.md

---
name: incident-postmortem
description: 線上事故復(fù)盤報告生成。當(dāng)用戶提供事故時間線、影響范圍,或要求撰寫 postmortem / 事故報告 / 復(fù)盤時使用。
---

# 事故復(fù)盤報告生成

## 何時使用
用戶描述了一次線上事故并需要產(chǎn)出正式復(fù)盤文檔時。

## 步驟
1. 讀取 `assets/template.md` 作為唯一輸出骨架,**不得增刪任何一級標(biāo)題**。
2. 若用戶未提供嚴(yán)重等級,依據(jù) `reference/severity.md` 判定,并在報告中注明判定依據(jù)。
3. 按下列規(guī)則填寫:
   - **影響范圍**:必須量化(受影響用戶數(shù) / 請求數(shù) / 時長);無數(shù)據(jù)寫"待補充",禁止編造。
   - **時間線**:`HH:MM` 單調(diào)遞增,每行一個事件。
   - **改進項**:每條含負(fù)責(zé)人占位 `@owner` 與截止日期 `YYYY-MM-DD`,便于下游腳本抽取建單。
4. 輸出純 Markdown,不要整體包進代碼塊。

## 硬約束
- 不臆測未提供的數(shù)字。
- 一級標(biāo)題順序與模板完全一致(看板按標(biāo)題解析)。

# 事故復(fù)盤:<一句話標(biāo)題>

## 元信息
- 事故編號:INC-
- 嚴(yán)重等級:
- 發(fā)生時間:
- 恢復(fù)時間:
- 總時長:

## 影響范圍

## 時間線

## 根因分析
### 直接原因
### 根本原因

## 處置與恢復(fù)

## 改進項
| 措施 | 負(fù)責(zé)人 | 截止日期 | 狀態(tài) |
| ---- | ------ | -------- | ---- |

## 經(jīng)驗教訓(xùn)

# 嚴(yán)重等級判定

| 等級 | 判定標(biāo)準(zhǔn) |
| ---- | -------- |
| P0 | 核心功能全站不可用,或數(shù)據(jù)丟失/泄露 |
| P1 | 核心功能部分不可用,影響 >10% 用戶 |
| P2 | 非核心功能不可用,或有降級方案 |
| P3 | 輕微影響,無用戶可感知中斷 |

判定就高不就低:同時命中多個等級時取最嚴(yán)重者。

sla-calculator/
├── SKILL.md
└── scripts/
    └── sla.py

---
name: sla-calculator
description: 根據(jù)事故記錄計算 SLA 可用性、停機時長與錯誤預(yù)算。當(dāng)用戶提供停機 CSV,或詢問月度可用性、錯誤預(yù)算是否耗盡時使用。
allowed-tools: Bash(python3 *), Read
---

# SLA 可用性計算

## 關(guān)鍵原則
**所有數(shù)值計算必須調(diào)用腳本完成,禁止在對話中心算。**

## 步驟
1. 確認(rèn)停機記錄為 CSV,列:`start,end`(ISO8601)。
2. 執(zhí)行:
   `python3 scripts/sla.py --file <路徑> --target 99.9 --month 2026-07`
3. 將腳本輸出的 JSON 轉(zhuǎn)述為結(jié)論,并明確指出錯誤預(yù)算是否已耗盡。
4. **不要修改腳本輸出的任何數(shù)字。**

#!/usr/bin/env python3
"""從停機記錄計算月度可用性與錯誤預(yù)算。計算集中于此以保證可復(fù)現(xiàn)。"""
import argparse, csv, json, calendar
from datetime import datetime

def parse(ts):
    return datetime.fromisoformat(ts.replace("Z", "+00:00"))

def month_seconds(month):
    year, mon = map(int, month.split("-"))
    return calendar.monthrange(year, mon)[1] * 24 * 3600

def main():
    p = argparse.ArgumentParser()
    p.add_argument("--file", required=True)
    p.add_argument("--target", type=float, required=True)  # SLA 目標(biāo) %,如 99.9
    p.add_argument("--month", required=True)                # YYYY-MM
    a = p.parse_args()

    total = month_seconds(a.month)
    down = 0
    with open(a.file, newline="", encoding="utf-8") as f:
        for row in csv.DictReader(f):
            down += (parse(row["end"]) - parse(row["start"])).total_seconds()

    uptime = (total - down) / total * 100
    allowed = total * (100 - a.target) / 100          # 允許停機秒數(shù)
    budget_used = down / allowed * 100 if allowed else 0

    print(json.dumps({
        "month": a.month,
        "uptime_pct": round(uptime, 4),
        "target_pct": a.target,
        "downtime_seconds": int(down),
        "downtime_human": f"{int(down)//3600}h{int(down)%3600//60}m",
        "error_budget_used_pct": round(budget_used, 2),
        "budget_exhausted": budget_used >= 100,
        "meets_sla": uptime >= a.target,
    }, ensure_ascii=False, indent=2))

if __name__ == "__main__":
    main()

rest-api-guide/
├── SKILL.md
└── reference/
    ├── pagination.md
    ├── errors.md
    └── auth.md

---
name: rest-api-guide
description: 團隊 REST API 設(shè)計規(guī)范。設(shè)計/評審 HTTP 接口、命名端點、選狀態(tài)碼,或問及 API 版本、分頁、錯誤格式、鑒權(quán)時使用。
---

# REST API 設(shè)計規(guī)范

## 核心規(guī)則(高頻,直接遵循)
- **資源命名**:復(fù)數(shù)名詞 + kebab-case,如 `/user-groups`;不出現(xiàn)動詞。
- **層級**:`/orders/{id}/items`,嵌套不超過兩層。
- **方法語義**:GET 只讀且冪等;POST 創(chuàng)建;PUT 全量替換;PATCH 局部更新;DELETE 刪除。
- **狀態(tài)碼**:200/201/204 · 400/401/403/404/409/422 · 500。
- **版本**:URL 前綴 `/v1/`,僅破壞性變更升版本。

## 何時查閱引用文件(低頻,按需加載)
- 設(shè)計**分頁 / 游標(biāo)** → 讀 `reference/pagination.md`
- 定義**錯誤響應(yīng)體** → 讀 `reference/errors.md`
- 涉及**鑒權(quán) / Token / 權(quán)限** → 讀 `reference/auth.md`

> 這三個主題互斥且少同時出現(xiàn),故不內(nèi)聯(lián)——既省 token,也避免規(guī)則相互干擾。

# 錯誤響應(yīng)體規(guī)范

統(tǒng)一使用 RFC 9457 (Problem Details):

```json
{
  "type": "https://api.example.com/errors/out-of-stock",
  "title": "庫存不足",
  "status": 409,
  "detail": "商品 SKU-123 當(dāng)前庫存為 0",
  "instance": "/orders/8821"
}
```

- `type` 為可跳轉(zhuǎn)錯誤文檔 URL;無專屬文檔時用 `about:blank`。
- 校驗錯誤(422)追加 `errors` 數(shù)組,每項含 `field` 與 `message`。
- 絕不在 `detail` 泄露堆棧、SQL 或內(nèi)部主機名。

# 分頁規(guī)范

默認(rèn)游標(biāo)分頁,大數(shù)據(jù)集禁用 offset。

請求:`GET /orders?limit=50&cursor=eyJpZCI6MTAwfQ`

```json
{
  "data": [ ... ],
  "page": { "next_cursor": "eyJpZCI6MTUwfQ", "has_more": true }
}
```

- `limit` 默認(rèn) 50,上限 200,越界返回 400。
- `next_cursor` 為空表示已到末頁。

# 鑒權(quán)規(guī)范
- 傳輸:僅 HTTPS;Token 放 `Authorization: Bearer <jwt>`。
- 過期:access token ≤ 15min,配合 refresh token。
- 401 = 未認(rèn)證 / Token 失效;403 = 已認(rèn)證但無權(quán)限。二者不可混用。

security-audit/
├── SKILL.md
└── reference/
    └── checklist.md

---
name: security-audit
description: 只讀代碼庫安全審計。當(dāng)用戶要求安全體檢、掃描硬編碼密鑰、檢查危險調(diào)用或上線前安全審查時使用。
allowed-tools: Read, Grep, Glob
---

# 只讀安全審計

## 能力邊界(重要)
本 Skill **只讀**。frontmatter 未授予任何寫入/執(zhí)行工具:
- 只發(fā)現(xiàn)、只報告,**絕不修改文件**。
- 如需修復(fù),輸出建議交由人工或另一個具備寫權(quán)限的流程處理。

## 步驟
1. 依據(jù) `reference/checklist.md` 逐項用 Grep / Glob 掃描。
2. 每條發(fā)現(xiàn)給出:`文件:行號`、風(fēng)險等級、證據(jù)片段、修復(fù)建議。
3. 輸出風(fēng)險清單表,按嚴(yán)重度降序;無發(fā)現(xiàn)則明確寫"未發(fā)現(xiàn)"。

## CLI 與 SDK 邊界提示
`allowed-tools` 僅在 Claude Code CLI 生效。若本 Skill 經(jīng) Agent SDK 調(diào)用,
只讀約束不由 frontmatter 強制,須在 agent 的 tools 白名單或權(quán)限系統(tǒng)中另行限定。

# 安全審計清單

## 密鑰與憑證
- 硬編碼密鑰:形如 `key/secret/password/token = "<長字符串>"` 的賦值
- 私鑰文件頭:出現(xiàn) PRIVATE KEY 文件頭
- 云訪問密鑰:符合各云廠商 Access Key 格式的字符串

## 危險調(diào)用
- 命令注入:拼接用戶輸入調(diào)用系統(tǒng)命令 / 開啟 shell 執(zhí)行
- 不安全反序列化:對不可信數(shù)據(jù)做反序列化
- SQL 拼接:用字符串拼接構(gòu)造 SQL 而非參數(shù)化查詢

## 配置
- 生產(chǎn)開調(diào)試:生產(chǎn)配置中調(diào)試開關(guān)為開
- 過寬 CORS:允許來源為通配符

## 風(fēng)險等級
Critical=可直接遠(yuǎn)程利用 · High=需前置條件 · Medium=縱深防御問題 · Low=最佳實踐偏差