Claude Code 自定義斜槓命令與 Skill 實戰：從零寫一個「生成更新日誌」的 /release-notes，含傳參、預執行命令和調試

本文根據 Claude Code 官方文檔《Extend Claude with skills》《Best practices for Claude Code》整理，資料核對於 2026-11-05。配圖為本站整理的示意圖，不是介面截圖。本站（bigolab.com）不是 Anthropic 官方網站。

適用於誰

• 已經知道 Skill 是什麼，但沒有真正寫過一個的人；
• 總在聊天裏重複粘貼同一段指令（比如「按這個格式寫更新日誌」）的人；
• 想知道自定義斜槓命令和 Skill 到底是什麼關係的人。

概念和字段規範站內已有文章：/guides/skill-md-format-spec-how-to-write 講格式，/guides/skill-directory-structure-scripts-references 講目錄，/guides/claude-code-skills-directory-location-priority 講放哪裏、誰優先。本文只做一件事：把一個完整例子從頭寫出來。

結論先說

1. 自定義命令和 Skill 現在是一回事。 官方說：.claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 都會創建 /deploy，舊的 commands 文件繼續有效；Skill 多了一個放支持文件的目錄、控制誰能觸發的字段，以及讓 Claude 在相關時自動加載的能力。
2. 什麼時候該寫。 官方的說法：當你總是把同一段指令、檢查清單或多步流程粘貼進對話，或者 CLAUDE.md 裏某一節已經變成「流程」而不是「事實」時，就寫一個 Skill。它的正文只在使用時才加載，平時幾乎不占上下文。
3. 有副作用或要自己掌握時機的流程，加 disable-model-invocation: true，讓它只能由你輸入 /名字 觸發，Claude 不會自己決定運行。
4. 預執行命令（感嘆號加反引號）會在 Claude 看到內容之前先運行，把輸出直接塞進提示詞；但它不會彈權限提示，沒被允許就會讓整個調用中止，所以要用 allowed-tools 預授權。
5. 改了 SKILL.md 當前會話就能生效，不用重啟，除非你新建了一個此前不存在的頂層 skills 目錄，那時用 /reload-skills。

圖：本站根據 Claude Code 官方文檔：Skills 整理的示意圖

我們要做的東西

目標：在項目裏輸入 /release-notes v1.2.0，Claude 讀出 v1.2.0 以來的提交，按「新功能、修復、其他」寫成面向用戶的更新日誌，只輸出給你看，不改任何文件。

選它做例子，是因為它剛好用到官方 Skill 的幾個核心能力，又足夠小。

第一步：建目錄和 SKILL.md

放哪裏？官方列了幾個位置：個人技能在 ~/.claude/skills/<技能名>/SKILL.md，所有項目可用；項目技能在 .claude/skills/<技能名>/SKILL.md，提交進倉庫全隊共享。更新日誌是項目相關的，我們放項目裏：

bash
mkdir -p .claude/skills/release-notes

在裏面建 SKILL.md：

text
---
name: release-notes
description: 根據 git 提交記錄寫面向用戶的更新日誌。當用戶要寫 release notes、更新日誌、changelog，或想知道上個版本以來改了什麼時使用。
argument-hint: "[上一個版本的標籤，例如 v1.2.0]"
disable-model-invocation: true
allowed-tools: Bash(git log *) Bash(git tag *)
---

## 現有版本標籤（按時間倒序）

!`git tag --sort=-creatordate`

## 任務

上一個版本：$ARGUMENTS（如果沒有給，就取上面列表裏的第一個；列表為空就告訴我並停止）。

1. 運行 `git log <上一個版本>..HEAD --oneline --no-merges`，讀出這之後的所有提交。
2. 按 [template.md](template.md) 的格式，把提交歸類為「新功能」「修復」「其他」，用面向用戶的語言改寫，不要照抄提交資訊。
3. 不確定歸類的提交，放到「待確認」並說明原因，不要猜。
4. 只在對話裏輸出結果，不要修改或創建任何文件。

逐段說明（對照官方文檔）：

• description：官方說它幫助 Claude 判斷何時用這個技能，要把關鍵用途放前面，寫進用戶會自然說的詞。
• argument-hint：輸入 / 後在自動補全裏提示該給什麼參數。
• disable-model-invocation: true：不讓 Claude 自動調用。官方舉的例子是 /commit、/deploy 這類你要自己掌握時機的流程。
• allowed-tools：官方說它讓 Claude 在這次調用期間使用列出的工具時不需要再詢問，下一條消息發出後失效。這裏同時是預執行命令能運行的前提。
• ! 加反引號的行：官方說它會在內容發給 Claude 前運行命令，用輸出替換這一行。要求 ! 在行首或空白之後。
• $ARGUMENTS：你在命令後面輸入的文字。官方還提供按位置取的 $0、$1。

第二步：加一個支持文件

官方說技能目錄裏可以放多個文件，主文件只寫要點，詳細的參考材料按需加載。我們加一個 template.md，規定輸出格式：

text
# 更新日誌 {版本}

## 新功能
- 用一句話說明用戶能做什麼新事情

## 修復
- 用一句話說明修好了什麼問題

## 其他
- 內部改動、依賴更新等，沒有就省略

## 待確認
- 提交編號：無法判斷類別的原因

注意 SKILL.md 裏要引用這個文件並說明什麼時候讀，官方也是這樣要求的，Claude 才知道它的存在。

第三步：試運行

在項目目錄裏啟動 claude，輸入：

text
/release-notes v1.2.0

第一次可能會問你是否允許運行 git log，選擇允許即可。如果出現 Shell command failed 之類的中止，官方的原因說明是：預執行命令失敗，或權限檢查不是「允許」，整個技能調用都會中止。排查辦法：看 allowed-tools 是否包含該命令，命令本身能否在終端裏單獨運行。

第四步：讓 Claude 幫你寫、幫你改

提示詞 1：讓 Claude 起草 SKILL.md

text
請幫我在 .claude/skills/release-notes/ 下創建一個技能：
目標：/release-notes <上一個版本標籤> 讀取該標籤以來的 git 提交，寫成面向用戶的更新日誌，只輸出不改文件。
要求：1）只能由我手動觸發；2）用預執行命令列出現有 tag；3）預授權 git log 和 git tag；4）輸出格式放在同目錄的 template.md；5）description 裏寫上中英文觸發詞。
寫完後告訴我每個 frontmatter 字段的作用。

提示詞 2：用真實輸出迭代

text
這次 /release-notes 的輸出有幾個問題：【把重複的提交合並了 / 把內部改動寫進了「新功能」/ 語氣太技術化】。
請修改 SKILL.md 和 template.md：補充歸類規則和語氣要求，並加兩個「好的寫法 / 壞的寫法」例子。改完用 git diff 給我看，然後我重新運行。

官方說，技能內容在調用後會作為一條消息留在對話裏，之後不會被重新讀取，所以要把「整個任務期間都應遵守」的規則寫成常駐指令。對話被壓縮後，可能只保留技能內容的開頭，把最重要的規則放在最前面。

提示詞 3：改善觸發描述（適用於允許自動觸發的技能）

text
請檢查這個技能的 description，看當我說「幫我整理一下這次發版改了什麼」「寫個 changelog」時能不能觸發。給出三種改進寫法，說明每種的優缺點，不要直接改文件。

本例設定了 disable-model-invocation，不會自動觸發，這條只用於以後你寫允許自動觸發的技能。

圖：本站根據官方文檔整理的示意圖

調試清單（官方「Troubleshooting」）

• 技能沒有觸發：看 description 是否含有用戶會說的詞；問 Claude「有哪些技能可用」確認它被識別；直接用 /名字 調用；若 /名字 也不認，檢查名字裏有沒有特殊字符。
• YAML 寫錯：官方說格式錯誤時技能仍會加載，但元數據為空，所以 /名字 能用、自動匹配卻不行；用 claude --debug 看解析錯誤，或運行 claude plugin validate .claude/skills 檢查（需要較新的版本，官方寫明為 v2.1.233 及以後）。
• Claude 後來不照着做了：必須每次都發生的規則，改用 Hook，見 /guides/claude-code-hooks；需要判斷的規則，改成覆蓋全任務的措辭。
• 團隊共享：項目技能提交進倉庫即可共享。注意官方提醒：技能裏的 allowed-tools 會直接生效，所以審查倉庫裏的技能再運行。

怎麼選：Skill、Hook、MCP、子智能體

一句話區分：Skill 是「按需加載的做事流程」，Hook 是「每次必定執行的規則」，MCP 是「接外部系統」，子智能體是「隔離上下文的助手」。詳細對比見 /guides/skill-vs-mcp-vs-subagent-vs-hook，舊式的自定義命令速查見 /guides/claude-code-slash-commands。

常見問題

Q：我已經有 .claude/commands/xxx.md，要遷移嗎？

不用。官方說它們繼續有效；同名時 skill 優先。新寫的建議用 skill 格式。

Q：Windows 上預執行命令能用嗎？

官方說明預執行命令通過 Bash 工具或 PowerShell 工具運行，沒有 Git Bash 時用 PowerShell 工具；只有在 frontmatter 裏寫死 shell: bash 而電腦上沒有 Git Bash 時才會失敗。

訂閱和額度

Skill 的正文只在調用時占上下文，比常駐在 CLAUDE.md 裏省。訂閱選擇見 /chongzhi/claude-code，價格和額度以官方頁面當前顯示為準。

相關教學

• /guides/claude-skills：Skills 是什麼、怎麼裝
• /guides/claude-code-slash-commands：斜槓命令速查
• /guides/claude-code-hooks-run-tests-before-commit：Hooks 實戰：提交前跑測試

參考資料

• Claude Code 文檔：Extend Claude with skills — https://code.claude.com/docs/en/skills
• Claude Code 文檔：Best practices for Claude Code — https://code.claude.com/docs/en/best-practices