| 版本 | 内容 | 时间 | | ---- | ---- | ------------------- | | V1 | 新建 | 2026-07-18 10:52:19 | ## 引入对于经常重复执行固定流程的程序员来说，把这些操作封装成 Skill 是非常自然的事情。例如，提交代码通常不是简单执行一句 `git commit`，而是一系列固定步骤： ``` 检查当前 git 状态 → 查看修改内容 → 确认提交范围 → 创建 commit message → 完成提交 ``` 如果每次都手动告诉 Claude：“帮我检查 git 状态，然后提交代码，提交信息是 fix login bug。”不仅重复，而且容易遗漏步骤。通过创建一个 commit Skill，可以把这套流程固定下来。这就是任务型 Skill 的价值：**它把重复出现的对话模式和执行流程，封装成一个可以反复调用的能力**。以后面对类似任务，用户不需要重新描述“怎么做”，只需要表达“要完成什么目标”。 ## Skills 和 Command 的关系在早期版本的 Claude Code 中，Commands 和 Skills 是两个相对独立的机制。Commands 主要用于创建自定义 Slash Command，把高频操作封装成一个快捷入口。随着 Claude Code 的发展，Skills 提供了一种更完整的能力封装方式。相比传统 Command，Skill 不只是保存一段 Prompt，而是一个完整的任务能力模块。 SKill 的优势是它支持： - 多文件组织 - 渐进式加载 - 更适合长期维护 | 维度 | Commands | Skills | | -------- | ------------------------------- | ------------------------------------------------------------ | | 定位 | 用户主动触发的快捷入口 | 可复用的任务能力模块 | | 触发方式 | 用户输入 `/command` | Claude 根据任务描述发现并加载，也可以被显式调用 | | 存放位置 | `.claude/commands/` | `.claude/skills//` | | 主文件 | 任意 `.md` 文件 | 固定 `SKILL.md` | | 触发机制 | Slash Command 名称精确匹配 | 根据 Skill 的 `name` 和 `description` 进行任务匹配 | | 内容形式 | Prompt 模板 | 能力定义 + 工作流程 + 辅助资源 | | 资源支持 | 通常单个 Markdown 文件 | 支持 scripts、references、templates 等辅助目录 | | 加载方式 | 调用 Command 时加载对应内容 | 先发现 Skill 描述，需要时加载完整 Skill 内容 | | 典型用途 | 高频固定操作 | 复杂任务、专业流程、领域知识 | | 适合场景 | `/commit`、`/review`、`/deploy` | `security-review`、`bug-investigation`、`architecture-analysis` | ## 任务 skill 的核心机制在之前的内容中，我们介绍过两类工作方式： - **参考型**：提供知识和规则，让 Claude 在需要时调用； - **任务型**：执行明确动作，需要用户主动触发。 | 维度 | 参考型 Skill | 任务型 Skill | | -------------------------- | ------------------------ | --------------------------------- | | Claude 自动调用 | 可以 | 不会 | | 用户主动调用 | 可以 | 可以 | | `disable-model-invocation` | 默认不设置 | 一般设置为 `true` | | description 作用 | 帮助 Claude 判断使用时机 | 描述 Skill 用途，供用户识别和调用 | | 典型场景 | 规范、知识、流程指导 | 部署、提交、迁移等动作 | | 风险特点 | 通常低风险 | 通常涉及实际操作 | 如何判断是否应该禁止自动调用？可以问自己：如果 Claude 在没有明确请求的情况下自动执行这个 Skill，最坏情况是什么？如果风险较高，例如： - 发布生产环境； - 删除资源； - 修改数据库； - 执行不可逆操作；建议使用下面的配置要求用户主动确认。 ``` disable-model-invocation: true ``` ## 任务型 SKILL 的核心配置 ### 参数传递机制 #### 基本传参方式手动和 Claude 调用 SKILL 时都可以传参数，通过 `$ARGUMENTS` 变量获取传入的内容。 ```markdown --- name: fix-issue description: 修复 GitHub issue argument-hint: 问题编号 disable-model-invocation: true --- 按照编码规范修复 GitHub issue $ARGUMENTS 1. 读取 issue 描述 2. 理解需求 3. 实现修复 4. 编写测试 5. 提交代码 ``` 调用：`/fix-issue 123` 实际替换后： ```mark 按照编码规范修复 GitHub issue 123 1. 读取 issue 描述 ... ``` #### 没写 `$ARGUMENTS` 的兜底行为如果 SKILL 正文里没写 `$ARGUMENTS` 变量，你传了参数也不会丢 —— 系统会自动在 SKILL 内容末尾追加 `ARGUMENTS: <你输入的内容>`，保证 Claude 能看到。 --- #### SKILL堆叠调用（v2.1.196+） **功能**：一条消息开头可以连续写多个SKILL命令，一次性加载多个SKILL。 **示例**： ``` /code-review /fix-issue 123 ``` **效果**：同时加载 `code-review` 和 `fix-issue` 两个SKILL，末尾的 `123` 作为参数传给**每一个**SKILL。 > v2.1.199 之前：只加载第一个SKILL，后面的 `/fix-issue 123` 会被当成普通参数文本传进去。 **堆叠调用的规则** - 最多展开**第一个 + 后面 5 个**，共 6 个堆叠SKILL - 遇到第一个不是「内联可调用SKILL」的 token 就停止展开 - 停止点之后的所有内容，作为参数传给所有已经展开的SKILL **会停止展开的情况** - 分叉子代理类型的SKILL（`context: fork`） - 参数本身以 `/` 开头的SKILL（比如 `/loop`） - 遇到普通文字就停 --- #### 按位置取单个参数两种写法等价 - `$ARGUMENTS[N]`：完整写法 - `$N`：简写形式下标从 0 开始，`$0` 是第一个参数，`$1` 是第二个。示例 ```yaml --- name: migrate-component description: 把组件从一个框架迁移到另一个 --- 将 $0 组件从 $1 迁移到 $2 保留所有原有功能和测试 ``` 调用：`/migrate-component SearchBar React Vue` 替换结果： - `$0` → `SearchBar` - `$1` → `React` - `$2` → `Vue` ### 动态上下文注入 #### 核心机制：!\`<command>\` 语法在 SKILL 内容里写 !\`shell命令\` ，**在发送给 Claude 之前就会先执行这条 shell 命令**，命令的输出会替换掉占位符。Claude 拿到的是最终数据，根本看不到命令本身。 **完整示例** ```markdown --- name: pr-summary description: 总结 PR 变更内容 context: fork agent: Explore allowed-tools: Bash(git *) --- ## PR 上下文当前分支： !`git branch --show-current` 该分支近期提交记录： !`git log master..HEAD --oneline 2>/dev/null || echo "暂无领先 main 分支的提交"` 变更文件统计： !`git diff --stat master 2>/dev/null || git diff --stat HEAD~1` ## 你的任务总结这个 PR... ``` 执行流程： ``` 用户输入 /pr-summary ↓ 系统加载 pr-summary.md skill 文件 ↓ 解析并执行预执行命令： ├─ ! `git diff --stat origin/main 2>/dev/null || git diff --stat HEAD~3` ├─ ! `git status` └─ ! `git log --oneline -10` ↓ 捕获命令输出 ↓ 将输出注入到SKILL提示词中 ↓ 组装完整提示词发送 ``` Claude 看到的提示词 ``` claude 看到的提示词 /pr-summary ... 命令输出1

命令输出2

命令输出3 ... -- ``` > 关键：动态上下文是**预处理阶段**执行的，不是 Claude 运行时执行的。 --- #### **重要特性** - 只执行一次，不递归只对原始文件扫描替换一遍。命令输出里就算再有 !\`...\` 占位符，也不会再执行第二遍。防止命令输出意外注入新的可执行命令。 - 语法识别规则 `!` 必须出现在**行首**或者**紧跟空白字符之后**才会被识别。 - ✅ 行首：!\`cmd\` - ✅ 空白后：- !\`cmd\` - ❌ 跟在其他字符后：KEY=!\`cmd\`（会原样保留，不执行） --- #### 多行命令写法单行写不下的，用 ```! 围栏代码块： ````markdown ## 环境信息 ```! node --version npm --version git status --short ``` ```` --- #### 全局禁用开关在 settings.json 里设置 `"disableSkillShellExecution": true` 效果 - 用户/项目/插件/附加目录来源的 SKILL ，shell 命令全部不执行 - 占位符会被替换成 `[shell command execution disabled by policy]` - **官方内置和托管SKILL不受影响** 适用场景企业托管配置里用，用户不能覆盖，防止自定义SKILL执行任意 shell 命令。 --- #### 深度推理提示 SKILL 内容里任意位置写上 `ultrathink`，触发时会开启深度推理模式。 > 相当于一次性加强思考深度，具体看 https://code.claude.com/docs/en/model-config#use-ultrathink-for-one-off-deep-reasoning 专门文档。 ### Hooks 配置任务型 Skill 和参考型 Skill 最大的区别在于：它通常会执行真实操作，而这些操作可能改变代码、环境或系统状态，也就是产生副作用（side effect）。例如提交代码会改变 Git 历史，部署应用会影响线上环境，修改文件会改变项目状态。对于这类操作，仅依靠 Skill 定义执行流程是不够的，还需要 Hooks 在关键节点自动触发检查，作为流程中的安全网。 Hooks 配置很简单，只需要在 frontmatter 的 hooks 字段中定义： ```yaml --- description: Safe deployment command disable-model-invocation: true allowed-tools: Bash(git:*), Bash(npm:*), Bash(ssh:*) hooks: PreToolUse: - matcher: Bash hooks: - type: "command" command: echo "About to run: $TOOL_INPUT" >> /tmp/deploy.log PostToolUse: - matcher: Edit hooks: - type: "command" command: npx prettier --write "$FILE_PATH" --- Deploy the application to staging environment. ``` 具体的 hooks 的作用在后续分析。 Skill Hooks 与全局 Hooks 的区别如下。 | 维度 | Skill Hooks | 全局 Hooks（settings.json） | | ------------- | ------------------------- | --------------------------- | | 生效范围 | 仅 Skill 执行期间 | 所有对话 | | 配置位置 | SKILL.md frontmatter | `.claude/settings.json` | | 随 Skill 分发 | ✅ 打包在一起 | ❌ 需单独配置 | | 适用场景 | Skill 专属的验证 / 格式化 | 全局的安全策略 | ### 子代理独立运行 SKLL 在 frontmatter 加上 `context: fork`，SKILL会开启隔离执行模式；整个 `SKILL.md` 的内容会直接作为子代理的完整提示词；关键隔离特性：**子代理读取不到主对话的聊天历史**，完全独立上下文。 > [!warning] > > `context: fork` 只适合**带有明确执行任务**的 SKILL； > > 如果 SKILL 只有规范、标准、参考文档，没有具体待办任务，子代理只会拿到一堆规则，没有执行目标，最终返回无有效内容。两种「SKILL + 子代理」协作模式对比 | 模式 | 系统提示词来源 | 执行任务 | 额外加载内容 | | ------------------------- | ------------------- | --------------------- | --------------------------------------------- | | SKILL配置 `context: fork` | 你指定的 agent 类型 | 整个 SKILL.md 全文 | 默认加载 `CLAUDE.md`；`Explore/Plan` 类型除外 | | 子代理配置 `skills` 字段 | 子代理自身 md 正文 | Claude 下发的委派任务 | 预加载 SKILL + `CLAUDE.md` | 开启 fork 后，任务写在 SKILL 里，再通过 `agent: xxx` 指定子代理类型执行；内置的 `Explore`（调研）、`Plan`（方案规划）两种代理会刻意精简上下文：**不会加载 CLAUDE.md、不会读取 git 状态**；因此搭配 `agent: Explore` 的分叉SKILL，仅能读取当前 `SKILL.md` + 该代理自带系统提示词，无额外冗余内容，节省 Token。 ## 任务型 SKILL 设计方法论设计思考清单： | 层级 | 核心问题 | 设计原则 | | ---------- | -------------------------- | ------------------------ | | Intent | 用户为什么需要这个 Skill？ | 从用户目标出发命名 | | Invocation | 谁决定调用？ | 用户触发 vs 模型自动调用 | | Permission | Skill 能做什么？ | 最小权限 | | Context | Skill 需要知道什么？ | 动态信息预注入 | | Workflow | Skill 如何完成任务？ | 明确步骤和状态流 | | Guardrail | 如何避免误操作？ | Hooks + 条件检查 | | Isolation | 是否影响当前会话？ | 必要时 fork | | Model | 需要什么推理能力？ | 能力匹配成本 | | Validation | 如何确认成功？ | 自动验证结果 | | Recovery | 出错怎么办？ | 回滚与人工确认 | - **单一职责原则**：一个命令只做一件事。 - **清晰命名原则**：从命令名就能知道他做什么。推荐命名模式 `verb + object + scope` - **有意义的参数提示**：让使用者了解如何传参。例如 `argument-hint: [source file] [target directory]` - **权限最小化原则**：严格控制每个任务的权限边界。例如 ``` allowed-tools: - Bash(git status:*) - Bash(git add:*) - Bash(git commit:*) ``` - **可验证性原则**：每个 Skill 应该定义怎么知道成功，否则 Skill 只是“执行动作”，不是“完成任务”。例如 ``` kubectl apply kubectl rollout status health check endpoint test ``` - **可恢复原则**：危险 Skill 必须考虑失败。 ## 小结命令的价值在于积累——团队标准化流程就是把最佳实践固化为任务型 Skill。任务型 Skill（用户触发动作）、参考型 Skill（Claude 匹配知识）、SubAgent（隔离执行）三者共存互补。 | Skill 类型 | 任务型 Skill | 参考型 Skill | SubAgent | | ------------------------ | -------------------------- | ------------------ | ------------------------- | | 本质 | 用户触发的动作 | Claude 匹配的知识 | 独立执行的角色 | | 触发方式 | `/name` 显式调用 | Claude 自动判断 | Task 工具或 context: fork | | disable-model-invocation | true | 不设（默认 false） | N/A | | allowed-tools | 精确授权危险操作 | 一般不需要 | 在 agent 配置中设定 | | !\`command\` | 常用（注入运行时上下文） | 少用 | N/A | | Hooks | 常用（安全网） | 少用 | 全局 Hooks 生效 | | 上下文 | 主对话（或 context: fork） | 主对话 | 隔离 | | 典型场景 | commit、deploy、review | API 规范、代码风格 | 大型审查、并行任务 | 我们仍以“代码审查”为例，对比一下同一个需求的三种实现。 | 方案 | 配置要点 | 适用场景 | | -------------------------- | ------------------------------------------------------------ | -------------------------------------- | | 任务型 Skill `/review` | `disable-model-invocation: true` + `allowed-tools: Read, Grep` | 用户完成功能后主动触发审查 | | 参考型 Skill `code-review` | description 描述审查场景，不设 disable | 用户说 "帮我看看代码"，Claude 自动匹配 | | SubAgent `reviewer` | `.claude/agents/reviewer.md` + 只读工具 | 审查整个 PR 的几十个文件，隔离执行 |

06-ClaudeCode-任务型SKILL.

Dylan Kwok

06-ClaudeCode-任务型SKILL