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