Skills（技能）教程 · AI Code Study

01

它是什么：一份说明书，一门可移植的手艺

你大概有过这种经历：同一个流程——「按这个模板写周报」「用这套规范提交代码」「按这五步排查线上问题」——每隔几天就要往聊天框里重贴一遍。Agent Skills 解决的就是这件事：把流程知识打包成一个文件夹，里面一份 SKILL.md 写清元数据和步骤，需要时再附上脚本、模板、参考文档。Agent 平时只「记得有这么门手艺」，活儿对上了才翻说明书。

格式由 Anthropic 发起、以开放标准发布（agentskills.io），一家写好的技能可以在多家 Agent 之间复用——目前多家开源 Agent 已支持这一格式。它不是插件系统，没有代码接口：一份技能就是「Markdown 写的说明书」加上可选的附带文件，版本控制、代码评审、跨团队共享全部沿用你现有的 Git 流程。

它和上一页的 vibe coding 是绝配：vibe coding 里「每次都要重复交代」的那部分——验收标准、提交规范、复盘格式——写进 SKILL.md 就从「每次口述」变成「永久生效」。技能也是 Agent 使用习惯里迁移成本最低的一环：学会了就是学会了，换一家支持该格式的 Agent 依然带着走。

格式: 一个文件夹 + SKILL.md
规范站点: agentskills.io（开放标准）
发起方: Anthropic，已开放生态采用
必填字段: name、description（YAML frontmatter）
启动成本: 每技能约百 token（只有元数据）
附带内容: scripts/ references/ assets/ 按需加载
与 MCP 关系: 互补：MCP 接系统，Skills 传方法
附带代码: 无运行时、无接口——纯 Markdown

什么时候该写一个技能：你发现自己「又在把同一段指令贴进对话」。判断口诀：贴了第二遍，就该进 SKILL.md 了。反过来，一次性任务不值得打包——那是普通提示词的活。

02

环境准备：让 Agent 认识技能目录

Skills 不是独立软件，它跑在 Agent 里。本页以 Claude Code 为主要演示环境（个人技能目录、项目技能目录、插件技能都支持）；OpenCode 等其他支持 Agent Skills 格式的工具，目录约定以各自官方文档为准——SKILL.md 本身是通用的，换工具通常只是换存放位置。

Terminal

# macOS / Linux：下载独立二进制 + 校验，无需 Node
curl -fsSL https://claude.ai/install.sh | bash

# 装完重开终端验证
claude --version

详细安装与登录见本站 Claude Code 教程。

Terminal

# 需要 Node.js ≥ 18
npm install -g @anthropic-ai/claude-code

# 以后升级也走 npm
npm update -g @anthropic-ai/claude-code

claude --version

用 nvm 的机器先切好 Node 版本再装，全局 bin 目录要在 PATH 里。

Terminal · 把两个技能目录先建好

# 个人技能：跟着你走，所有项目可用
mkdir -p ~/.claude/skills

# 项目技能：进某个仓库时再建，随仓库共享给全队
mkdir -p ~/your-project/.claude/skills

# 验证：启动后技能会被自动发现
claude

Claude Code 会监视技能目录，改完 SKILL.md 存盘即生效，不用重启。

目录名有讲究：技能放在「一个以技能名命名的文件夹」里，且 SKILL.md 的 name 字段要与文件夹名一致（规范要求）。路径形如 ~/.claude/skills/weekly-report/SKILL.md——直接把 SKILL.md 散放在 skills/ 根下是不对的。

03

快速上手：五分钟写第一个技能

照官方 quickstart 抄一个最小的：让 Claude 汇总最近的改动。整个技能只有一个 SKILL.md，连脚本都不用。

Terminal · 创建技能

mkdir -p ~/.claude/skills/summarize-changes

~/.claude/skills/summarize-changes/SKILL.md

---
name: summarize-changes
description: 汇总当前仓库最近的 git 改动，输出面向团队的变更摘要。当用户提到「总结改动」「写变更摘要」「这次改了什么」时使用。
---

# 变更摘要

1. 运行 git log --oneline -20 与 git diff HEAD~5 --stat
2. 按功能分组归纳，不逐条罗列 commit
3. 每组写一句「影响面」：动了数据结构、接口还是纯样式
4. 结尾单列一段「需要测试的点」
5. 全程只读，不修改任何文件

Terminal · 两种触发方式

# 方式一：直接点名（斜杠 + 技能名）
> /summarize-changes

# 方式二：自然语言命中 description，Claude 自动调用
> 帮我总结一下这周的改动，要在站会上讲

01
建目录、写 SKILL.md
frontmatter 只有 name 和 description 两行；正文是给 Agent 看的步骤。存盘即生效——Claude Code 在监视技能目录，不用重启会话。
02
description 写「做什么 + 何时用」
它是自动触发的唯一依据。把用户会说的词写进去（总结改动 / 变更摘要），命中率远高于一句干巴巴的「帮助总结代码」。
03
两种方式都试一遍
斜杠点名验证技能被发现；自然语言验证 description 是否写得够准。两种都通，这个技能才算上线。
04
不满意就改，改完立刻生效
技能就是 Markdown，改步骤、补一条「常见坑」、加一个示例，都是即时热更。好技能是迭代出来的。

没有把握时记住最小可用形态：frontmatter 两行 + 正文五步。先把流程跑通，再考虑加脚本和模板——过度设计是技能夭折的第一大原因。

04

核心概念：解剖、加载、位置、边界

SKILL.md 的解剖：frontmatter + 正文

每个技能由两部分组成。YAML frontmatter（两条 --- 之间）是给 Agent 看的元数据：name 与 description 必填，另有 license、metadata、allowed-tools 等可选字段。Markdown 正文是给 Agent 看的说明书：步骤、示例、边界情况，格式不限。按规范，name 只能小写字母、数字和连字符，最长 64 字符且必须与目录名一致；description 最长 1024 字符，要同时说明「做什么」和「什么时候用」。

SKILL.md · 带注解的骨架

---
# 元数据：启动时常驻，决定「何时想起这个技能」
name: my-skill            # 与目录名一致，小写+连字符
description: 做什么 + 何时用 + 用户会说的关键词
---

# 正文：被激活时整份加载，是「怎么做」的说明书
## 步骤          # 可执行的命令与顺序
## 示例          # 一组输入输出，锚定行为
## 边界          # 什么不做、何时追问

渐进披露：三级加载，省上下文

这是 Skills 设计里最聪明的一点。Agent 不是把所有技能全文塞进上下文，而是分三级：

三级加载（渐进披露）

# 第一级：启动时
只加载每个技能的 name + description ≈ 每技能约 100 token

# 第二级：任务匹配时
读入完整 SKILL.md 正文（建议 < 5000 token / 500 行以内）

# 第三级：执行中按需
正文里引用的 references/、scripts/ 文件，用到哪个读哪个

装 30 个技能，常驻成本也只有约 3000 token 的目录索引——这就是「Agent 手里一摞说明书，干活前只翻用得上的那本」。写技能时也要顺着这个机制来：正文保持精炼，细节拆进 references/，别把一切塞进主文件。

这个机制还有一层容错：长会话发生自动压缩后，Claude Code 会按预算重新挂载技能（每个保留开头约 5000 token、总预算 25000 token），技能不会因为压缩而「失忆」。

存放位置：个人、项目、插件三层

Claude Code 技能目录

# 个人技能：所有项目可用，不进 Git
~/.claude/skills/<技能名>/SKILL.md

# 项目技能：随仓库提交，全队共享
.claude/skills/<技能名>/SKILL.md

# 插件技能：插件包内，命名空间化调用
<插件名>:技能名

# 企业托管目录：管理员统一下发，优先级最高
（由组织管理设置指定）

同名冲突时优先级为企业 > 个人 > 项目。早期的 .claude/commands/ 自定义命令已并入技能体系：commands 目录里的 deploy.md 与 skills/deploy/SKILL.md 都注册为 /deploy，同名时技能优先。插件带来的技能调用时带命名空间前缀（/插件名:技能名），和你的自有技能不抢名字。

与 MCP 的区别：接系统 vs 传方法

两个概念经常被放在一起比，其实分工清晰：MCP 是接口——它让 Agent 连上外部系统（数据库、工单、浏览器），拿到「能调用的工具」；Skills 是方法——它教 Agent「怎么把一件事做对」，给的是流程、规范和判断标准。不是二选一，是分工协作。

MCP 解决的问题: 让 Agent「够得着」外部系统：数据库、工单、浏览器、内部 API
Skills 解决的问题: 让 Agent「做得对」内部流程：模板、规范、检查清单、口径
组合用法: 周报技能接 Jira MCP：MCP 拉数据，Skill 按团队格式组织成周报

一个判断口径：如果你的需求是「Agent 能操作 X 系统」，找 MCP 或写配置；如果是「Agent 每次都按同一个流程做 X」，写 Skill。大多数「每次都要重复交代」的痛点，都属于后者。

05

速查表：格式、字段、位置、原则

下面这块表格能搜。搜 frontmatter、触发、上下文 之类的词。

路径	作用
my-skill/	技能根目录，目录名 = 技能名 = frontmatter 的 name
SKILL.md	必需。YAML frontmatter + Markdown 指令正文
scripts/	可选。可执行代码（Python / Bash / JS），Agent 按需运行
references/	可选。参考文档，正文链接过去，Agent 按需再读
assets/	可选。模板、图片、数据文件等静态资源
references/REFERENCE.md	惯例：详细技术参考，正文保持精炼时往这里拆
相对路径引用	正文引用附带文件用相对路径，一层为宜，避免套娃
其他任意文件	规范不限制目录里放什么——但命名要自解释
skills-ref validate	官方参考库命令，校验 frontmatter 与命名规范
/skill-doctor（CC）	逐技能报告上下文开销与使用情况，瘦身前先体检

字段	说明
name（必填）	1-64 字符；小写字母、数字、连字符；不许 -- 连串、不许首尾连字符；必须与目录名一致
description（必填）	1-1024 字符；写清「做什么 + 何时用」，带上用户会说的关键词
license（可选）	许可证名称，或指向随附的许可文件
compatibility（可选）	≤500 字符；仅在有环境要求时写（依赖包、网络等）
metadata（可选）	字符串键值对；键名起得独特些，避免冲突
allowed-tools（可选）	空格分隔的预授权工具列表；实验性，支持程度因 Agent 而异
正文（Markdown）	格式不限；推荐结构：步骤 → 示例 → 边界情况
user-invocable（CC 扩展）	设 false 则用户不能斜杠调用，只由 Claude 自动触发
正文长度建议	SKILL.md 500 行以内；超了拆到 references/，按需加载
when_to_use（CC 扩展）	补充触发语境，与 description 合并生效（截断于 1536 字符）
disable-model-invocation	Claude Code 扩展；设 true 则只能斜杠手动调用
argument-hint（CC 扩展）	参数提示；配合 $ARGUMENTS、$1、命名参数做占位替换
model / effort（CC 扩展）	本次调用临时覆盖模型与思考强度，下一条消息恢复
context: fork（CC 扩展）	让技能跑在子代理里，不占用主会话上下文

位置（Claude Code）	说明
~/.claude/skills/	个人技能，跨项目可用，不进 Git
.claude/skills/	项目技能，随仓库提交，全队共享
嵌套目录 .claude/skills/	子目录里的项目也能识别到
插件 <plugin>/skills/	插件自带技能，调用时带命名空间
企业托管目录	组织统一下发，优先级最高
--add-dir	把额外目录挂进来作为技能来源
~/.claude/skills/synced/	claude.ai 同步下载的技能；synced 是保留名，勿手放
优先级	企业 > 个人 > 项目；技能覆盖同名 commands 文件
调用方式	/技能名直接调用；或 description 命中后自动调用
其他 Agent	OpenCode 等支持 Agent Skills 格式的工具，目录以各自文档为准

原则	说明
description 是索引	自动触发只看它；写「做什么 + 何时用」+ 用户口中的关键词
渐进披露优先	正文 < 500 行；细节拆 references/，用哪条读哪条
一个技能一件事	「周报生成」和「git 提交规范」分开写，别做大杂烩
步骤可执行	写命令而不是写意图：「运行 npm test」优于「注意质量」
给示例和边界	一组输入输出样例 + 三个常见坑，胜过十条抽象原则
声明只读或可写	审查类技能明确「不修改文件」，把约束写进正文
脚本能独立运行	scripts/ 里的脚本自带依赖说明和报错信息
迭代而非一次写完	用两周改一轮：把每次手动补的话沉淀回 SKILL.md
进 Git、过 review	项目技能是团队资产，改动走和代码一样的评审流程

06

实战：手写一个「周报生成」技能

做一个真实可用的团队技能：输入一堆零散的工作记录，按你团队的模板输出周报。它同时演示了三个要素——SKILL.md 正文、references/ 模板、按需加载。

第 1 步：建目录

Terminal

# 团队共享：放进某个仓库的 .claude/skills/
cd ~/your-project
mkdir -p .claude/skills/weekly-report/references

# 个人使用则改为：mkdir -p ~/.claude/skills/weekly-report/references

第 2 步：写 SKILL.md

.claude/skills/weekly-report/SKILL.md

---
name: weekly-report
description: 把本周零散的工作记录整理成团队周报，按 references/TEMPLATE.md 模板输出。当用户提到「写周报」「本周总结」「weekly report」时使用。
---

# 周报生成

## 输入
用户提供本周的工作记录（对话里直接给，或指定一个文件路径）。
记录零散、口语化都没关系，不要要求用户重写。

## 步骤
1. 读取 references/TEMPLATE.md，按模板结构组织内容
2. 把记录归纳到「本周完成 / 进行中 / 下周计划 / 风险与需要的支持」四栏
3. 每条产出用一句话 + 可验证的结果（数字、链接、PR 号），不写形容词
4. 语气克制：不用「圆满」「顺利」，用事实说话
5. 输出 Markdown；结尾附一行「数据截止时间」

## 边界
- 记录不足时，列出缺口并追问，不要编造内容
- 不修改任何项目文件，只输出周报文本
- 模板若被用户临时覆盖（给出新格式），以用户为准

第 3 步：附上模板文件

.claude/skills/weekly-report/references/TEMPLATE.md

# 周报 · YYYY-MM-DD ~ YYYY-MM-DD · 姓名

## 本周完成
- 做成了什么（结果 + 数据 / 链接）

## 进行中
- 事项（当前进度 X%，下一步是什么）

## 下周计划
- 事项（预期产出）

## 风险与需要的支持
- 风险 / 阻塞（需要谁做什么）

第 4 步：触发与验收

Terminal · 跑一遍

claude
> /weekly-report
  输入：本周修了支付回调的 bug（PR #214），
  给 WC 组件加了暗色模式（完成 80%），
  下周做埋点迁移。

# 验收：四栏结构齐、含 PR 号、没有编造条目、只输出了文本
# 满意后提交进仓库，全队共用：
git add .claude/skills && git commit -m "feat: 周报生成技能"

第 5 步：迭代与版本化

好技能是改出来的：每次你手动补了一句说明（「记得附上数据截止时间」），回头就把它写进 SKILL.md。技能随仓库走 Git，改模板、调步骤都有提交记录可回溯——这也是把技能放项目目录而非个人目录的理由：它是团队资产，值得被 review。

Terminal · 一次典型的技能迭代

# 用了两周，发现总要在对话里补一句「别写形容词」
vim .claude/skills/weekly-report/SKILL.md   # 把这句沉淀进步骤 3
git add -A && git commit -m "chore(skill): 周报禁用形容词表述"

验收标准：四步做完，/weekly-report 出现在斜杠菜单里；自然语言说「写周报」也能触发；换一个同样装了这个仓库的同事，技能开箱即用。做到这三条，它就是一份合格的团队资产——下一步该照方抓药，把「git 提交规范」「发布检查单」也各写一份。

07

避坑：四个最常见的坑

坑一：description 写得含糊，技能「从不触发」

对比：坏与好的 description

# 坏：Agent 不知道什么时候该用它
description: 处理周报相关的事。

# 好：做什么 + 何时用 + 用户会说的词
description: 把本周零散工作记录整理成团队周报，按模板输出。
当用户提到「写周报」「本周总结」「weekly report」时使用。

自动触发的唯一依据就是 description。写得像好文档一样具体，技能才会「该出手时就出手」。

坑二：name 与目录名不一致

规范硬性要求：name 必须与技能目录名完全一致，且只允许小写字母、数字和连字符。目录叫 Weekly_Report、frontmatter 写 weekly-report，直接违反规范；大写、下划线、连续连字符都是非法 name。拿不准就跑一遍官方的 skills-ref validate 校验。

坑三：正文越写越长，上下文被吃光

Terminal · 体检与瘦身

wc -l ~/.claude/skills/weekly-report/SKILL.md
# 超过 500 行就该拆了：
#   详细规范 → references/SPEC.md
#   示例合集 → references/EXAMPLES.md
#   正文里只留一句链接，按需加载

SKILL.md 正文在技能被激活时整份进上下文。把每个细节都塞正文，等于给每次调用都上全量税——拆文件不是洁癖，是成本控制。Claude Code 里可以用 /skill-doctor 逐技能查看上下文开销，数字比感觉可靠。

坑四：同名覆盖，一层压一层

技能的解析顺序是企业 > 个人 > 项目，同名技能只有最上层生效。你在项目里写的 commit-helper 没反应？先检查个人目录里是不是也有一个同名的旧版本。另外早期的 commands 文件与技能同名时技能优先，迁移旧命令时留意。

Terminal · 排查同名冲突

ls ~/.claude/skills/        # 个人层的同名旧版本？
ls .claude/skills/          # 项目层放对位置了吗？
grep -r 'name: commit-helper' ~/.claude/skills .claude/skills

08

进阶方向与资源

Agent Skills 官网——开放标准的总入口，quickstart、规范、客户端列表都在这。
完整规范（Specification）——frontmatter 每个字段的约束条件，写技能前值得通读一遍。
Claude Code Skills 文档——目录、优先级、触发规则的权威来源，本页的主要依据。
GitHub：agentskills/agentskills——规范仓库与 skills-ref 校验工具，欢迎提 issue 参与。
客户端列表（Client Showcase）——看看还有哪些 Agent 支持了这个格式。
官方 skill-creator 插件——在 Claude Code 里 /plugin install skill-creator@claude-plugins-official，用它半自动起草与评测技能。

学完本页去哪：先把你最常重贴的那段流程写成技能（s3 的五分钟最小版足够起步）。然后回 Claude Code 教程看权限与 hooks，把技能和自动化串起来；或在 OpenCode 教程里看看支持 Skills 格式的另一家 Agent 怎么玩，同一份技能两边通用。

09

收尾：照着勾一遍

装好了一个支持技能的 Agent，~/.claude/skills/ 与 .claude/skills/ 目录已建写过一个最小技能（两行 frontmatter + 五步正文），斜杠点名能触发 description 写了「做什么 + 何时用」，自然语言也能命中手写过 s6 的 weekly-report：SKILL.md + references/TEMPLATE.md 齐活能说清渐进披露三级加载，以及 Skills 和 MCP 的分工

0 / 5

它是什么：一份说明书，一门可移植的手艺

环境准备：让 Agent 认识技能目录

快速上手：五分钟写第一个技能

建目录、写 SKILL.md

description 写「做什么 + 何时用」

两种方式都试一遍

不满意就改，改完立刻生效

核心概念：解剖、加载、位置、边界

SKILL.md 的解剖：frontmatter + 正文

渐进披露：三级加载，省上下文

存放位置：个人、项目、插件三层

与 MCP 的区别：接系统 vs 传方法

速查表：格式、字段、位置、原则

实战：手写一个「周报生成」技能

第 1 步：建目录

第 2 步：写 SKILL.md

第 3 步：附上模板文件

第 4 步：触发与验收

第 5 步：迭代与版本化

避坑：四个最常见的坑

坑一：description 写得含糊，技能「从不触发」

坑二：name 与目录名不一致

坑三：正文越写越长，上下文被吃光

坑四：同名覆盖，一层压一层

进阶方向与资源

收尾：照着勾一遍