一分钟，教会你的 AI 智能体新技能

第一个技能 — 把重复的请求做成技能

适合做第一个技能的，是你已经向 AI 解释过三次以上的事：怎样写提交信息、你的测试步骤、你的报告格式。把这些说明在 SKILL.md 里写一次，智能体每次都会找到并照做。

1. 选一件你总在解释的工作，用小写字母、数字和连字符起一个短名字（commit-message）。
2. 在智能体的技能文件夹里，用这个名字建一个文件夹。npx skills init <name> 会建好文件夹和 SKILL.md 模板。
3. 在最上面填写 name（和文件夹名相同）和 description，在下面写步骤。
4. 开一个新会话，用平常的话请它做这件事。如果智能体用了这个技能，就成功了。

# in your project folder
mkdir -p .agents/skills && cd .agents/skills
npx skills init commit-message      # makes commit-message/SKILL.md

# Codex · Gemini CLI · Copilot CLI read   .agents/skills/commit-message/SKILL.md
# Claude Code reads                       .claude/skills/commit-message/SKILL.md

你也可以对智能体说：“把我们刚才做的事做成一个技能。”Claude Code 和 Codex 都懂这个格式（Codex 内置了 $skill-creator）。

description — 智能体唯一的线索

一开始，智能体只读每个技能的名字和说明（description）。它靠这几行判断哪个技能适合你的请求。说明含糊，技能就永远用不上，或者在不该用的时候被用上。

• 写清楚它做什么、什么时候用 — 两者都要，用一两句话。
• 用第三人称写（"Writes commit messages …"），不要写 "I can help you …"。
• 写进人们真正会输入的词："commit message"、"commit this"、"staged changes"。
• 规则：description 最多 1,024 个字符；name 最多 64 个小写字母、数字和连字符，并且和文件夹名相同。

# ✗ too vague — the agent cannot tell when to use it
description: Helps with commits.

# ✓ what it does + when to use it + the words people really say
description: Writes a git commit message from the staged changes in the Conventional Commits style. Use when the user asks for a commit message, says "commit this", or wants to describe staged changes.

Claude Code 在技能列表里最多只显示说明的 1,536 个字符，所以把最主要的用途放在最前面。

正文指示 — 简短、按顺序、带例子

frontmatter 下面是智能体使用技能时读的指示。智能体已经很聪明，所以只写它不知道的：你的规则、你的步骤顺序、你的格式。

• 省掉智能体已经知道的东西（git 是什么、怎样写 Markdown）。
• 顺序重要时就给步骤编号，并写明出问题时怎么办（“如果没有暂存任何内容，就说明并停下”）。
• 用一两个例子展示你想要的结果 — 例子比描述更能说明问题。
• 给一个默认做法，而不是列一堆选项（“用 pdfplumber；扫描的 PDF 用 OCR”）。
• SKILL.md 保持在 500 行以内。变长了就拆成多个文件（[高级] 标签页）。

---
name: commit-message
description: Writes a git commit message from the staged changes in the Conventional Commits style. Use when the user asks for a commit message or says "commit this".
---

1. Run `git diff --staged`. If nothing is staged, say so and stop.
2. Pick one type: feat, fix, docs, refactor, test or chore.
3. Write a subject of 50 characters or less, then a blank line,
   then why the change was made in one or two short lines.

Example:
fix(cart): keep the coupon after a page reload

The coupon code was stored only in memory.

调用技能并检查

技能有两种用法：请求和说明相符时，智能体自己选用；或者你按名字调用。

• 自动：用平常的话提出请求就行（“写一条提交信息”）。智能体读了说明后会加载技能。
• Claude Code：/skills 显示列表，/<skill-name> 调用技能。名字后面的话会放进 $ARGUMENTS。
• Codex：/skills 显示列表，在消息里写 $<skill-name> 就能调用。
• Claude Code 会立刻读取对 SKILL.md 的修改。如果新建了技能文件夹，运行 /reload-skills。在其他工具里，开一个新会话。

# Claude Code
/skills                 # list the skills it found
/commit-message         # call one yourself
/fix-issue 123          # "123" goes into $ARGUMENTS in SKILL.md

# Codex
/skills                 # list and pick
$commit-message         # mention one in your message

如果该用技能时没用上，先改 description — 大多数时候原因就在这里。

放在哪里 — 只给自己，还是给团队

同一个技能可以放在你的主文件夹里（给你所有的项目用），也可以放在项目里（给参与这个项目的所有人用）。

• 个人技能：Claude Code 用 ~/.claude/skills/，Codex、Gemini CLI 和 Copilot CLI 用 ~/.agents/skills/。
• 项目技能：项目里的 .claude/skills/ 或 .agents/skills/。提交之后，整个团队都用同一个技能。
• 如果两个技能同名，Claude Code 会优先使用个人技能，而不是项目技能。
• 永远不要在技能里放密码或 API 密钥 — 技能文件会被读取，也常被分享。

# only me, every project
~/.claude/skills/commit-message/      # Claude Code
~/.agents/skills/commit-message/      # Codex · Gemini CLI · Copilot CLI

# this project — commit it and the whole team gets it
.claude/skills/commit-message/
.agents/skills/commit-message/

git add .agents/skills/commit-message
git commit -m "Add the commit-message skill"

进阶练习 — 在你的项目里做一个

1. 写下一个你向 AI 提过三次以上的请求。
2. 用 npx skills init 建好这个技能的文件夹，写上 name 和 description。
3. 用五行以内写出步骤，并附一个结果的例子。
4. 在新会话里用平常的话提出请求，看技能有没有被用上。然后再按名字调用它。
5. 提一个不相关的请求，确认技能没有被用上。

五项都做到了，就进入 [高级] 标签页。

官方文档

• Agent Skills — Quickstart
• Agent Skills — Specification
• Claude Code — Skills
• Codex — Skills

已于 2026-10-18 对照官方文档核实。这些工具变化很快 — 如果命令不起作用，请查看官方文档。

拆成文件 — 只读需要的部分

智能体分三步读技能：开始时读名字和说明，使用技能时读 SKILL.md，其他文件只在需要时读。所以大块资料放进单独的文件，SKILL.md 就成了一张地图，告诉它什么问题该读哪个文件。

• SKILL.md 里写概要和“遇到这种情况，读那个文件”。
• 只从 SKILL.md 链接文件，只链一层。文件 → 文件 → 文件这样的链条常常只被读到一部分。
• 超过 100 行的参考文件，在最上面放一个目录。
• 按内容给文件起名（用 finance.md，不要用 doc2.md），路径一律用 / 写。

sql-report/
├── SKILL.md              ← the map: what to read for which question
├── references/
│   ├── finance.md        ← read only for revenue questions
│   └── sales.md          ← read only for sales questions
└── scripts/
    └── check_query.py    ← run it, do not read it

## Which file to read
- Revenue, billing → read [references/finance.md](references/finance.md)
- Deals, pipeline → read [references/sales.md](references/sales.md)

脚本 — 每次都必须一样的工作，写成代码

现成的脚本比智能体每次临时写的代码更可靠，而且运行时进入上下文的只有输出，不是代码。检查、转换等必须准确的工作放进 scripts/。

• 写清楚是要运行它（"Run scripts/check_query.py"），还是要阅读它（“规则见 scripts/check_query.py”）。
• 在脚本里处理错误，输出的信息要说明哪里错了、该怎么做。
• 写下需要的包和版本，真正必需的条件写进 compatibility。
• 建立一个循环：检查 → 修改 → 再检查，检查通过后才继续。
• 固定的值要用注释说明理由（为什么超时是 30 秒？）。

## Check the query before you run it

Run:
    python3 scripts/check_query.py query.sql

It prints OK, or one problem per line.
If it is not OK, fix the query and run the check again.
Run the query only after you see OK.

能运行哪些语言要看智能体。常用的是 Python、Bash 和 JavaScript。

frontmatter 选项 — 标准字段和各工具的附加项

除了 name 和 description，标准里还有几个可选字段，各工具也会加上自己的字段。工具会忽略不认识的字段，所以先让技能只靠标准字段就能工作。

• 标准：license、compatibility（需要的程序和网络，最多 500 个字符）、metadata（作者等）、allowed-tools（预先允许的工具 — 实验性）。
• Claude Code 的 disable-model-invocation: true — 只有你能调用。用于有副作用的工作，比如部署或发送消息。
• Claude Code 的 user-invocable: false — 只有 AI 使用，并在 / 菜单中隐藏。context: fork 会在子智能体里运行技能。
• Claude Code 的 !`command` — 在读取技能前先运行命令，并用输出替换它（例如 !`git diff HEAD`）。
• Codex：agents/openai.yaml 里的 policy → allow_implicit_invocation: false — 只有你调用 $<skill-name> 时才会使用这个技能。

---
name: deploy
description: Deploys the app to staging or production. Use when the user says deploy, release or ship.
license: MIT
compatibility: Requires git, docker and network access
metadata:
  author: my-team
allowed-tools: Bash(git status) Bash(./scripts/deploy.sh *)
# Claude Code only — other tools ignore these
disable-model-invocation: true
argument-hint: "[staging|production]"
---

Current branch: !`git branch --show-current`

Deploy to $ARGUMENTS with `./scripts/deploy.sh $ARGUMENTS`.

allowed-tools 里只放技能真正需要的命令。权限越宽，出错的代价越大。

测试 — 写很多之前，先写测试

技能好不好用，只有试了才知道。先看看没有技能时智能体会出什么错，然后只写够修正这些错的内容。

1. 不用技能，让智能体做这件事，记下它做错或漏掉的地方。
2. 针对这些漏洞，至少准备三个测试请求 — 其中一个是不该用这个技能的请求。
3. 指示只写到足够填补漏洞为止。
4. 在新会话里，用同样的请求分别试有技能和没技能的情况，并比较结果。
5. 用你会用到的每个模型测试 — 小模型可能需要更多细节。

# checks the frontmatter and the naming rules
skills-ref validate ./commit-message

[
  {"query": "write a commit message for what I staged", "use_skill": true},
  {"query": "commit this, it fixes the login bug",      "use_skill": true},
  {"query": "explain what git rebase does",             "use_skill": false}
]

skills-ref 是 agentskills 仓库里的参考工具（用于演示）— 克隆后用 pip install -e . 安装。在 Claude Code 里，/skill-doctor 会显示每个技能占用的上下文和使用情况。

安全 — 像读代码一样读别人的技能

技能是智能体要照做的一组指示，它的脚本会在你的电脑上运行。坏的技能会让智能体照着坏指示做事，所以安装前要检查。

• 只从你信任的地方安装。加上 -l 可以只看列表，不安装。
• 安装前，读一遍 SKILL.md 和 scripts/ 里的每个文件。
• 留意会把文件或密钥发到别处、或者会删除东西的命令。
• 不要把密码或密钥放进技能里。从环境变量读取。
• Claude Code：用 Skill(deploy *) 这样的权限规则阻止某个技能，用 disableSkillShellExecution 设置关闭 !`command`。

# see what is inside before you install
npx skills add my-name/my-skills -l

# read the instructions and every script
cat .agents/skills/<name>/SKILL.md
ls .agents/skills/<name>/scripts/

你自己的技能也一样：提交或分享前，再读一遍改动。

高级练习 — 让你的技能成长

1. 把进阶阶段做的技能里较长的部分移到 references/，并从 SKILL.md 链接过去。
2. 在 scripts/ 里写一个检查，并在 SKILL.md 里加上“检查 → 修改 → 再检查”的步骤。
3. 对技能文件夹运行 skills-ref validate，修正它报告的问题。
4. 准备三个测试请求（其中一个不该用这个技能），比较有技能和没技能的结果。
5. 安装别人做的技能前，从头到尾读一遍。

五项都做完了，就进入 [大师] 标签页。

官方文档

• Skill authoring best practices
• Agent Skills — Specification
• skills-ref — GitHub
• Claude Code — Skills

已于 2026-10-18 对照官方文档核实。这些工具变化很快 — 如果命令不起作用，请查看官方文档。

分享你的技能 — 一个 GitHub 仓库就够

把技能放进公开的 GitHub 仓库，任何人都能用 npx skills add <owner>/<repo> 安装。一个仓库可以放很多技能。

• 每个技能放在 skills/ 下自己的文件夹里。安装程序会找到它们。
• 加上 LICENSE，以及写明每个技能做什么和安装命令的 README。
• 用户可以用 -s 只取一个技能，用 -g 安装到他们所有的项目。
• 你修改技能并 push 后，用户用 npx skills update 就能拿到更新。

my-skills/                     # a public GitHub repository
├── README.md                  ← what each skill does + the install command
├── LICENSE
└── skills/
    ├── commit-message/SKILL.md
    └── sql-report/SKILL.md

# anyone can install it
npx skills add my-name/my-skills
npx skills add my-name/my-skills -s commit-message -g
npx skills update              # gets your new commits

从你自己的网站分享 — 像 SONUB 一样

你也可以从自己的网站分享技能。SONUB 就是这样做的：npx skills add https://sonub.com 会读取 /.well-known/agent-skills/index.json 里的列表，并把每个技能作为压缩包下载。

• 列表里有每个技能的名字、说明、压缩包地址，以及压缩包的 sha256 digest。
• digest 变了，npx skills update 就会重新下载那个技能 — 只更新有变化的技能。
• 如果 name 或 description 不符合规则（和文件夹同名的小写名字、最多 1,024 个字符的说明），安装程序会悄悄跳过这个技能。
• SONUB 每次收到请求都会从技能文件夹生成列表和压缩包，所以部署好的修改就是新版本。

# the list the installer reads
https://sonub.com/.well-known/agent-skills/index.json

# one archive per skill, with the sha256 digest of its bytes in the list
https://sonub.com/.well-known/agent-skills/gp.tar.gz

npx skills add https://sonub.com

• SONUB 技能和安装命令

一个技能，所有工具通用

Agent Skills 是开放标准，所以一个文件夹可以在 Claude Code、Codex、Gemini CLI、GitHub Copilot 等工具里使用。不同的只是各工具读取的文件夹。

• 让技能只靠标准字段（name、description）和普通指示就能工作。工具专用的选项只是附加项。
• 避免只属于某个工具的说法（“Bash 工具”）。写成“在终端里运行”。
• 在 .agents/skills/ 里放一个真正的文件夹，再链接到 .claude/skills/。npx skills add 可以帮你做（推荐），或者用 --copy 复制。
• 在 Claude Code 里，你还可以把技能和子智能体、钩子、MCP 一起打包成插件，通过市场分享。

# one real folder for every tool
.agents/skills/commit-message/

# a link so Claude Code finds the same folder
mkdir -p .claude/skills
ln -s ../../.agents/skills/commit-message .claude/skills/commit-message

如果技能用到 MCP 工具，要写出带服务器名的完整名字（ServerName:tool_name）。不写的话，智能体可能找不到这个工具。

• Claude Code 大师 — 插件

设计 — 什么时候用技能，什么时候用别的

教智能体的方法有好几种。在适合技能的地方用技能，工作就会更简单。

• 每次对话都要遵守的规则 → AGENTS.md（或 CLAUDE.md）。
• 偶尔才需要的流程或知识 → 技能。
• 交出去的大任务，只要结果回来 → 子智能体。
• 连接外部服务和数据 → MCP。技能可以教智能体怎样使用这些工具。
• 每次都必须发生的事（每次编辑后格式化）→ 钩子。

一个技能，一项工作。技能做的事太多时，就拆开。

• Claude Code 高级 — 技能、子智能体、钩子、MCP
• Codex 高级 — 配置、MCP、技能、钩子

维护你的技能 — 边用边改进

技能是靠观察它怎样工作变好的，不是靠猜。在真实任务里使用它，在智能体卡住的地方修改它。

• 观察智能体怎样使用它：从来不读的文件、反复读的文件、漏掉的规则。
• 在一个 AI 会话里改进技能，在新会话里测试 — 新会话会暴露缺少的东西。
• 不要写日期（“八月以前 …”），写现在的做法，把旧做法收进“旧做法”一节。
• 删掉没人用的技能 — 每段说明在每个会话里都会占用上下文。
• 问问你的团队：它在该启动的时候启动了吗？指示清楚吗？缺了什么？

大师清单

• description 写清了它做什么、什么时候用，以及人们真正会用的词
• SKILL.md 少于 500 行，其他文件只链接一层
• 脚本自己处理错误，并且写清了是要运行还是要阅读
• 至少有三个测试，其中一个是不该用这个技能的情况
• 里面没有机密信息，别人的技能先读过再安装
• 在你会用的智能体和模型里检查过，并附上安装命令分享出去

全部打勾后，把你的一个技能发布到 GitHub，用 npx skills add 分享出去。

官方文档

• skills CLI (npx skills) — GitHub
• Agent Skills
• Claude Code — Plugins
• Skill authoring best practices

已于 2026-10-18 对照官方文档核实。这些工具变化很快 — 如果命令不起作用，请查看官方文档。