Agent Skills 入门：教 Claude 一次，以后自动照做

一句话

Skill 是一个文件夹，核心是一份 SKILL.md：开头写名称和描述，正文写做事步骤，旁边可以放参考文档和脚本。Claude 平时只看描述，任务匹配时才加载正文。这门课教你写第一个 Skill、写出能稳定触发的描述、用渐进加载节省上下文，再通过仓库、插件和企业设置分享出去，最后讲怎么排查不触发和冲突。

这篇导读覆盖的课程

• Introduction to agent skills —— 6 节课

课程结构

什么是 Skills

Skill 解决什么问题，和每次重复交代有什么区别。

创建第一个 Skill

SKILL.md 的头部字段和正文；写一段能可靠触发的描述。

配置与多文件 Skill

渐进加载的目录结构；allowed-tools 限制工具；运行脚本而不占上下文。

Skills 与其他功能的区别

Skills、CLAUDE.md、hooks、子代理各自适合什么。

分享 Skills

提交到仓库、通过插件分发、用企业托管设置全组织部署；在子代理里使用 Skills。

排错

不触发、优先级冲突、运行时错误的排查方法。

精华：这门课真正要你带走的东西

Skill 解决“每次都要重新交代”的问题。你每次让 Claude 写发布说明，都要贴一遍格式要求；每次做代码审查，都要列一遍检查清单。Skill 把这些固定下来，Claude 在匹配的任务里自动使用。

最小的 Skill 只要一个文件：

.claude/skills/release-notes/SKILL.md
---
name: release-notes
description: 根据 git 提交记录写版本发布说明。用户要写 release notes、changelog 或版本说明时使用。
---
1. 读取上一个 tag 到 HEAD 的提交。
2. 按“新功能 / 修复 / 破坏性变更”分组。
3. 每条一句话，面向用户而不是开发者。

描述（description）决定会不会触发。Claude 在每次会话开始时只看到各 Skill 的名称和描述，靠描述判断当前任务要不要用。所以描述要同时写清“做什么”和“什么时候用”，并包含用户可能说的关键词。描述含糊，Skill 就不触发或乱触发。

渐进加载（progressive disclosure）：只在需要时读需要的部分。第 1 层是描述，始终在上下文里，很短。第 2 层是 SKILL.md 正文，触发后才加载。第 3 层是同目录下的参考文件（如 reference.md、模板），正文里告诉 Claude“需要时再读”。这样一个 Skill 可以附带很多资料，却几乎不占平时的上下文。

脚本不占上下文。确定性的步骤（解析文件、校验格式）写成脚本放进 Skill 目录，让 Claude 直接运行。Claude 只看到运行结果，不需要把脚本源码读进上下文。用 allowed-tools 字段可以限制 Skill 运行期间能用的工具，例如只读 Skill 不许编辑文件。

和其他功能怎么分工：

• CLAUDE.md：每次都加载的项目常识。适合短小、处处适用的规则。
• Skills：按需加载的专门流程。适合只在某类任务里用到的长说明。
• hooks：必定执行的脚本，不经过模型判断。适合不能被跳过的规则。
• 子代理：独立上下文里的助手。适合要隔离大量中间信息的子任务；子代理也可以预加载 Skills。

分享的 3 个层级。个人：放 ~/.claude/skills/。项目：放仓库的 .claude/skills/ 并提交，团队成员拉代码即可用。更大范围：打包进插件，或由管理员用企业托管设置推送到全组织。

关键概念

SKILL.md

Skill 的主文件：YAML 头部（name、description 等）加 Markdown 正文。

description（描述）

Claude 判断是否使用 Skill 的唯一依据，要写清做什么和何时用。

渐进加载（progressive disclosure）

描述常驻、正文触发后加载、参考文件按需读取的三层结构，用来节省上下文。

allowed-tools

SKILL.md 头部字段，限制 Skill 激活时 Claude 可用的工具。

Skill 存放位置

个人目录 ~/.claude/skills/、项目目录 .claude/skills/、插件、企业托管设置，范围依次扩大。

斜杠调用

除了自动触发，也可以输入 /skill-name 手动调用一个 Skill。

学前准备

• 会用 Claude Code 的基本操作（第 06 篇）。
• 想好 1 件你反复给 Claude 交代的事，作为第一个 Skill 的素材。

动手练一遍

1. 写第一个 Skill：在项目里建 .claude/skills/ 下的一个目录，写 SKILL.md。内容选你最常重复的要求，例如提交信息格式。
2. 测触发：新开会话，用 3 种不同说法提出这类任务（一句直接、一句含糊、一句用英文）。记录哪几次触发了。没触发就改描述，加入你实际会说的关键词。
3. 改成多文件：把正文里的长示例挪到 examples.md，正文只写“需要示例时读 examples.md”。确认效果不变。
4. 加脚本：写一个小脚本做一步确定性检查（例如检查提交信息是否以类型前缀开头），在 SKILL.md 里让 Claude 运行它。
5. 分享：提交到仓库，让一位同事拉代码后试用。

容易卡住的地方

• 描述只写“做什么”不写“何时用”。Claude 无法判断当前任务是否匹配。
• 把所有内容塞进 SKILL.md 正文。长资料放参考文件，按需读取。
• 用 Skill 实现必须执行的规则。Skill 靠模型判断是否触发，强制规则用 hooks。
• 多个 Skill 描述重叠。Claude 可能选错，描述之间要有清楚的边界。
• 改了 Skill 却在旧会话里测试。新开会话再测，确保加载的是新版本。

延伸阅读

• Claude Code 文档：Skills —— 字段说明、存放位置和内置 Skills（英文）
• Anthropic 工程博客：Agent Skills —— 渐进加载的设计思路（英文）
• anthropics/skills 示例仓库 —— 官方 Skill 示例，可以直接参考结构
• 下一篇：子代理入门 —— 另一种保持上下文干净的方式

← 返回课程目录