一句话定义
Skill 是一个可复用的技能包。
它把“某件事该怎么做”写成 SKILL.md 和可选资源文件，让 Claude 在需要时按这套 playbook 执行。
一句人话: skill 不是“谁来干”，而是“这件事怎么干”。
为什么重要
只要你发现自己在反复给 AI 贴同一种 checklist、流程或操作说明，这段内容就该从聊天里毕业，变成一个 skill。
Anthropic 官方文档里最有用的一点，不是“skill 可以复用”，而是它按需加载：
CLAUDE.md这种项目说明会在会话起手时进入上下文- skill 的正文通常只有在触发时才进上下文
所以 skill 特别适合装“步骤很多，但不是每轮都要用”的东西。本仓库里的 kb-compile、kb-lint、learning 都是这个思路: 流程复杂，但不必每次开场都背进脑子里。
技术机制
在 Claude Code 里，一个 skill 的典型物理形态是：
.claude/skills/<skill-name>/SKILL.md它至少会有一个 description，告诉 Claude “这是什么能力、什么时候该用”。官方文档的关键机制可以压成三条：
- 名字和描述进入技能注册表，Claude 先知道“这里有这项能力”。
- 正文在触发时加载，所以长步骤和参考材料不会一直占上下文。
- skill 可以带 supporting files 和 scripts，让 AI 不只会说，还知道去哪读模版、跑什么脚本。
Anthropic 官方对 skill 的基本定义可以概括成一句话：
skill 是一组会被动态加载的指令、脚本和资源，用来让 Claude 在某类专门任务上做得更稳。
Claude Code 还在通用 skill 标准之上加了几层能力，比如 invocation 控制、按路径触发、以及 context: fork 时把某个 skill 放进 subagent 里跑。
最小可跑通例子
一个极简的 skill 目录可以长这样：
.claude/skills/write-daily/
└── SKILL.mdSKILL.md：
---
name: write-daily
description: Write a daily note in our standard format. Use when the user asks for a daily journal or reflection.
---
1. 先提炼今天发生的 3 件事
2. 再写 1 个情绪判断
3. 最后补 1 个明天要继续的动作从这里开始，你已经有了一个能复用的 skill。之后再需要补模板、例子、校验脚本，直接往这个目录里加文件，而不是每次重写 prompt。
常见误解
- skill = agent。不是。agent 是角色，skill 是能力。agent 可以调用 skill，skill 本身不需要人格。
- skill = MCP。也不是。skill 解决“我会什么”；MCP 解决“我能连什么”。
- skill 一定要写代码。不对。纯 markdown 流程、参考模板、检查清单，也可以是 skill。
- 越长越好。不对。官方文档明确建议把
SKILL.md保持精简，把大块参考材料拆到 supporting files，避免触发时一次加载过多内容。
与其他术语的关系
[[agent]]：agent 是 skill 的常见调用者；该不该调 skill，通常由 agent 判断。[[workflow]]：workflow 关心步骤编排；skill 是其中可复用的步骤单元。[[subagent]]：某些 skill 会用context: fork放到 subagent 里执行，把重活从主会话拆出去。[[MCP]]：MCP 连的是外部工具，skill 封装的是本地做法；二者经常搭配，但不是一回事。[[CLAUDE.md]]：CLAUDE.md 适合放长期共识；skill 适合放按需触发的程序化做法。[[Harness]]：skill 是 harness 里最像“可插拔能力模块”的部分。
陈彬视角
正确顺序: 先 workflow，再 agent，剩下全是 skill。
这句话的重点不是贬低 skill，而是提醒你: skill 最适合承接稳定、可复用、重复出现的那部分工作。
延伸阅读
[[agent]][[workflow]][[subagent]][[MCP]][[CLAUDE.md]][[02-基建/平台/claude-code/进阶_hooks_settings_plugins]]
🎬 3 个场景（读者最可能用到的情境）
场景 1 · 写作者装”风格校对 skill”
撰稿人每篇稿子收尾都要过一遍自定义校对规则（避免 AI 套话、控制句长、查虚词）。写成 .claude/skills/style-check/SKILL.md，每次只说”跑一下 style-check”，不用重贴 300 字指令。
场景 2 · HR 装”面试问卷 skill”
HR 每次发问卷都要按岗位生成 15 个问题、3 个 followup。把生成流程 + 问卷模板 + 评分口径封进 question-pack skill。换岗位只改输入，流程不用重写。
场景 3 · 散户装”复盘模板 skill”
散户每天收盘后让 AI 填同一张复盘表：持仓/盘面/情绪/明日计划。做成 daily-review skill，一句话触发，输出结构固定可归档。
⚖️ 和最像的邻居比
| 术语 | 本质区别 | 适用边界 |
|---|---|---|
| skill | 按需加载的可复用能力包 | 步骤多、要复用、但不是每轮都用 |
| agent | 有角色判断的岗位 | 需要稳定视角和边界判断 |
| CLAUDE.md | 项目级常驻说明书 | 每次都要知道的长期规则 |
| MCP | 外部工具接入协议 | 连第三方系统/数据源 |
🚫 反例（不该这么用）
反例 1 · 写成”每次都要贴”的 prompt
HR 每次面试前都在对话里贴一份 500 字的”问卷生成指令”，从不做成 skill。结果版本漂移、复用困难。正确做法：凡是贴过 2 次以上的 prompt，就该迁成 skill。
反例 2 · skill 正文塞 5000 字
把整本操作手册、所有模板、全部示例都堆在 SKILL.md 正文里，触发时一次吃掉大半上下文。正确做法：SKILL.md 保持精简（触发说明 + 主流程），模板/参考/长示例拆到同目录 supporting files，按需引用。
❓ 常见误解
- 误解 1：“skill 一定要写代码 / 挂脚本” → 实际：纯 markdown 的流程、清单、模板就足够是 skill，脚本只是可选件。
- 误解 2：“skill = agent” → 实际：skill 是能力，agent 是角色；agent 会调用多个 skill，skill 本身不需要人格。
- 误解 3：“skill 越复杂越专业” → 实际：最常用的 skill 往往只有 30 行，越简单越容易被正确触发。
🧬 历史坐标（最早谁提 · 本质 · 分型 · git）
最早谁提
2025 年 10 月 16 日 · Anthropic 官方博客《Equipping agents for the real world with Agent Skills》正式引入 Skills。2025 年 12 月 18 日 Anthropic 把 Skills 开放为跨平台标准。官方文：https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
本质（一句话 · 20 字内）
按需加载的可复用能力包（md + 脚本 + 资源）。
分型 / 演化（2-4 行主线）
- 2023-03 · OpenAI ChatGPT Plugins 开启”给模型插能力”的想象
- 2023-11 · ChatGPT GPTs 把”定制版 Claude”带给普通用户，但封闭在 ChatGPT 生态
- 2025-10 · Anthropic Agent Skills 发布，核心突破是 progressive disclosure（描述先进上下文，正文按需加载）
- 2025-12 · Skills 成为开放标准，社群 skill-library 规模化
代表 git / 文档
- anthropics/skills · Anthropic · 官方 skill library 仓库
- Equipping agents with Agent Skills · Anthropic (2025-10-16) · Skills 首发技术博客
- 官方 skills 文档 · Anthropic · SKILL.md spec 与 progressive disclosure 机制
为什么要这张表
你照着例子写了第一个 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