适合人群：已经在用 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.py

SKILL.md 的开头是一段 YAML 头信息（frontmatter），其中最重要的两个字段是：

• name：技能名称，使用小写字母、数字和连字符；
• description：描述这个技能“做什么”以及“什么时候应该使用”。

这里有一个关键机制：渐进式加载。AI 一开始只读取每个技能的名称和描述，判断当前任务是否相关；只有确定需要时，才会读取 SKILL.md 的正文和其他附属文件。这样即使安装了很多技能，也不会一次性占满上下文。

因此，description 写得好不好，直接决定了技能会不会在合适的时机被调用。

三、操作步骤

步骤 1：确认技能存放位置

Claude Code 会从以下位置读取技能（以官方文档当前说明为准）：

1. 个人技能：用户目录下的 ~/.claude/skills/，对你所有的项目都生效；
2. 项目技能：项目根目录下的 .claude/skills/，跟随项目代码一起提交，团队成员共享。

新手建议先在某个练习项目里创建项目级技能，方便调试，也不会影响其他项目。

cd your-project
mkdir -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、整理本次改动说明时使用。

改进点有三个：第一，说明了具体产出；第二，列出了触发场景；第三，包含了用户可能使用的不同说法。

另外，如果多个技能的描述过于相似，模型可能会选错。比如“代码评审规范”和“提交信息规范”都提到“代码改动”，就应该在描述中写清各自的边界，例如“仅在用户请求评审或检查代码质量时使用”。

还有一个小习惯：每次新增技能后，用三到五种不同的说法测试一遍，记录哪些说法能触发、哪些不能，再据此调整描述。这个过程花不了多少时间，却能明显提高技能的命中率。

四、哪些场景适合写成技能包

1. 框架最佳实践：例如前文提到的 SwiftUI 规范，或团队内部 React 组件写法；
2. 固定格式产出：周报、接口文档、提交信息、测试用例模板；
3. 公司内部流程：发版检查清单、代码评审要点；
4. 领域知识：特定行业的术语表、数据字段说明；
5. 重复的多步操作：例如“先跑测试、再格式化、再生成变更日志”。

判断标准很简单：如果你发现自己在不同对话里反复向 AI 解释同一件事，它就值得写成技能。

五、常见问题 FAQ

Q1：Skill 和项目里的 CLAUDE.md 有什么区别？
CLAUDE.md 通常在会话开始时就加载，适合放项目的全局背景；Skill 按需加载，适合放只在特定任务中才需要的详细规范。两者可以配合使用。

Q2：技能会自动执行脚本吗？安全吗？
技能里的脚本由 AI 通过工具调用执行，仍然受 Claude Code 的权限设置约束。使用他人分享的技能前，务必先阅读其中的脚本内容，不要安装来源不明的技能。

Q3：一个技能写多长合适？
官方建议保持 SKILL.md 精简，把大段参考资料拆到单独文件。正文过长会占用上下文，也会让关键规则被淹没。

Q4：技能可以在其他工具里用吗？
Agent Skills 的格式已经被多个编程助手采纳，但具体支持情况和存放路径以各工具的官方文档为准。

Q5：description 写成英文还是中文？
都可以。关键是与用户实际的提问方式匹配。如果团队主要用中文提问，用中文写描述并包含常见说法即可。

六、实用技巧

1. 一个技能只做一件事：“提交信息规范”和“代码评审规范”分成两个技能，比合在一起更容易被准确调用；
2. 用祈使句写规则：“必须……”“不要……”，比“建议考虑……”更明确；
3. 写反例：列出 AI 常犯的错误，例如“不要使用已废弃的某某接口”；
4. 纳入版本管理：项目技能放在仓库中，规范变更时通过代码评审更新；
5. 定期清理：框架升级后，及时删除过时规则，避免误导模型。

七、总结

Agent Skills 的思路并不复杂：把经验写成文件，让 AI 按需读取。创建文件夹、写好 SKILL.md 的名称和描述、给出清晰规则和示例、在真实任务中迭代，就能让 AI 越来越符合你的工作习惯。与其等待更强的模型，不如先把自己积累的经验交给它。

参考资料

• Claude Code 官方文档：Agent Skills 章节
• Anthropic 工程博客关于 Agent Skills 的介绍文章
• X 用户 @GitHub_Daily 关于 SwiftUI Agent Skill 的分享
• X 用户 @myldao 关于“给 AI 配老手经验”的讨论