第 4 章 · 02 SKILL.md 结构与配置字段

第 4 章 · 02 SKILL.md 结构与配置字段

本节摘要:技能文件的目录结构(SKILL.md 与 scripts/references/templates 平级),必填 frontmatter 仅 name + description,可选字段与斜杠命令相同(argument-hint/allowed-tools/model/disable-model-invocation/user-invocable/context/agent/hooks)。正文支持 $ARGUMENTS/$0/$1 参数替换与 !`cmd` 动态注入;context: fork 可在隔离 subagent 中运行;user-invocable: false 让技能仅由 Claude 自动调用。一句话:技能是命令的超集——命令能做的,技能都能做,还多了自动触发。

学习目标

阅读完本节,你应当能够:

1. 画出技能的目录结构。
2. 背出必填字段与全部可选字段。
3. 说出 user-invocable: false 与 context: fork 的用途。

一、目录结构

my-skill/
├── SKILL.md          # 技能定义(frontmatter + 正文)
├── scripts/          # 辅助脚本(如 detect-smells.py)
├── references/       # 参考文档(按需加载)
└── templates/        # 输出模板
​

二、frontmatter 字段

---
name: my-skill             # 技能名(变 /my-skill);默认目录名
description: 作用与触发时机   # 必填——唯一影响自动触发的字段
argument-hint: [参数提示]
allowed-tools: Bash(git *)  # 免权限白名单
model:                      # 指定模型
disable-model-invocation: true  # 仅用户可调用
user-invocable: false       # 仅 Claude 自动调用(不出现在 / 菜单)
context: fork               # 在隔离 subagent 中运行
agent: general-purpose      # context: fork 时的 agent 类型
hooks:                      # 技能级 hooks(第 7 章)
---
​

要点:description 是自动触发的唯一依据——它决定 Claude"什么时候想起用这个技能",所以必须写清触发场景与关键词;user-invocable: false 适合 brand-voice 这类"应该始终生效"的语气类技能;context: fork 让技能在隔离上下文中执行,适合长流程。

三、正文能力

与命令完全一致:$ARGUMENTS/$0/$1 参数替换、!`cmd` 动态注入、@file 引用。技能 = 命令 + 自动触发——这是本章的核心公式。

四、版本与质量

技能可带版本历史(如 frontmatter 外记录 v1.0.0 变更);SKILL.md 控制在 500 行内,超出部分拆到 scripts/references——既保持正文可读,又符合渐进式披露。

小结

SKILL.md 的写法与命令同源,必填只有 name+description;所有扩展能力(参数/注入/隔离/权限)都是可选项。写技能时最值得花心思的是 description——它是自动触发的"门牌号"。下一节精读六个示例技能。