Skills 怎么写：粘贴三次就该沉下来

同一段发布清单、评审口径、迁移步骤，你已经往对话框里贴了三次，就该做成 Skill。和常驻的 CLAUDE.md 不同：技能正文默认用到才加载，适合长流程。分工见 MCP、Skills、Hooks 怎么选 和 CLAUDE.md 别写成第二份 README。

旧式 .claude/commands/deploy.md 和新式 .claude/skills/deploy/SKILL.md 都会生成 /deploy。旧文件继续可用；新写建议用 skills，能带辅助文件，也能控制谁来触发。

放哪、怎么试

位置	路径	范围
个人	~/.claude/skills/<名>/SKILL.md	本机所有项目
项目	.claude/skills/<名>/SKILL.md	这个仓库，可提交
插件	插件内 skills/	插件启用处

目录名就是命令名。最小例子：

mkdir -p ~/.claude/skills/summarize-changes

---
description: 总结未提交改动并标风险。用户问改了什么、要写提交说明或看 diff 时用。
---

## Current changes

!`git diff HEAD`

## Instructions

用两三条概括上面的改动，再列出缺错误处理、硬编码、测试缺口等风险。diff 为空就说没有未提交改动。

!command`` 会在送进模型前跑命令，把输出嵌进正文。问「我改了什么」或敲 /summarize-changes 都能试。

description 决定会不会被自动叫起来。写具体场景，别写「处理文案」。单条描述加 when_to_use 在列表里大约截到 1536 字符，关键句放前面。

谁可以调用

默认你和模型都能调用。

• disable-model-invocation: true：只有你敲 /名。适合部署、发消息、带副作用的流程。
• user-invocable: false：只给模型当背景知识，不进 / 菜单。

---
name: deploy
description: 部署到生产环境
disable-model-invocation: true
---

按顺序部署 $ARGUMENTS：跑测试、构建、推目标、验证成功。

不想改文件时，用设置里的 skillOverrides：on / name-only / user-invocable-only / off。/skills 菜单里空格可切换。

常用 frontmatter

字段	作用
allowed-tools	本轮调用期间预批这些工具，下一条消息清空
disallowed-tools	本轮临时拿掉工具
context: fork	在子代理里跑；技能正文当任务提示
agent	fork 时用哪种子代理
model / effort	本轮模型或努力程度
paths	只在匹配文件时自动激活
arguments	命名位置参数，正文里 $name

项目技能的 allowed-tools 在信任工作区后才按项目规则生效；审查仓库里的技能时注意它能给自己开多大权限。$ARGUMENTS、$0、${CLAUDE_SKILL_DIR}、${CLAUDE_PROJECT_DIR} 可做替换。

辅助材料放同目录别的 md 或 scripts/，在 SKILL.md 里链过去，主文件尽量短。技能内容进对话后会跨轮保留；权限授予不会跨你的下一条消息。

和 CLAUDE.md、Hooks 别混

短事实、每次都要知道的约定 → CLAUDE.md。多步流程、偶尔才用 → Skill。一次都不能漏 → Hooks 或 permissions.deny。

发现技能太多占列表预算，跑 /skill-doctor 或 /doctor 看成本，低频的改成 name-only 或关掉。改个人 / 项目技能目录一般当前会话就能热更新；插件侧改 hooks / MCP 可能要 /reload-plugins。