AI Agent 的 Skill 编写实战指南:从踩坑到精通

my-skill/
├── SKILL.md           # 核心指令文件（必须）
├── scripts/           # 可执行脚本（可选）
├── references/        # 详细参考文档（可选）
└── templates/         # 模板文件（可选）

---
name: weekly-report
description: 生成周报。当用户说"写周报"、"整理本周工作"、"汇报进展"时触发。
---

# ❌ 差
description: 写周报用的

# ✅ 好
description: |
  生成工作周报。触发场景包括：
  - 用户说"写周报"、"整理本周工作"、"汇报本周进展"
  - 用户提到"工作总结"、"weekly report"
  - 每周五下午的工作汇报场景

# ✅ 好的描述会说清楚
description: |
  分析 Excel 销售数据并生成可视化报告。
  输入：Excel 文件路径或数据内容
  输出：分析结论 + 图表 + 建议
  触发词："分析数据"、"做报表"、"数据可视化"

description: |
  管理微信公众号文章发布。
  支持：Markdown 转微信排版、封面图生成、草稿创建、定时发布。
  触发词："发公众号"、"微信文章"、"推文"、"发布文章"
  涉及工具：微信公众号 API、Pillow 图片处理

## 工作流程

### 第一步：收集信息
- 确认本周完成的主要工作（最多 5 项）
- 确认遇到的问题和解决方案
- 确认下周工作计划

### 第二步：整理结构
- 按"完成事项 → 问题与解决 → 下周计划"组织
- 每项工作用一句话概括，再用 2-3 句展开

### 第三步：生成报告
- 控制在 500 字以内
- 重点数据加粗
- 问题部分给出具体解决方案，不要只说"待解决"

## 输出示例

### ✅ 好的周报
> 本周完成用户登录模块开发（含手机号+微信两种方式），上线后注册转化率提升 12%。
> 遇到的问题：微信 OAuth 回调在 iOS 上偶尔失败，排查后发现是 URL 编码问题，已修复。

### ❌ 差的周报
> 本周做了很多工作，完成了一些功能，遇到了一些问题。

## 质量标准

- [ ] 标题在 10-20 字之间
- [ ] 正文不超过 500 字
- [ ] 每项工作都有具体数据或结果
- [ ] 问题部分有解决方案，不能只说"待处理"
- [ ] 语言简洁，不使用"进行"、"开展"等空洞词汇

## 边界情况

- 如果用户没有提供足够信息：先询问，不要自行编造
- 如果本周没有完成任何工作：如实说明，不要硬凑
- 如果涉及敏感数据：脱敏处理后再说
- 如果用户要求的格式与模板不同：优先按用户要求来

# ❌ 建议语气（AI 可能忽略）
建议在写代码前先写测试。

# ✅ 命令语气（AI 大概率遵守）
必须先写测试再写代码。没有测试的代码不允许提交。

## 完成前检查

在提交最终结果前，逐项确认：
□ 标题是否符合字数要求？
□ 是否有具体的数字或数据支撑？
□ 是否去掉了所有"进行"、"开展"等空话？
□ 格式是否符合模板要求？

# ❌ 模糊
分析要深入

# ✅ 明确
每个分析维度至少包含：1 个数据对比、1 个原因分析、1 个改进建议

## 禁止事项

- 不要使用"据悉"、"据了解"等新闻八股开头
- 不要在正文中插入广告或推广内容
- 不要编造数据或案例
- 不要使用超过 3 种颜色的强调方式

---
name: work-report
description: |
  生成工作日报或周报。触发词："写日报"、"写周报"、"整理工作"、"本周汇报"。
  支持日报和周报两种格式，自动根据时间判断。
---

# 工作报告生成

## 流程

1. 询问用户本周/今天的主要工作内容
2. 按"完成事项 → 遇到问题 → 解决方案 → 明日/下周计划"整理
3. 每项工作用【结果+数据】的方式描述

## 格式要求

- 日报 200 字以内，周报 500 字以内
- 用短句，不要用长段落
- 数据加粗，问题用 ⚠️ 标记
- 结尾附一句简短的自我总结

## 示例输出

### 本周工作
1. **完成用户系统重构**，接口响应时间从 800ms 降至 120ms
2. **修复 3 个线上 bug**，其中 1 个是支付回调超时问题
3. ⚠️ 数据库慢查询优化未完成，原因是需要 DBA 配合

### 下周计划
- 完成慢查询优化
- 启动消息队列改造方案设计

---
name: code-review
description: |
  进行代码审查。触发词："review 代码"、"代码审查"、"帮我看看代码"、"CR"。
  检查代码质量、安全性、性能、可维护性。
---

# 代码审查 Skill

## 审查维度

### 1. 功能正确性
- 逻辑是否正确，是否有边界条件遗漏
- 异常处理是否完善
- 返回值/错误码是否一致

### 2. 安全性
- SQL 注入、XSS、CSRF 防护
- 敏感信息是否硬编码
- 权限校验是否完整

### 3. 性能
- 是否有 N+1 查询
- 是否有不必要的循环或重复计算
- 大数据量场景是否考虑分页

### 4. 可维护性
- 命名是否清晰
- 是否有适当的注释
- 函数是否过长（超过 50 行需要拆分）

## 输出格式

按严重程度分类：
- 🔴 严重问题（必须修复）
- 🟡 建议优化（推荐修复）
- 🟢 代码亮点（值得学习）

每个问题给出：位置、问题描述、修复建议、示例代码。

---
name: meeting-notes
description: |
  整理会议纪要。触发词："整理会议"、"会议纪要"、"会议记录"、"记一下会议"。
  输入：会议录音转写文本或会议笔记
  输出：结构化会议纪要
---

# 会议纪要 Skill

## 流程

1. 提取基本信息：时间、参会人、会议主题
2. 按议题分组整理讨论内容
3. 提取所有决策和行动项
4. 生成 3-5 句话的摘要

## 输出模板

### 会议信息
- 主题：
- 时间：
- 参会人：

### 核心摘要
[3-5 句话概括会议最重要的内容]

### 讨论要点

#### 议题 1：[名称]
- 讨论内容
- 结论/决策

#### 议题 2：[名称]
- 讨论内容
- 结论/决策

### 行动项

| 事项 | 负责人 | 截止时间 |
|------|--------|----------|
|      |        |          |

## 注意事项

- 分歧意见要如实记录，不要只记结论
- 行动项必须有明确的负责人和时间
- 如果信息不完整，标注"待确认"而不是编造

# ❌ 这样写没用
帮用户写一篇高质量的产品介绍。

# ✅ 要写具体步骤
1. 先问用户产品的核心卖点是什么
2. 确认目标用户群体
3. 按"痛点 → 解决方案 → 优势 → 案例"结构撰写
4. 每个部分控制在 100 字以内

需求分析 Skill → 方案撰写 Skill → 排版美化 Skill → 发布 Skill

## 环境适配

- 如果是 Linux 系统：使用 apt/yum 安装依赖
- 如果是 macOS：使用 brew 安装依赖
- 如果没有网络：使用本地缓存的包

## 更新记录

- v1.2 (2026-04-28)：增加了边界情况处理
- v1.1 (2026-04-20)：优化了输出格式
- v1.0 (2026-04-15)：初始版本