Agent Skills 入门：是什么、怎么写、装在哪

用智能体写代码久了，总有一些话要反复说：提交信息怎么写、发版要跑哪几步、这个项目的接口约定是什么。每次都粘贴一遍，既浪费上下文，也容易漏。Skill 就是把这些内容打包成文件，让智能体在需要时自己去读。

Skill 是什么

一个 Skill 就是一个目录，里面至少有一个 SKILL.md：

summarize-changes/
├── SKILL.md        必需：前置信息 + 指令
├── reference.md    可选：详细参考资料，需要时再读
└── scripts/
    └── helper.py   可选：可执行的脚本

SKILL.md 分两部分：开头 --- 之间的 YAML 前置信息，告诉智能体这个 Skill 是做什么的、什么时候用；后面的 Markdown 正文是具体指令。

---
name: commit-message
description: 按团队约定写提交信息。用户要提交代码、写 commit message 时使用。
---

1. 运行 `git diff --staged` 查看暂存的改动
2. 第一行不超过 50 个字，用动词开头，说明改了什么
3. 空一行后用列表写原因和影响范围

这种格式来自 Agent Skills 开放标准，Claude Code、Codex、Cursor 等都支持，写一次可以在多个智能体里用。

为什么不直接写进 CLAUDE.md / AGENTS.md

关键在于按需加载（Codex 文档称为「渐进式披露」）：

• 会话开始时，智能体只看到每个 Skill 的名字和描述
• 任务和描述对得上，或者你手动调用时，才加载 SKILL.md 全文
• 辅助文件和脚本，只有指令里用到时才读取或执行

所以 Skill 可以放很长的参考资料，平时几乎不占上下文。而 CLAUDE.md、AGENTS.md 每次会话都完整加载，适合放「每次都该知道的事实」，比如构建命令和目录结构。

一个简单的判断方法：是事实，放项目说明；是流程，放 Skill。 Claude Code 官方文档的说法是，当 CLAUDE.md 里某一节从「事实」长成了「流程」时，就该把它拆成 Skill。

怎么调用

两种方式：

有副作用的流程（部署、发消息、提交）不适合让智能体自己决定什么时候跑。在 Claude Code 里，前置信息加 disable-model-invocation: true，就只能手动调用。

放在哪里

把整个目录放到智能体读取 Skill 的位置。个人目录对所有项目生效，项目目录提交进仓库后团队都能用：

两个常见错误：

• 只放了一个 name.md 文件，而不是 name/SKILL.md 目录，智能体不会识别
• 只复制了 SKILL.md，漏了 scripts/ 和参考文件，指令里引用的内容就找不到了

各家的完整规则（同名时用哪个、子目录里的 Skill 什么时候加载）见 Claude Code：Skill 和 Codex：Skills。

写好一个 Skill 的要点

1. 描述决定会不会被触发。 自动调用完全依赖 description。把用途和触发场景写在最前面，用用户自然会说的词，比如「写提交信息」「review 这次改动」。描述在 Skill 很多时会被截短，所以关键词要靠前。

2. 正文要短。 Skill 一旦加载，内容会留在对话里，每一行都持续占用上下文。写要做什么，不写为什么这么做。长篇资料放进单独的文件，在 SKILL.md 里说明「需要 X 时读 reference.md」。

3. 一个 Skill 只做一件事。 「部署」和「写发版说明」拆成两个，描述更好写，触发也更准。

4. 装别人的 Skill 前先读一遍。 Skill 会让智能体照着执行，可能运行自带的脚本。Claude Code 的 allowed-tools 字段还能让列出的工具在调用时免确认。来源不明的 Skill，先看正文、allowed-tools 和 scripts/。

从哪里找现成的 Skill

本站的 Skills 目录 自动收录 GitHub 上的 Skill 仓库，精选 页按场景挑了一批，官方 页列出各厂商自己维护的 Skill。每个详情页都给出了安装方式。

也可以让智能体自己找和安装：

npx funcoding-cli skills find "代码评审"
npx funcoding-cli skills add <owner/repo/skill>

默认装到 Claude Code 的个人目录，加 --agent=codex 或 --agent=cursor 装给其他智能体，加 --project 装到当前项目。命令说明见 CLI。