Skill 开发入门：把“反复说的那段话”变成可复用的 AI 能力

一句话：

MCP = 让 Agent 能连系统；Skill = 教 Agent 怎么把事做好。

一、Skill 到底是什么

my-skill/
├── SKILL.md        # 必需：元数据 + 工作流指令
├── scripts/        # 可选：Python / Bash / Node 脚本
├── references/     # 可选：规范文档、API 说明、知识库
└── assets/         # 可选：模板、图片、配置、样例数据

---
name: pr-review
description: 审查 Pull Request 的 bug、安全风险和代码风格。当用户要求 review 代码、diff 或 PR 时使用。
---

# PR Review

1. 先完整读取 diff，不要只看片段。
2. 按优先级反馈：正确性 > 安全 > 性能 > 风格。
3. 每条问题给出 `file:line` 和修复建议。
4. 最后输出：approve / request-changes + 一句话总结。

二、Skill 适合解决什么问题

• 重复发生：每个月、每周、每次提交都在做
• 有固定套路：先干啥、再干啥、输出什么格式
• 人工总在补指令：你老是对 AI 说“别忘了加测试用例”“按我们团队规范来”

• 代码评审 / Commit 规范 / Changelog 生成
• PDF 抽取、合同校对、报表格式化
• 工单分类、PR 描述撰写、发布前检查
• 团队自有流程：上线 Checklist、安全自查、文案风格约束

• 需要实时查数据库 → 用 MCP / 工具
• 纯一次性问题 → 直接聊天就行
• 逻辑太泛、什么都能干 → 说明还没想清楚边界

三、Skill 开发六步法

1. 找痛点：先有真实任务，再写 Skill

最近我反复教 AI 做的那件事是什么？

• “每次 AI 写 PR 描述都太水”
• “每次处理合同都漏看违约责任条款”
• “每次生成接口文档都不符合公司 OpenAPI 规范”

2. 定边界：只做一件事

一个 Skill 只解决一类问题。

dev-assistant：
- 写代码
- 审 PR
- 发邮件
- 做周报
- 查数据库

pr-description-writer
pdf-invoice-extractor
contract-risk-checker
release-checklist-runner

3. 写 SKILL.md：先写“何时触发”，再写“怎么做”

description: >
  从暂存区 git diff 生成 PR 标题和描述。
  当用户说“写个 PR 描述 / draft a PR / 帮我把这次改动总结一下”时使用。
  不要用于已合并分支、不要编造未出现的改动。

• 先读什么
• 再调什么命令
• 输出什么格式
• 禁止做什么
• 完成前检查什么

4. 把“不稳定步骤”写成脚本

• 涉及精确计算
• 要解析 JSON / PDF / Excel
• 要调 Git、正则、日期、文件路径
• 说错一次就会出事故

scripts/
├── extract_diff.py
├── rank_review_comments.py
└── render_pr_body.py

运行：

python scripts/extract_diff.py --staged

用它的输出来生成 PR 描述，不要自己伪造 diff 内容。

5. 放参考资料，而不是堆正文

references/
├── pr-rules.md
├── api-style-guide.md
└── forbidden-patterns.md

如果需要判断代码风格是否合规，读取 references/pr-rules.md。

6. 测试：别只“看着像对的”

• 3 个应该触发的请求
• 3 个长得像但不该触发的请求
• 1 个边界 case（信息不足、权限不够、文件不存在）

四、一个完整小例子：PR 描述 Skill

pr-description-writer/
├── SKILL.md
├── scripts/
│   └── get_staged_diff.sh
└── references/
    └── pr-style.md

---
name: pr-description-writer
description: 根据 git 暂存区改动生成 PR 标题和描述。当用户要求写 PR 描述、draft PR、总结本次改动时使用。不要用于未暂存改动，不要编造 diff 中没有的内容。
---

# PR Description Writer

1. 运行 scripts/get_staged_diff.sh 获取暂存改动。
2. 如果没有暂存内容，停止并提示用户先 git add。
3. 按 references/pr-style.md 的格式输出：
   - Title：祈使句，≤ 70 字符
   - Summary
   - Changes
   - Testing
4. 只写 diff 里能验证到的内容。
5. 输出前检查：有没有编造文件？有没有漏掉破坏性改动？

#!/usr/bin/env bash
git diff --staged

# PR 风格规范

- 标题用祈使句：Add / Fix / Refactor / Remove
- 不写 “Updated code”
- Changes 按 功能 / 配置 / 测试 分组
- 若含 DB 变更，必须写 Migration 说明

五、Skill 的分发与安装

• 用 npx skills add owner/repo --skill xxx 安装
• 打成 Plugin 分发多个 Skill
• 在 ChatGPT / Codex / Copilot 等支持的平台里共享到工作区

⚠️ Skill 不是“文本”，而是“给 Agent 看的指令 + 可运行脚本”。

装别人 Skill 前，要像装依赖一样看：SKILL.md、scripts、权限、网络访问、敏感信息。

六、好 Skill 的 8 条检查清单

• [ ] 名字和文件夹一致，用 kebab-case
• [ ] description 写清“做什么 + 什么时候用 + 不做什么”
• [ ] 只解决一类问题
• [ ] SKILL.md 短、具体、可执行
• [ ] 稳定逻辑进 scripts/
• [ ] 大段知识进 references/
• [ ] 有触发用例和负例
• [ ] 不索要多余权限
• [ ] 能进 Git、能版本化、能 review

七、Skill 与 MCP、Tool、Agent 的关系

Agent
 ├─ 决策：该不该做、先做哪步
 ├─ Tool / Function Calling：调一个函数
 ├─ MCP：连数据库、邮件、内部系统
 └─ Skill：把“公司/团队/个人的干法”固化下来

Skill 定流程，MCP 取实时数据，Tool 执行动作，Agent 做编排。

八、结语

把老员工脑子里的“经验”、团队文档里的“规范”、脚本里的“保底逻辑”，

变成 Agent 能稳定执行的文件夹。

“我这周第 3 次跟 AI 解释同一套流程了——那就把它写成 Skill。”