建立您的第一個技能

建立您的第一個技能 · 4 min

摘要逐字稿

本影片將逐步說明如何從零開始建立一個技能——一個可在您所有專案中使用的個人 PR 描述技能。您將確切看到如何建構 SKILL.md 檔案、測試它，並了解 Claude Code 如何發現並將技能與您的請求進行比對。本影片也涵蓋了當名稱發生衝突時，決定哪個技能勝出的優先順序階層。

重點整理

技能是一個包含 SKILL.md 檔案的目錄，該檔案在 frontmatter 中包含中繼資料（名稱、描述），下方則是指示內容
Claude 在啟動時僅載入技能名稱和描述，然後使用語意比對將傳入的請求與這些描述進行比對
當找到符合項目時，僅具有名稱、描述和指示的技能會在未經您詢問的情況下完整載入。如果某個技能預先核准了工具或新增了 hooks，Claude Code 可能會先徵求您的核准
名稱衝突的優先順序為：Enterprise → Personal → Project。外掛技能採用命名空間，因此會與同名技能一併載入
若要更新技能，請編輯其 SKILL.md。若要移除技能，請刪除其目錄。Claude Code 會在目前的工作階段中套用變更，無需重新啟動。如果 ~/.claude/skills 在此工作階段中是新建立的，請在每次變更後執行 /reload-skills

讓我們逐步說明如何從零開始建立一個技能，然後看看 Claude Code 在幕後實際上是如何載入並比對技能的。

建立技能

我們將建立一個個人技能，教導 Claude 以一致的格式撰寫 PR 描述。由於這是個人技能，它存放在您的家目錄中，並可在您所有的專案中運作。

首先，在 skills 資料夾內為您的技能建立一個目錄。目錄名稱應與您的技能名稱相符：

mkdir -p ~/.claude/skills/pr-description

然後在該目錄內建立一個 SKILL.md 檔案。該檔案分為兩個部分，以 frontmatter 的破折號分隔：

markdown

---
name: pr-description
description: Writes pull request descriptions. Use when creating a PR, writing a PR, or when the user asks to summarize changes for a pull request.
---

When writing a PR description:

1. Run `git diff main...HEAD` to see all changes on this branch
2. Write a description following this format:

## What
One sentence explaining what this PR does.

## Why
Brief context on why this change is needed

## Changes
- Bullet points of specific changes made
- Group related changes together
- Mention any files deleted or renamed

name（名稱）用於識別您的技能。description（描述）告訴 Claude 何時使用它——這就是比對的依據。第二組破折號之後的所有內容，都是技能啟用時 Claude 所遵循的指示。

pr-description 的 SKILL.md 在編輯器中開啟，旁邊是 commit-message、debugging 和 documentation 技能資料夾。

測試您的技能

Claude Code 會監看您的技能目錄，因此新技能在目前的工作階段中即可使用，無需重新啟動。如果 ~/.claude/skills 在工作階段開始時尚不存在，Claude Code 尚未對其進行監看，因此請立即執行 /reload-skills，並在之後每次變更後再次執行。您可以透過檢查可用技能清單來驗證您的技能是否可用。

Claude Code 可用技能輸出，包含「documentation」、「debugging」、pr-description 和 commit-message 等技能。

您應該會看到您的技能列在其中。若要測試它，請在某個分支上進行一些變更，並說類似「為我的變更撰寫 PR 描述」這樣的話。Claude 會表明它正在使用 PR description 技能，檢查您的差異內容，並依照您的範本撰寫描述——每次格式都相同。

技能比對的運作方式

當 Claude Code 啟動時，它會掃描多個位置以尋找技能，但僅載入名稱和描述，而非完整內容。這是一個重要的細節。

當您傳送請求時，Claude 會將您的訊息與所有可用技能的描述進行比對。舉例來說，「解釋這個函式的作用」會與描述為「以視覺化圖表解釋程式碼」的技能相符，因為其意圖有所重疊。

一旦找到符合項目，Claude 會讀取完整的 SKILL.md 檔案並遵循其指示。僅具有名稱、描述和指示的技能（例如 pr-description）會在未經詢問的情況下載入。如果某個技能預先核准了工具或新增了 hooks，Claude Code 可能會要求您先核准，這取決於您的權限模式。上方的影片和下方的圖片展示了 Claude Code v2.1.19 針對像 pr-description 這類技能所移除的核准步驟。

審查後端程式碼安全性問題與合規疏失的技能 frontmatter，以及「Use backend-review Skill?」。

技能優先順序

如果您複製了一個儲存庫，其中有一個技能與您的某個個人技能同名，那麼哪一個會勝出？這裡有一個明確的優先順序：

Enterprise（企業）——受管理的設定，優先順序最高
Personal（個人）——您的家目錄（~/.claude/skills）
Project（專案）——儲存庫內的 .claude/skills 目錄

這讓組織能夠透過企業技能強制執行標準，同時仍允許個人自訂。如果您的公司有一個企業「code-review」技能，而您建立了一個同名的個人「code-review」技能，則企業版本優先。來自已安裝外掛的技能不在此順序之內。它們採用 /plugin-name:skill-name 的命名空間，因此外掛技能和另一個同名技能都會載入。

為避免衝突，請使用具描述性的名稱。不要只用「review」，而是使用類似「frontend-review」或「backend-review」這樣的名稱。

更新與移除技能

若要更新技能，請編輯其 SKILL.md 檔案。若要移除技能，請刪除其目錄。Claude Code 會在目前的工作階段中套用變更，因此您無需重新啟動。如果您先前在此工作階段中因為 ~/.claude/skills 是新建立的而執行了 /reload-skills，請在每次變更後再次執行。

課程反思

在您的日常工作流程中，有哪一項任務是您現在就可以轉換成技能的？描述內容會是什麼樣子？
優先順序階層可能如何影響您團隊的技能管理策略？您會更依賴個人層級還是專案層級的技能？

接下來

在下一課中，您將學習進階設定選項，包括中繼資料欄位、使用 allowed-tools 預先核准工具，以及如何使用漸進式揭露和多檔案組織來建構較大型的技能。