适合人群：已经在用 Claude Code（或其他支持 Agent Skills 的编程助手），希望让 AI 在特定任务上遵循固定规范的开发者；对“技能包”概念感到陌生的新手。
一、背景：为什么会有“技能包”
最近在 X 上看到一条中文技术账号的分享：用 Claude Code 写 SwiftUI，代码虽然能跑，但经常用到已经废弃的接口，界面复杂时还会出现卡顿。有一位长期编写 Swift 教程的作者把 SwiftUI 开发中常见的坑整理成了一个 Agent Skill，专门约束大模型在过时 API、状态管理、无障碍支持等方面的写法。另一位用户评论说，给 AI 配一份“老手经验”，有时比换一个更强的模型更有效。
这个观点值得展开：大模型掌握了大量通用知识，但它不知道你的团队规范、你的项目约定、某个框架最新的最佳实践。Agent Skills 就是把这些“经验”打包成文件，让 AI 在需要的时候自动加载。
本文从零开始，带你写一个最简单的技能包，并理解它的工作方式。
二、核心概念：一个技能包长什么样
根据 Claude Code 官方文档，一个 Skill 本质上是一个文件夹，里面至少包含一个SKILL.md文件。典型结构如下：
my-skill/ ├── SKILL.md # 必需：技能说明（带 YAML 头信息） ├── reference.md # 可选：更详细的参考资料 └── scripts/ # 可选：辅助脚本 └── check.pySKILL.md的开头是一段 YAML 头信息（frontmatter），其中最重要的两个字段是：
- name：技能名称，使用小写字母、数字和连字符；
- description：描述这个技能“做什么”以及“什么时候应该使用”。
这里有一个关键机制：渐进式加载。AI 一开始只读取每个技能的名称和描述，判断当前任务是否相关；只有确定需要时，才会读取SKILL.md的正文和其他附属文件。这样即使安装了很多技能，也不会一次性占满上下文。
因此，description 写得好不好，直接决定了技能会不会在合适的时机被调用。
三、操作步骤
步骤 1：确认技能存放位置
Claude Code 会从以下位置读取技能（以官方文档当前说明为准）：
- 个人技能：用户目录下的
~/.claude/skills/，对你所有的项目都生效； - 项目技能：项目根目录下的
.claude/skills/，跟随项目代码一起提交，团队成员共享。
新手建议先在某个练习项目里创建项目级技能，方便调试，也不会影响其他项目。
cdyour-projectmkdir-p.claude/skills/commit-message步骤 2：编写 SKILL.md
以“按团队规范编写 Git 提交信息”为例，创建.claude/skills/commit-message/SKILL.md：
--- name: commit-message description: 按团队约定生成 Git 提交信息。当用户要求提交代码、编写 commit message 或整理变更说明时使用。 --- # 提交信息规范 ## 格式 <类型>(<范围>): <简短描述> 类型只能是：feat、fix、docs、refactor、test、chore。 ## 规则 1. 简短描述不超过 50 个字符，使用中文，不加句号； 2. 如果改动涉及多个模块，范围写主要模块； 3. 正文说明“为什么改”，而不是重复“改了什么”； 4. 提交前先运行 git diff --staged 查看实际改动，不要凭猜测写。 ## 示例 fix(login): 修复验证码过期后无法重新获取的问题几点说明：
- description 同时写清“做什么”和“何时用”，并包含用户可能说出的关键词，比如“提交代码”“commit message”；
- 正文用清晰的列表写规则，避免长篇大论；
- 给出一个正例，比十条抽象规则更容易让模型理解。
步骤 3：（可选）添加参考文件和脚本
如果规范很长，可以把细节拆到reference.md，在SKILL.md里写一句“详细的范围命名表见 reference.md”。模型需要时才会去读，节省上下文。
如果有固定的检查逻辑，比如校验提交信息长度，也可以放一个脚本到scripts/目录，并在正文中说明何时运行。脚本执行的结果比让模型“目测”更可靠。
步骤 4：测试技能是否生效
重新启动 Claude Code 会话，然后用自然语言提出相关请求，例如：
我改好了登录模块的 bug，帮我写一条提交信息。观察 AI 是否按照你定义的格式输出。如果没有生效，优先检查：
- 文件名是否是大写的
SKILL.md； - YAML 头信息是否用
---正确包裹； - description 是否和你的请求相关。
步骤 5：迭代优化
技能写好后，在真实工作中多用几次。发现 AI 仍然犯某类错误时，就把对应规则补进SKILL.md。这和带新同事很像：规范文档是在一次次纠错中完善起来的。
进阶：写好 description 的几个思路
前面提到，技能是否会被调用，很大程度上取决于 description。下面用对比的方式说明。
不够好的写法：
description:提交信息工具问题在于只有名词，既没说明能做什么，也没说明在什么情况下使用，模型很难把用户的请求和它对应起来。
更好的写法：
description:按团队约定生成 Git 提交信息，包括类型、范围和简短描述。当用户要求提交代码、写 commit message、整理本次改动说明时使用。改进点有三个：第一，说明了具体产出；第二，列出了触发场景；第三，包含了用户可能使用的不同说法。
另外，如果多个技能的描述过于相似，模型可能会选错。比如“代码评审规范”和“提交信息规范”都提到“代码改动”，就应该在描述中写清各自的边界，例如“仅在用户请求评审或检查代码质量时使用”。
还有一个小习惯：每次新增技能后，用三到五种不同的说法测试一遍，记录哪些说法能触发、哪些不能，再据此调整描述。这个过程花不了多少时间，却能明显提高技能的命中率。
四、哪些场景适合写成技能包
- 框架最佳实践：例如前文提到的 SwiftUI 规范，或团队内部 React 组件写法；
- 固定格式产出：周报、接口文档、提交信息、测试用例模板；
- 公司内部流程：发版检查清单、代码评审要点；
- 领域知识：特定行业的术语表、数据字段说明；
- 重复的多步操作：例如“先跑测试、再格式化、再生成变更日志”。
判断标准很简单：如果你发现自己在不同对话里反复向 AI 解释同一件事，它就值得写成技能。
五、常见问题 FAQ
Q1：Skill 和项目里的 CLAUDE.md 有什么区别？
CLAUDE.md 通常在会话开始时就加载，适合放项目的全局背景；Skill 按需加载，适合放只在特定任务中才需要的详细规范。两者可以配合使用。
Q2：技能会自动执行脚本吗？安全吗？
技能里的脚本由 AI 通过工具调用执行，仍然受 Claude Code 的权限设置约束。使用他人分享的技能前，务必先阅读其中的脚本内容，不要安装来源不明的技能。
Q3：一个技能写多长合适？
官方建议保持SKILL.md精简，把大段参考资料拆到单独文件。正文过长会占用上下文，也会让关键规则被淹没。
Q4：技能可以在其他工具里用吗？
Agent Skills 的格式已经被多个编程助手采纳，但具体支持情况和存放路径以各工具的官方文档为准。
Q5：description 写成英文还是中文？
都可以。关键是与用户实际的提问方式匹配。如果团队主要用中文提问，用中文写描述并包含常见说法即可。
六、实用技巧
- 一个技能只做一件事：“提交信息规范”和“代码评审规范”分成两个技能，比合在一起更容易被准确调用；
- 用祈使句写规则：“必须……”“不要……”，比“建议考虑……”更明确；
- 写反例：列出 AI 常犯的错误，例如“不要使用已废弃的某某接口”；
- 纳入版本管理：项目技能放在仓库中，规范变更时通过代码评审更新；
- 定期清理：框架升级后，及时删除过时规则，避免误导模型。
七、总结
Agent Skills 的思路并不复杂：把经验写成文件，让 AI 按需读取。创建文件夹、写好 SKILL.md 的名称和描述、给出清晰规则和示例、在真实任务中迭代，就能让 AI 越来越符合你的工作习惯。与其等待更强的模型，不如先把自己积累的经验交给它。
参考资料
- Claude Code 官方文档：Agent Skills 章节
- Anthropic 工程博客关于 Agent Skills 的介绍文章
- X 用户 @GitHub_Daily 关于 SwiftUI Agent Skill 的分享
- X 用户 @myldao 关于“给 AI 配老手经验”的讨论
