你是不是经常把同一段要求、同一份检查清单粘贴给 AI？这种时候就该把它写成一个 Skill：一个文件夹加一个 SKILL.md，以后说一句话或输入一个命令就能复用。
这篇从零做一个 Skill，讲清楚结构、写法和怎么测。还没用过 Skill，先看《Claude Code Skill 怎么用？Agent Skills 安装目录与触发方式》。
哪些工作值得做成 Skill
满足下面任意一条，就值得沉淀：
- 同一段说明你粘贴过三次以上，比如"写周报按这个格式"
- 固定的多步骤流程，比如发版前：跑测试 → 改版本号 → 写更新日志
- 团队约定，比如接口命名规范、提交信息格式
- CLAUDE.md 里某一段越写越长，已经变成了操作步骤。Claude Code 官方文档也建议把这类内容挪进 Skill，因为 Skill 正文只在用到时才加载
不适合做成 Skill 的：一次性的任务，或者一句话就能说清的偏好。
SKILL.md 的结构
一个 Skill 就是一个文件夹，SKILL.md 分两部分：
---
name: weekly-report
description: 做什么，以及什么时候该用
---
这里写给智能体的具体步骤。
name：Skill 的名字，用小写字母、数字和连字符，和文件夹名保持一致。Claude Code 里它就是你输入的命令/weekly-reportdescription：写清"做什么、什么时候用"。智能体靠这句话决定要不要自动加载，是整个 Skill 最关键的一行- 正文：写具体步骤。用祈使句，写清输入和输出
需要脚本、模板、参考资料，就放在同一个文件夹里：
weekly-report/
├── SKILL.md
├── references/ （参考资料，用到才读）
├── scripts/ （脚本）
└── assets/ （模板等文件）
想让 Skill 在 Claude Code、Codex、Cursor 里都能用，头部尽量只用name、description这些标准字段。Claude Code 还支持disable-model-invocation、allowed-tools、context: fork等扩展字段，其他工具不一定认。
从零做一个 Skill：根据 git 提交生成周报
假设你每周五都要让 AI 按固定格式，根据本周提交记录写周报。下面把它做成个人 Skill。
第 1 步：先把客户端接好。配置写在全局文件里，以 Claude Code 为例，打开 ~/.claude/settings.json：
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.aicodewith.ai",
"ANTHROPIC_AUTH_TOKEN": "sk-你的Key",
"CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK": "1"
}
}
Codex 用户在 ~/.codex/config.toml 里配置 provider，写法见《Codex config.toml 配置指南》。第 2 步：建文件夹。个人 Skill 放在家目录，所有项目都能用：
mkdir -p ~/.claude/skills/weekly-report
用 Codex 就放到~/.agents/skills/weekly-report/；想让团队共用，就放进项目的.claude/skills/或.agents/skills/并提交到仓库。
第 3 步：写 ~/.claude/skills/weekly-report/SKILL.md：
---
name: weekly-report
description: 根据本周 git 提交记录生成中文周报。当用户说"写周报""总结本周工作""这周做了什么"时使用。
---
# 生成周报
1. 运行 `git log --since="1 week ago" --pretty=format:"%h %s" --no-merges` 获取本周提交。
2. 按功能把提交分成三类：新功能、问题修复、其他。
3. 按下面的格式输出，每条一句话，不要出现提交哈希：
## 本周完成
- 新功能：……
- 问题修复：……
- 其他：……
## 下周计划
（留空，提醒用户自己补充）
4. 如果本周没有提交，直接告诉用户，不要编造内容。
第 4 步：试一下。进入任意 git 项目，运行 claude，然后：
- 手动调用：输入
/weekly-report - 自动触发：直接说"帮我写一下这周的周报"
两种方式都按格式出周报，就说明这个 Skill 做好了。Claude Code 会自动发现新建或修改的 Skill，不用重启。
Claude Code 还有个专属写法：在正文里写一行 `!git log --since="1 week ago" --oneline`，它会先执行命令，把结果直接塞进 Skill 内容里再交给模型。这个写法只在 Claude Code 里有效。
description 怎么写才能准确触发
智能体平时只看得到 name 和 description，所以描述写不好，Skill 就不会被用上，或者乱被用上。
把关键用途和触发词放在最前面。Skill 多了以后描述可能被截短，前半句要能单独说明白。
写上用户真正会说的话。对比一下：
| 写法 | 问题 |
|---|---|
| description: 周报工具 | 太短，智能体不知道什么时候用 |
| description: 一个非常强大的、可以帮助你提升效率的智能助手 | 全是虚词，没有触发词 |
| description: 根据本周 git 提交记录生成中文周报。当用户说"写周报""总结本周工作"时使用。 | 有用途、有触发词，好 |
写清边界。容易和别的 Skill 混淆时，加一句"不用于……"，比如"不用于写月报或项目总结"。
有副作用的不要自动触发。部署、发消息这类，Claude Code 和 Cursor 加 disable-model-invocation: true，只允许手动调用。
测试和迭代
- 正向测：换三四种说法提需求，看能不能自动触发
- 反向测：说一些不相关的话，确认它不会乱触发
- 开新会话测：写 Skill 那个会话里残留的上下文会掩盖说明里的漏洞，一定要在新会话里试
- 对比有无 Skill 的结果：同样的需求，关掉 Skill 再跑一次，确认 Skill 真的让结果更好
- 按问题改：不触发就改
description；触发了但做错，就改正文步骤
省事的办法是用官方的 Skill 生成工具帮你起草和测试：
- Claude Code：安装 skill-creator 插件
/plugin install skill-creator@claude-plugins-official，然后让它评估你的 Skill - Codex：输入
$skill-creator - Cursor：输入
/create-skill
保持正文简短。Claude Code 官方建议SKILL.md控制在 500 行以内，详细资料拆到references/里，用到再读。
常见问题
Skill 写好了但 / 菜单里找不到？
先检查文件名是不是 SKILL.md、是不是放在 ~/.claude/skills/<名字>/ 这一层。Claude Code 里，头部的 --- 必须是文件第一行，否则头部不会生效；可以运行 claude plugin validate ~/.claude/skills 检查格式。
头部 YAML 写错了会怎样？
在 Claude Code 里，Skill 还能用 /名字 手动调用，但 description 读不到，就不会自动触发。
一个 Skill 可以做好几件事吗？
不建议。一个 Skill 只做一件事，触发更准，也更好维护。多件事就拆成多个 Skill。
怎么分享给同事？
最简单的是放进项目的 .claude/skills/ 或 .agents/skills/ 提交到仓库，同事拉代码就有。要跨项目分发，可以打包成插件。
用别人写的 Skill 要注意什么？
装之前先读一遍 SKILL.md 和里面的脚本。Claude Code 的 allowed-tools 字段可以让 Skill 免确认执行命令，来路不明的 Skill 要特别留意这一行。
