适合人群已经在用 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.mdYAML 头信息是否用---正确包裹description 是否和你的请求相关。步骤 5迭代优化技能写好后在真实工作中多用几次。发现 AI 仍然犯某类错误时就把对应规则补进SKILL.md。这和带新同事很像规范文档是在一次次纠错中完善起来的。进阶写好 description 的几个思路前面提到技能是否会被调用很大程度上取决于 description。下面用对比的方式说明。不够好的写法description:提交信息工具问题在于只有名词既没说明能做什么也没说明在什么情况下使用模型很难把用户的请求和它对应起来。更好的写法description:按团队约定生成 Git 提交信息包括类型、范围和简短描述。当用户要求提交代码、写 commit message、整理本次改动说明时使用。改进点有三个第一说明了具体产出第二列出了触发场景第三包含了用户可能使用的不同说法。另外如果多个技能的描述过于相似模型可能会选错。比如“代码评审规范”和“提交信息规范”都提到“代码改动”就应该在描述中写清各自的边界例如“仅在用户请求评审或检查代码质量时使用”。还有一个小习惯每次新增技能后用三到五种不同的说法测试一遍记录哪些说法能触发、哪些不能再据此调整描述。这个过程花不了多少时间却能明显提高技能的命中率。四、哪些场景适合写成技能包框架最佳实践例如前文提到的 SwiftUI 规范或团队内部 React 组件写法固定格式产出周报、接口文档、提交信息、测试用例模板公司内部流程发版检查清单、代码评审要点领域知识特定行业的术语表、数据字段说明重复的多步操作例如“先跑测试、再格式化、再生成变更日志”。判断标准很简单如果你发现自己在不同对话里反复向 AI 解释同一件事它就值得写成技能。五、常见问题 FAQQ1Skill 和项目里的 CLAUDE.md 有什么区别CLAUDE.md 通常在会话开始时就加载适合放项目的全局背景Skill 按需加载适合放只在特定任务中才需要的详细规范。两者可以配合使用。Q2技能会自动执行脚本吗安全吗技能里的脚本由 AI 通过工具调用执行仍然受 Claude Code 的权限设置约束。使用他人分享的技能前务必先阅读其中的脚本内容不要安装来源不明的技能。Q3一个技能写多长合适官方建议保持SKILL.md精简把大段参考资料拆到单独文件。正文过长会占用上下文也会让关键规则被淹没。Q4技能可以在其他工具里用吗Agent Skills 的格式已经被多个编程助手采纳但具体支持情况和存放路径以各工具的官方文档为准。Q5description 写成英文还是中文都可以。关键是与用户实际的提问方式匹配。如果团队主要用中文提问用中文写描述并包含常见说法即可。六、实用技巧一个技能只做一件事“提交信息规范”和“代码评审规范”分成两个技能比合在一起更容易被准确调用用祈使句写规则“必须……”“不要……”比“建议考虑……”更明确写反例列出 AI 常犯的错误例如“不要使用已废弃的某某接口”纳入版本管理项目技能放在仓库中规范变更时通过代码评审更新定期清理框架升级后及时删除过时规则避免误导模型。七、总结Agent Skills 的思路并不复杂把经验写成文件让 AI 按需读取。创建文件夹、写好 SKILL.md 的名称和描述、给出清晰规则和示例、在真实任务中迭代就能让 AI 越来越符合你的工作习惯。与其等待更强的模型不如先把自己积累的经验交给它。参考资料Claude Code 官方文档Agent Skills 章节Anthropic 工程博客关于 Agent Skills 的介绍文章X 用户 GitHub_Daily 关于 SwiftUI Agent Skill 的分享X 用户 myldao 关于“给 AI 配老手经验”的讨论
适合人群已经在用 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.mdYAML 头信息是否用---正确包裹description 是否和你的请求相关。步骤 5迭代优化技能写好后在真实工作中多用几次。发现 AI 仍然犯某类错误时就把对应规则补进SKILL.md。这和带新同事很像规范文档是在一次次纠错中完善起来的。进阶写好 description 的几个思路前面提到技能是否会被调用很大程度上取决于 description。下面用对比的方式说明。不够好的写法description:提交信息工具问题在于只有名词既没说明能做什么也没说明在什么情况下使用模型很难把用户的请求和它对应起来。更好的写法description:按团队约定生成 Git 提交信息包括类型、范围和简短描述。当用户要求提交代码、写 commit message、整理本次改动说明时使用。改进点有三个第一说明了具体产出第二列出了触发场景第三包含了用户可能使用的不同说法。另外如果多个技能的描述过于相似模型可能会选错。比如“代码评审规范”和“提交信息规范”都提到“代码改动”就应该在描述中写清各自的边界例如“仅在用户请求评审或检查代码质量时使用”。还有一个小习惯每次新增技能后用三到五种不同的说法测试一遍记录哪些说法能触发、哪些不能再据此调整描述。这个过程花不了多少时间却能明显提高技能的命中率。四、哪些场景适合写成技能包框架最佳实践例如前文提到的 SwiftUI 规范或团队内部 React 组件写法固定格式产出周报、接口文档、提交信息、测试用例模板公司内部流程发版检查清单、代码评审要点领域知识特定行业的术语表、数据字段说明重复的多步操作例如“先跑测试、再格式化、再生成变更日志”。判断标准很简单如果你发现自己在不同对话里反复向 AI 解释同一件事它就值得写成技能。五、常见问题 FAQQ1Skill 和项目里的 CLAUDE.md 有什么区别CLAUDE.md 通常在会话开始时就加载适合放项目的全局背景Skill 按需加载适合放只在特定任务中才需要的详细规范。两者可以配合使用。Q2技能会自动执行脚本吗安全吗技能里的脚本由 AI 通过工具调用执行仍然受 Claude Code 的权限设置约束。使用他人分享的技能前务必先阅读其中的脚本内容不要安装来源不明的技能。Q3一个技能写多长合适官方建议保持SKILL.md精简把大段参考资料拆到单独文件。正文过长会占用上下文也会让关键规则被淹没。Q4技能可以在其他工具里用吗Agent Skills 的格式已经被多个编程助手采纳但具体支持情况和存放路径以各工具的官方文档为准。Q5description 写成英文还是中文都可以。关键是与用户实际的提问方式匹配。如果团队主要用中文提问用中文写描述并包含常见说法即可。六、实用技巧一个技能只做一件事“提交信息规范”和“代码评审规范”分成两个技能比合在一起更容易被准确调用用祈使句写规则“必须……”“不要……”比“建议考虑……”更明确写反例列出 AI 常犯的错误例如“不要使用已废弃的某某接口”纳入版本管理项目技能放在仓库中规范变更时通过代码评审更新定期清理框架升级后及时删除过时规则避免误导模型。七、总结Agent Skills 的思路并不复杂把经验写成文件让 AI 按需读取。创建文件夹、写好 SKILL.md 的名称和描述、给出清晰规则和示例、在真实任务中迭代就能让 AI 越来越符合你的工作习惯。与其等待更强的模型不如先把自己积累的经验交给它。参考资料Claude Code 官方文档Agent Skills 章节Anthropic 工程博客关于 Agent Skills 的介绍文章X 用户 GitHub_Daily 关于 SwiftUI Agent Skill 的分享X 用户 myldao 关于“给 AI 配老手经验”的讨论
