技能作為機構知識 · AI 原生 SDLC 實戰手冊

技能是組織將其機構知識運作化的方式。這些指示是明確的、受版本控制的、廣泛應用的，並在政策變更時集中更新。一個基本原則是：為必須一致應用的機構知識撰寫技能；不要為屬於 CLAUDE.md 或提示的組件撰寫技能。

開始使用

先決條件：不需要任何條件。擁有 CLAUDE.md 會有幫助，因為它能將代理的工作知識保留在儲存庫中，但技能並不依賴它。
基礎設施：一項政策，有指定的負責人和書面的真實來源。

如何執行

選擇一項目前執行不一致的知識。這可以是安全標準、API 設計慣例或品牌規則。
將其寫成一個技能，即一個包含 SKILL.md 的資料夾，其前置資料（frontmatter）說明何時觸發，其內容說明該做什麼。工程師根據政策負責人的真實來源撰寫，並使用 Claude 協助。
將技能放在儲存庫的 .claude/skills/<name>/ 中，使其隨程式碼一起發布，或透過外掛程式在整個組織中分發。
測試技能是否觸發。要求 Claude 以不同方式執行相關任務，並確認每次都能載入該技能。
當政策變更時，修改技能，並讓政策負責人簽署核准該變更。
工程師在下一個工作階段會自動取得新版本。

它看起來是什麼樣子

.claude/skills/secure-api-review/SKILL.md：

markdown

---
name: secure-api-review
description: Apply the API security standard. Use whenever creating or
  modifying an external-facing endpoint, reviewing API code, or
  generating an OpenAPI spec.
---
# Secure API review
When you create or change an API endpoint:
1. Authentication: every endpoint requires the gateway JWT;
   no anonymous routes outside /health.
2. Input validation: validate request bodies against the OpenAPI
   schema and reject unknown fields.
3. Audit: every state-changing endpoint emits an audit event with
   actor, action, entity and timestamp.
4. Data classification: fields tagged pii in the schema must never
   appear in logs or error messages.
Run scripts/check-endpoints.sh and include its output in your summary.

治理考量

技能是一種控制，儘管是建議性的。它使 Claude 在撰寫程式碼時更有可能應用該政策，但沒有任何機制強制工作階段遵守它。必須始終成立的政策，需要在技能背後有某種確定性的機制，例如阻止該動作的掛鉤（hook），或在 PR 時重新檢查政策的審查流程。技能使違規變得罕見，而掛鉤則使違規幾乎不可能發生。掛鉤會在編輯時捕捉違規，而在拉取請求上進行的相同檢查，則會捕捉任何以其他方式進入分支的內容。技能的呼叫會記錄在工作階段追蹤中，政策負責人會像審查程式碼一樣審查技能變更。

如何衡量

領先指標：從政策負責人核准政策變更到更新後的技能合併所需的時間，取自技能資料夾上的 PR。
落後指標：引用該政策的 PR 審查發現，一旦技能在撰寫程式碼時應用該政策，這個數字應趨近於零。若發現未趨近於零，則表示技能未觸發，或其文字已偏離官方政策。

掛鉤作為建置時期的防護機制

技能是一種建議性控制，而掛鉤則是其背後的確定性層。Claude 的大多數動作是在實作期間進行的檔案編輯和 shell 命令，因此建置階段是掛鉤最常觸發的地方。

建置階段的掛鉤可以：

阻止對受保護路徑的編輯，例如生成的類別或凍結的套件
在檔案編輯後執行格式化工具和程式碼檢查工具，使偏差不會累積
將憑證排除在差異（diff）之外
支援任何政策必須無例外成立的技能

掛鉤會在每個符合條件的動作上執行，因此建置階段的掛鉤應該快速且限定於已變更的檔案。較重的檢查，例如完整的測試套件，應放在提交（commit）或 PR 階段。

這是本頁前面展示的 secure-api-review 技能第 4 條規則背後的掛鉤。該儲存庫屬於一家保險公司，其端點檔案位於 claims-api/routes/ 中。每次編輯這些檔案之一後，掛鉤會執行 scripts/check-endpoints.sh，這是技能已經指名的儲存庫根目錄下的腳本。當 OpenAPI 結構中標記為 pii 的欄位出現在日誌呼叫或引發的錯誤中時，該腳本會失敗。

該掛鉤已在 .claude/settings.json 中註冊。空的 args 清單使 Claude Code 直接執行該腳本，而不是透過 shell：

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/api-policy.sh",
            "args": [] }
        ]
      }
    ]
  }
}

掛鉤腳本 .claude/hooks/api-policy.sh：

bash

#!/bin/bash
# 以該技能實際執行的相同腳本，支援 secure-api-review 技能的規則 4。
file=$(jq -r '.tool_input.file_path')
case "$file" in
  "$CLAUDE_PROJECT_DIR"/claims-api/routes/*.py) ;;
  *) exit 0 ;;                                   # not an endpoint
esac
cd "$CLAUDE_PROJECT_DIR" || exit 2
if ! found=$(scripts/check-endpoints.sh "${file#"$CLAUDE_PROJECT_DIR"/}"); then
  echo "secure-api-review rule 4: a pii field reaches a log or an error message." >&2
  echo "$found" >&2
  exit 2
fi

在編輯之後執行的掛鉤無法撤銷該編輯，因此退出代碼 2 會將腳本的訊息呈現給 Claude，讓它能夠修正該行。在記錄客戶姓名的編輯之後，這是 Claude 從腳本看到的訊息：

text

secure-api-review rule 4: a pii field reaches a log or an error message.
claims-api/routes/status.py:10: policy_holder_name

當 shell 命令重寫檔案時，Edit|Write 掛鉤不會觸發。因此，相同的腳本也會作為每個拉取請求上的必要檢查執行：

yaml

name: API policy
on: pull_request
jobs:
  check-endpoints:          # a required check in branch protection
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: scripts/check-endpoints.sh claims-api/routes/*.py

要求人工核准的掛鉤，應歸屬於第 5 階段：部署中的關卡，因為在建置期間出現核准提示，會讓一個人重新回到所有並行執行工作階段的關鍵路徑上。

開始使用

如何執行

它看起來是什麼樣子

治理考量

如何衡量