AI Skills实战：给编码智能体编写可复用技能的方法论与模板

用了一段时间智能体之后，团队普遍会遇到同一个瓶颈：同样的事情反复教。每次让 AI 发布版本，都要重新描述一遍「先跑 lint、再跑测试、改版本号、打 tag、按约定格式写 changelog」；换个同事、换个会话，这些流程知识就清零了。Skill（技能）正是为解决这个问题而生的机制——把方法论文写成文件交给智能体，让它随取随用、越攒越强。这篇文章讲清楚怎么写一个真正可复用的 Skill。

Skill 的三段式结构：说明书、方法论、参考附件

一个规范的 Skill 通常由三部分组成，理解它们的分工是写好技能的前提：

组成部分	作用	类比
元信息（name + description）	告诉智能体「这个技能是干什么的、什么时候用」	书的封面与目录
主体（SKILL.md 正文）	承载执行流程、约束与代码模板	操作手册正文
附件（脚本、配置模板）	放不下正文的详细参考资料	附录与光盘

元信息里的 description 是整个 Skill 的「命中开关」：智能体根据用户输入与各技能 description 的语义相似度决定是否加载。所以 description 不能只写「发布技能」，要写成「当用户要求发布、发版、打 tag、生成 changelog 时使用」，把用户真实的说法枚举进去。

SKILL.md 的写作模板

下面是一个可以直接套用的模板，以「团队发布流程」技能为例：

---
name: release-deploy
description: 当用户要求发布版本、发版、打 tag、生成 changelog 时使用
---

# 发布流程

## 执行步骤
1. 运行 npm run lint 与 npm run test，任一失败立即停止并报告
2. 按 semver 询问版本号类型（major/minor/patch），默认 patch
3. 更新 package.json 的 version 字段
4. 依据 git log 中自上次 tag 以来的提交，按「特性/修复/杂项」
   分组生成 CHANGELOG 片段
5. 执行 git tag vx.y.z，附上 changelog 作为 tag 描述

## 约束
- 工作区存在未提交改动时禁止发版，先提示用户处理
- 不要执行 git push，推送由用户手动确认后进行

## 参考
- changelog 格式示例见 ./examples/changelog.md

写主体内容时有四个要点：步骤可执行——每一步都是智能体能直接照做的动作，不要写「按需检查」这种模糊表述；约束前置——把「什么情况下必须停」写在显眼位置，发布类技能的止损约束比流程更重要；幂等友好——假设技能可能被中断后重跑，步骤设计成可以重新进入；附件只放细节——超过 50 行的示例、长配置模板拆成附件文件，正文保持在一屏到两屏，智能体加载正文后按需读取附件，避免一次灌入过多内容。

技能的组织与演进：从个人技巧到团队资产

技能写多了之后，组织方式决定它的长期价值。建议按两层组织：个人技能放全局目录，解决「我自己重复做」的事，如「按我的习惯写 commit message」；团队技能放仓库内 .claude/skills/（或工具对应的约定目录），随代码一起版本管理、随 PR 一起评审，解决「团队重复教 AI」的事，如发布流程、故障排查手册、组件脚手架生成。

团队技能的演进要像对待代码一样严肃：一条流程规则改了，对应的 Skill 必须同 PR 更新，否则技能会逐渐「说谎」——AI 按旧流程操作，比没有技能更危险。可以设一个简单的评审约定：改 scripts/release.sh 的 PR 必须检查 release-deploy 技能是否需要同步。

常见踩坑与规避

第一坑：description 写得太泛（「帮我做事」），导致技能永远不被命中，或者相反写得太窄导致没人记得它存在。第二坑：把技能写成百科全书，正文塞满背景知识却没有可执行步骤——智能体读完还是不知道第一步做什么。第三坑：在技能里硬编码路径与环境变量，换个项目就失效，应该改为在步骤开头先探测或询问。第四坑：技能之间互相复制粘贴大段内容，改一处漏一处，公共内容应该下沉为独立技能或附件，被其他技能引用。

实践清单

1. 每个技能只解决一类问题，description 用用户可能的真实说法来写。
2. 正文控制在两屏内，步骤可执行、止损约束前置，细节放附件。
3. 团队技能入仓库随 PR 评审，流程变更与技能变更强制同 PR。
4. 每月盘点一次技能命中率，长期不被命中的技能改写 description 或合并下线。

Skill 的本质是把「怎么用 AI」变成团队的可维护资产。当你的智能体加载着一套持续演进的技能库时，新同事上手第一天就能继承整个团队的工作方法——这才是智能体时代的正确打开方式。

免责声明

本工具与文章内容仅用于学习测试场景，优化建议仅供参考，请勿直接用于生产环境，由此产生的风险自行承担。