为什么要这张表
你照着例子写了第一个 SKILL.md，只用了 name 和 description 两个字段。后来你想让这个 skill 在特定文件夹自动触发，或者让它跑在隔离的子 Agent 里，或者限制只能用某些工具……这时候你才发现：SKILL.md 的 frontmatter 远不止这两个字段。
Claude Code 官方文档（CCBP · 2026-04-13 版）列出了 13 个 frontmatter 字段。大多数是可选的，但每个都解决一类真实需求。这张表的价值不是让你背全部 13 个，而是让你在遇到具体问题时知道去查哪个字段。
字段全集（13 个）
以下表格直接来自 CCBP 原文，不做改写：
| 字段 | 类型 | 必填 | 含义 | 例子 |
|---|---|---|---|---|
name | string | 否 | 显示名称，也是 /斜杠命令 的触发词；省略时默认取目录名 | name: write-daily |
description | string | 建议填 | 这个 skill 做什么；显示在自动补全、帮助 Claude 自发现 | description: Write a daily reflection note |
argument-hint | string | 否 | 自动补全时显示的参数提示 | argument-hint: "[issue-number]" |
disable-model-invocation | boolean | 否 | 设为 true 时禁止 Claude 自动调用此 skill | disable-model-invocation: true |
user-invocable | boolean | 否 | 设为 false 时从 / 菜单隐藏，只作为 Agent 预加载的后台知识 | user-invocable: false |
allowed-tools | string | 否 | 此 skill 激活期间不需要权限确认就能用的工具 | allowed-tools: "Bash, Read, Write" |
model | string | 否 | 运行此 skill 时使用的模型 | model: haiku |
effort | string | 否 | 覆盖模型的思考力度（low / medium / high / max） | effort: high |
context | string | 否 | 设为 fork 时把 skill 跑在隔离的子 Agent 里 | context: fork |
agent | string | 否 | context: fork 时指定子 Agent 类型，默认 general-purpose | agent: general-purpose |
hooks | object | 否 | 只在此 skill 作用域内生效的生命周期钩子 | （见下方易错点） |
paths | string/list | 否 | Glob 模式，匹配时才自动激活；接受逗号分隔字符串或 YAML list | paths: "src/**/*.py" |
shell | string | 否 | !`command` 块使用的 shell；bash（默认）或 powershell，后者需开 CLAUDE_CODE_USE_POWERSHELL_TOOL=1 | shell: bash |
核心 3 个字段深讲
1. description — 自动发现的关键
What the skill does. Shown in autocomplete and used by Claude for auto-discovery
这是 13 个字段里最值得精心写的一个。
原因：description 是 Claude 判断”要不要调这个 skill”的依据。写得太模糊（“处理文字相关任务”），Claude 不知道什么时候该用它；写得太窄（“只处理周报标题”），在边界场景会漏触。
好的 description 模板：[动作] + [对象] + [触发时机]
例：Write a daily reflection note in standard format. Use when user asks for daily journal or end-of-day review.
2. allowed-tools — 减少权限打断
Tools allowed without permission prompts when this skill is active
原文没有给出字段类型细节，但实际格式是空格或逗号分隔的工具名字符串。
实际意义：如果你的 skill 需要读写文件，但每次执行都弹出”允许使用 Read 工具吗？“确认框，体验很碎。把 Read、Write、Bash 等常用工具预先放进 allowed-tools，skill 激活期间这些工具就不再触发确认弹窗。
注意：这是局部授权，只在 skill 激活时生效，不影响 Claude 在其他场景的权限。
3. context: fork — 把重活交给子 Agent
Set to
forkto run the skill in an isolated subagent context
配合 agent 字段一起用：
context: fork
agent: general-purpose什么时候用：skill 步骤很多、会消耗大量上下文，又不希望影响主会话的注意力。典型场景：跑一个完整的代码审查流程、批量处理文件、执行多步调研任务。
context: fork 本质上是把这个 skill 的执行环境从主会话里”分叉”出去，主会话只收结果，不被中间过程污染。
易错点 2 条
易错点 1 · name 和目录名不一致
SKILL.md 里的 name 决定 /斜杠命令 的触发词，目录名只是文件系统的位置。
如果你把目录叫 write-daily-note，但 name: write-daily，用户用 /write-daily 触发，目录名不直接暴露给用户。这没有问题，但要保持自己心里清楚：两个名字可以不同，name 字段的优先级更高。如果省略 name，才会 fallback 到目录名。
易错点 2 · user-invocable: false 的使用场景易误解
初看会以为”隐藏 = 禁用”，实际上不是。设为 false 的 skill 仍然可以被 Agent 在内部预加载和调用，只是不出现在用户可见的 / 菜单。
典型用途：你有一个 skill 专门用于给其他 Agent 提供背景知识（比如”项目术语手册”），不希望用户在菜单里直接看到它、误触发它，但 Agent 可以自动读取。这时候设 user-invocable: false 是正确的做法。
易错点 3 · paths 写错导致 skill 永远不自动触发
paths 接受 Glob 模式，格式要准确。常见错误：写相对路径时少了 **/ 前缀，导致只匹配根目录而不匹配子目录。
# 错误：只匹配根目录的 .py 文件
paths: "*.py"
# 正确：匹配所有目录层级的 .py 文件
paths: "**/*.py"关联页面
[[5-术语们/03-skill]]— 本文是其”字段速查表”小节，读完概念再来查字段[[5-术语们/10-Harness]]— Harness 是组织 skill 的容器，了解 skill 放在哪里
来源：/Users/chenbin/Documents/Personal Kingdom/知识库/素材_AI使用/项目样本/claude-code-best-practice/github-mirror/claude-code-best-practice/best-practice/claude-skills.md · CCBP v2.1.101 · 2026-04-13