AI Agent Skill 体系实战：从创建到调试，我踩过的 7 个坑（附完整模板）

适合正在用 AI Agent（如 Claude Code、Cursor、WorkBuddy 等）并想自定义技能模块的开发者。
本文不讲理论框架，只讲我实际创建、调试、迭代 Skill 的过程，附可直接复制的模板和踩坑记录。

为什么需要 Skill

用 AI Agent 做重复性任务时，你会发现一个问题：每次都要重新描述需求、重复交代规则、反复纠正输出格式。

比如我每次让 AI 写公众号文章，都要说一遍"标题 12-18 字"“不要震惊体”“结尾加互动引导”“文末标注 AI 辅助完成”。说多了烦，不说又出错。

Skill 的本质就是把这些重复的规则封装成一个可复用的模块。AI Agent 加载 Skill 后，自动知道该怎么做，不用你每次重复。

类比一下：Skill 就像 Shell 脚本——你把一系列命令写成脚本，以后跑一个文件就行，不用每次手动敲。

Skill 长什么样

一个 Skill 的核心就是一个 Markdown 文件（通常叫 SKILL.md），外加一些辅助资源。结构如下：

my-skill/
├── SKILL.md           # 核心指令文件（必须）
├── scripts/           # 辅助脚本（可选）
│   └── validate.py
├── references/        # 参考资料（可选）
│   └── style-guide.md
└── assets/            # 模板/素材（可选）
    └── template.md

SKILL.md 的基本结构：

---
name: my-skill
description: 一句话描述这个 Skill 做什么
trigger: 触发条件（什么时候自动加载）
---

# 技能名称

## 什么时候用
描述触发场景

## 怎么做
具体的执行步骤和规则

## 输出格式
期望的输出结构

## 注意事项
踩坑点和约束

实战 1：创建一个"选题打分" Skill

这是我最早创建的 Skill 之一，用来标准化选题评估流程。

完整 SKILL.md

---
name: topic-scorer
description: 对内容选题进行四维度打分评估
trigger: 用户提到"选题""打分""评估选题"时自动加载
---

# 选题打分 Skill

## 什么时候用
当用户提出一个或多个选题，需要评估是否值得写时。

## 打分维度
对每个选题从 4 个维度打分（各 10 分，总分 40，合格线 30）：

| 维度 | 问的问题 | 评分标准 |
|------|---------|---------|
| 热门度 | 这个话题最近有人搜吗？ | 8-10: 热榜常客；5-7: 有热度但不爆；1-4: 冷门话题 |
| 匹配度 | 跟账号定位契合吗？ | 8-10: 完全契合；5-7: 有关联；1-4: 偏离定位 |
| 差异化 | 别人写过类似的吗？ | 8-10: 几乎没人写；5-7: 有竞品但角度不同；1-4: 大量同质内容 |
| 实操性 | 我有真实经验/代码吗？ | 8-10: 有完整实操经验；5-7: 有部分经验；1-4: 纯理论/搬运 |

## 输出格式
对每个选题输出：
1. 四维度分数表格
2. 总分
3. 是否通过（≥30 分通过）
4. 一句话推荐理由或淘汰原因

## 注意事项
- 不要为了凑分而打高分，宁可严格
- 如果某个维度信息不足，标注"待确认"而不是猜一个分数
- 热门度需要实际搜索验证，不能凭感觉

创建过程

1. 在 ~/.workbuddy/skills/ 下新建 topic-scorer/ 目录
2. 写 SKILL.md 文件
3. 在 AI Agent 中测试：提出一个选题，看它是否按四维度打分
4. 根据输出调整评分标准和格式

实战 2：创建一个"封面图生成" Skill

这个 Skill 的目标是让 AI 自动生成 CSDN 封面图，不用每次手写 PIL 代码。

完整 SKILL.md

---
name: csdn-cover-gen
description: 用 Python PIL 生成 CSDN 文章封面图（深色科技风，1200x630）
trigger: 用户提到"CSDN 封面""封面图""生成封面"时自动加载
---

# CSDN 封面图生成 Skill

## 什么时候用
写完 CSDN 文章后，需要生成配套封面图时。

## 技术要求
- 画布尺寸：1200 x 630（CSDN 推荐比例）
- 背景：深蓝渐变 + 网格装饰
- 字体：微软雅黑（msyh.ttc / msyhbd.ttc）
- 输出：PNG 格式，quality=95

## 元素规范
1. **标题区域**（左上角）：文章标题中文大字 + 副标题
2. **核心指标卡片**（中下）：3-4 个数据卡片（数字+标签）
3. **架构图/流程图**（右侧）：文章核心内容的可视化
4. **标签行**（底部）：3-5 个技术关键词标签
5. **右上角装饰**：文章类型标签

## 代码模板
使用以下函数库（已验证可用）：
- `_get_cn_font(size, bold)` - 获取中文字体
- `draw_rounded_rect(draw, bbox, radius, fill, outline, width)` - 圆角矩形
- `draw_arrow(draw, x1, y1, x2, y2, color, width)` - 箭头

## 注意事项
- 字体路径必须用绝对路径：`C:\Windows\Fonts\msyh.ttc`
- 中文字符不能用 Arial，必须用微软雅黑
- 指标卡片的数字不要编造，用文章中的真实数据
- 文件名与文章标题一致（不含 .md 后缀）

实战 3：创建一个"合规自查" Skill

每篇文章发布前过一遍合规检查，避免踩 CSDN 红线。

完整 SKILL.md

---
name: csdn-compliance-check
description: CSDN 文章发布前合规自查（标题+内容+格式）
trigger: 用户提到"合规检查""自查""能不能发"时自动加载
---

# CSDN 合规自查 Skill

## 什么时候用
文章写完、准备发布之前。

## 检查清单

### 标题检查（P0，一票否决）
- [ ] 包含至少一个技术词汇
- [ ] 无"震惊""惊爆""不得不看""一定要看完"等违规词
- [ ] 无"竟然是""没想到""内幕"等悬念式表述
- [ ] 无错别字/语病
- [ ] 标题与正文内容一致

### 内容检查（P0，一票否决）
- [ ] 无推广引流（二维码/微信号/外部链接）
- [ ] 无非技术内容（小说/休闲/旅游/养生/情感）
- [ ] 无版权风险（破解教程/未授权内容）
- [ ] 无荐股荐彩/诱导投资内容

### 格式检查（P1，建议修改）
- [ ] 英文单词与中文之间有空格
- [ ] 代码块标注了语言类型
- [ ] 表格格式完整
- [ ] 中英文术语大小写正确

### 质量检查（P2，可选优化）
- [ ] 开头说明了读者是谁 + 解决什么问题
- [ ] 有代码/配置/表格等实质性内容
- [ ] 结尾有互动引导
- [ ] 文末标注"本文由 AI 辅助完成"

## 输出格式
逐项列出检查结果：
- ✅ 通过
- ❌ 不通过（附具体位置和修改建议）
- ⚠️ 建议优化（非强制）

Skill 调试：我踩过的 7 个坑

坑 1：SKILL.md 太长，AI 读不完

症状：Skill 写了 500+ 行，AI 执行时经常遗漏后面的规则。

原因：AI 的上下文窗口有限，Skill 作为 system prompt 的一部分，太长会挤占对话空间。

解决：Skill 控制在 200 行以内。超过的拆成多个 Skill，用 trigger 条件按需加载。

坑 2：trigger 条件太宽，每次都加载

症状：设了 trigger: 用户提到"文章"时加载，结果每次聊天都触发。

原因：触发词太常见，误触发率高。

解决：trigger 用更精确的短语。比如改成 trigger: 用户提到"写文章""出稿""写公众号"时加载。

坑 3：Skill 之间规则冲突

症状：同时加载"去 AI 味 Skill"和"排版 Skill"，输出格式乱了。

原因：两个 Skill 都对段落格式有要求，互相矛盾。

解决：给 Skill 设优先级，冲突时高优先级的规则覆盖低优先级的。或者合并成一个 Skill。

坑 4：Skill 里的代码示例过时

症状：Skill 里写的 API 调用方式是旧版的，AI 按旧方式写代码报错。

原因：Skill 创建时的代码示例没有随着依赖库更新而更新。

解决：定期检查 Skill 里的代码示例是否还能跑。或者不在 Skill 里写死代码，只写规则和约束。

坑 5：没有示例，AI 理解偏差

症状：Skill 写了"输出要简洁"，AI 理解成"只写一句话"。

原因："简洁"是主观的，AI 理解和你的预期不一样。

解决：给正例和反例。不只说"输出要简洁"，而是给一个"好的输出"和"不好的输出"对比。

坑 6：Skill 没有版本管理

症状：改了 Skill 的一个规则，发现改坏了，想回退找不到旧版本。

原因：直接修改 SKILL.md 文件，没有备份。

解决：用 Git 管理 Skill 目录，或者每次修改前复制一份旧版本。

坑 7：多人协作时 Skill 冲突

症状：团队成员各自改了同一个 Skill，合并时冲突。

原因：Skill 文件没有模块化，所有规则写在一个文件里。

解决：把 Skill 拆成核心规则（只读）和个人配置（可覆盖）。核心规则团队共享，个人配置各自维护。

Skill 开发最佳实践

实践	说明
先跑通再封装	先手动完成任务，确认流程没问题再写成 Skill
200 行以内	超过就拆分，按需加载
给正例反例	不只说规则，给"对的"和"错的"对比
trigger 精确	用具体短语而不是泛泛的关键词
定期检查	每月看一次 Skill 里的代码示例是否过时
版本管理	Git 或手动备份，方便回退

总结

3 条核心经验：

1. Skill 是"规则封装"，不是"代码封装"。很多人以为 Skill 要写很多代码，其实核心是把你的经验和规则写成 AI 能理解的指令。

2. 先手动再自动化。不要一上来就写 Skill，先手动做几次任务，确认流程和规则没问题，再封装成 Skill。

3. 调试比创建更重要。Skill 写出来只是第一步，真正的价值在调试——根据 AI 的实际输出不断修正规则。

---

你在用 AI Agent 时自定义过 Skill 吗？遇到过什么问题？评论区交流。