Skills 实战：从斜杠命令到渐进披露

一句话定位：Skill 是装流程与领域知识的「按需加载包」——名字和描述常驻上下文，正文翻开才载入；本文讲 SKILL.md（技能的主文件）怎么写、何时该写、触发不可靠怎么调。前置：CLAUDE.md 与记忆系统——知道手册（常驻指令）与笔记（自动记忆）各装什么；Claude Code 全景与日常使用——先认识这套产品本身。

先从每次都要重新讲流程说起

你有一套固定的发版流程：先跑测试、再更新版本号、打 tag、推送、盯部署日志。每次让 Claude Code 协助，你都得把这五步重新描述一遍——它执行得很好，但下次会话又归零。

把流程写进 CLAUDE.md？它从此每个会话常驻——可你一天只用三次发版流程，却要为它常付二十四小时的上下文租金。贴在对话里？下次会话就丢。让它自己「记住」？流程这种多步骤操作，记忆笔记记不牢细节。流程类知识，需要一个「平时收着、用时取出」的载体。

什么样的载体能装下一套完整流程、平时不占上下文、用的时候还能一键展开？

这就是 Skill：一个目录、一份 SKILL.md——名字与描述常驻在「技能清单」里，正文在触发的瞬间才载入，还能挂 supporting files 按需取。旧版 Claude Code 的自定义斜杠命令（.claude/commands/ 下的 md 文件）已并入这套机制：两种文件形态等价，旧文件继续可用。先看一张 Skill 的生命周期图：

图：Skill 生命周期——①清单常驻 ②触发 ③载入执行 ④支撑文件按需；上下文预算主要花在触发之后

渐进拆解：一张菜谱卡片

类比：Skill 是卡片盒里的一张菜谱卡。封面写着菜名和一句「什么时候做这道菜」（描述，常驻）；你（或 Claude）翻到某张卡的瞬间，做法正文才算「上桌」（载入执行）；卡片背面和夹页还有备料清单与火候表（支撑文件），做到哪步翻哪页。卡片盒本身（技能清单）永远不厚——这正是渐进披露：先用一句话描述决定翻不翻，翻开了才付正文的预算。

预算视角看，这是把「人找知识」的成本，从「每次都带在身上」换成「用到才翻出来」——不过翻开的卡片会一直摊在桌上：正文载入后会驻留后续对话（自动压缩时按配额回挂），长篇技能照样是持续成本。

大白话：CLAUDE.md 是工牌，天天戴着，所以只能刻短话；Skill 是工具柜里的分格盒，格子上贴标签（描述），开格（触发）才取工具（正文）。工牌刻不下操作手册，分格盒也不该拿来做工牌。

技术定义：Skill 是一个目录，含一份 SKILL.md——顶部 YAML frontmatter 声明行为，下面 markdown 正文是触发后注入的指令；它遵循 Agent Skills 开放标准，Claude Code 在标准之上扩展了触发控制与子代理执行等字段。常用 frontmatter 一览：

字段	作用
`description` / `when_to_use`	自动触发的匹配依据，合计在清单中截断于 1536 字符
`paths`	路径匹配才自动触发
`disable-model-invocation` / `user-invocable`	触发权控制的一对开关
`allowed-tools` / `disallowed-tools`	技能运行回合内的工具授权与禁用
`context: fork` / `agent`	转入子代理执行
`argument-hint` / 正文 `$ARGUMENTS`	参数提示与参数替换

目录里除 SKILL.md 外都可放支撑文件，正文按需引用。旧斜杠命令文件（.claude/commands/*.md）与此机制合并：同名时技能优先，旧文件继续可用。

Skill 与 CLAUDE.md 的分工

判据一句话：每个会话都该知道的事实进 CLAUDE.md，成套的流程与专题知识进 Skill。

载体	预算特征	适合放
CLAUDE.md	常驻，每条规则每场会话都付预算	构建命令、项目约定、「永远要 X」级短事实
Skill	清单里只占一行描述，正文触发才载入	「发版五步」「代码评审清单」「本仓库 API 设计模式」这类成块内容

官方文档给的迁移信号很明确：CLAUDE.md 里的条目如果是一套多步骤流程，或者只跟一部分工作相关，就该搬去 Skill（或路径作用域规则）。

存放位置与命名

四级外加一批官方自带：

企业：IT 下发。
个人：~/.claude/skills/，对你的所有项目生效。
项目：.claude/skills/，随 git 共享。
插件：自带 插件名: 命名空间。

同名冲突按级解析——企业压个人、个人压项目。Claude Code 出厂预装的技能（如代码评审）也可被覆盖，但官方别名除外：覆盖 /code-review 后，别名 /review 仍指向原技能。工作目录下层还有子包的 .claude/skills/ 时，按目录限定名区分（apps/web:deploy），Claude 会根据当前在动的文件挑合适的变体。

两型内容，写法不同

类型	装什么	进入方式	写法追求
知识型	参考知识——如本仓库的 API 设计模式、领域术语表	自动触发	「查得到」：正文按主题分节，条目可独立阅读
任务型	操作流程——发版、提交、部署这类有先后步骤的动作	`/名字` 手动	「跟着走不错」：带检查点的步骤清单，每步可验证、失败即停的闸口写明

两型别混装——一张卡片既当速查表又当操作手册，两头都不好用。

触发机制与控制开关

自动触发靠 description——Claude 拿「技能清单」与你正在做的事做匹配，所以描述要把关键使用场景写在前头（清单里描述加触发说明合计截断于 1536 字符）；when_to_use 字段可补充触发短语；paths 字段让技能只在操作匹配路径的文件时自动触发。

控制权两个开关：

disable-model-invocation: true：把技能收归手动，只认 /名字，杜绝误触发。
user-invocable: false：反向——只许 Claude 自动用，菜单里不出现。

任务型技能常配前者，知识型常配后者或 paths。

与 Subagent 的配合

frontmatter 里一行 context: fork，这个技能就在独立的子代理上下文里运行——主对话只收结论，过程不占主上下文；agent 字段可指定用哪类子代理，background: true（默认）让长任务后台跑。

注意它同样是空白启动：SKILL.md 正文就是驱动这个子代理的任务提示，它读不到你的对话历史（技能 fork 不享受会话级 fork 的继承豁免，后台运行时工具面还会收窄）——要「带着当前对话整个转交」的会话级 fork（继承完整上下文）是另一种机制，见 Subagent 与并行工作流。这也正好接上 A2A 篇的边界：fork 出来的仍是同一个 harness（承载 Agent 主循环的运行时外壳）内部编排，不是跨信任域的协议协作。

动手：五分钟做一个 /deploy 技能

两步（# 后是注解；目录与文件都真实可建）：

mkdir -p .claude/skills/deploy        # 目录名就是命令名：/deploy
cat > .claude/skills/deploy/SKILL.md <<'EOF'
---
description: 按发版清单发布应用。Use when the user asks to deploy, release, or ship.
disable-model-invocation: true
---
# 发版流程
1. npm test 全绿；失败即停，禁止带病发布
2. 更新 package.json 版本号并写入 CHANGELOG.md
3. git tag "v$ARGUMENTS" 并推送标签
4. 盯部署日志至出现 "ready"，超时 5 分钟即回报
EOF

frontmatter 里再加一行 argument-hint: [版本号]，补全列表就会提示参数形态。回会话输入 /deploy v1.4.2，$ARGUMENTS 会被替换成参数（正文没写占位符时，参数会以 ARGUMENTS: 追加到末尾）；disable-model-invocation 保证它只在你喊的时候跑——发版这种事不该被自动脑补。

调试与核查三件套（/memory 看不到技能——它不是记忆）：

直接输入 /deploy，看是否出现在补全列表。
改了描述后开新会话，验证自动触发。
/context 里确认正文只在触发后出现。

知识型只需换个写法：把 frontmatter 换成 description: 本仓库 API 设计模式速查 加 paths: src/api/**，正文写模式清单——只在碰 API 文件时自动出现，平时零占用。

边界与取舍：卡片盒不是越多越好

什么时候不值得写 Skill。 一次性操作写对话里就行；每个会话都要的短事实写 CLAUDE.md；「发版五步」这种成套流程才是 Skill 的主场。反向信号：你的 CLAUDE.md 里出现了编号步骤，或者某段知识只服务一个目录——按官方迁移判据，它们该搬走了。

触发不可靠的调试路径。

不自动触发，按序三查：描述有没有把关键场景写清（「总结未提交改动」比「处理 git」好命中）→ 场景词是否该进 when_to_use → 是否该加 paths 限定（越窄越准）；误触发则反向三招：收紧描述、加 paths、disable-model-invocation: true 收归手动。
「装了却找不到」查名字：同名技能被上级覆盖（企业压个人、个人压项目），或嵌套技能要写限定名——用补全列表看它到底以什么名字在场。

整条调试路画成一张图：

图：触发调试树——不触发查描述，误触发收权限，找不到查名字；每支内自上而下按成本试

需要确定性拦截（不靠模型判断）时，那不是 Skill 的活，是 Hooks 的地盘。三方各管一段：Hooks 管物理关卡（事件到了必须执行），路径规则管「碰这些文件时的常驻提醒」，Skill 管「成套流程的按需展开」——常驻、路径常驻、按需，预算特征不同，别互相顶班。

自测前留一个判断钩子：如果你发现自己在给 Skill 正文越写越长——渐进披露允许你把细节拆进支撑文件，正文只留主干与入口。知识型技能尤其该这样做：正文当目录用，具体条目一个文件一条，Claude 按需去读——和 auto memory 的「索引薄、细节下沉」是同一套预算哲学。

自测

合上文章先自己答，再展开对照：

什么时候值得写一个 Skill，什么时候往 CLAUDE.md 堆规则就够？

判据是「每会话都要」与「成块」两条。每个会话都该生效的短事实与规则（构建命令、项目约定）进 CLAUDE.md——它常驻，也正因为常驻，条目必须短。成套的多步骤流程（发版、评审清单）与专题领域知识（API 模式速查）值得写 Skill——清单里只占一行描述，正文按需载入，还有手动斜杠调用与参数替换这些产品能力。官方迁移信号：CLAUDE.md 里出现多步骤流程或只跟部分工作相关的条目，就该搬去 Skill 或路径作用域规则。

触发不可靠（不触发/误触发）时，调试路径是什么？

不自动触发，按序查三处：description 是否把关键使用场景写在前头（自动匹配读的是它，合计截断于 1536 字符）；触发短语是否该补进 when_to_use；是否该加 paths 限定到特定路径——越窄越准。误触发，反向三招：收紧描述、加 paths、或设 disable-model-invocation: true 收归手动只认 / 名字。还有一类是「在场但名字不对」：同名冲突按企业压个人、个人压项目解析，嵌套技能用目录限定名——用输入框补全列表看它实际以什么名字在场。

参考与延伸

Claude Code 官方文档《Extend Claude with skills》：SKILL.md 结构、frontmatter 字段表、触发与命名冲突解析的原始出处 — code.claude.com/docs/en/skills
Agent Skills 开放标准（agentskills.io）：跨工具通用的技能格式规范，Claude Code 在其上做了触发控制等扩展 — agentskills.io

下一站：Hooks：事件驱动的确定性控制——技能管「怎么做」，Hooks 管「必须怎样」：把概率指令换成物理关卡。

学习舱 · 知识库