Agent Skills 实战：把经验写成 AI 可复用的工作流
提示词解决一次对话，Skill 沉淀一套可以反复执行的能力。Agent Skills 是一种开放的目录格式：用 SKILL.md 描述触发条件和工作流程，还可以携带脚本、参考资料与模板。
一、Skill、Tool、MCP 有什么区别
- Skill：告诉 Agent 应该怎样完成一类任务，是可复用的操作方法。
- Tool：让 Agent 执行一个具体动作，例如查询、转换或写入。
- MCP：让 AI 应用以标准方式发现并连接外部工具和数据。
Skill 是“怎么做”，Tool 是“做一下”，MCP 是“怎么接上这些能力”。
二、创建第一个 Skill
deployment-diagnosis/
├── SKILL.md
├── scripts/
│ └── collect-status.sh
├── references/
│ └── error-map.md
└── assets/
└── report-template.mdSKILL.md 最小示例：
---
name: deployment-diagnosis
description: Diagnose Docker and Nginx deployment failures. Use when a site returns 502, a container restarts, or a service becomes unreachable.
---
# Deployment diagnosis
1. Record the expected URL and last known working time.
2. Inspect container status before restarting anything.
3. Collect the latest 100 log lines and redact secrets.
4. Test the application inside the container.
5. Test the mapped port from the host.
6. Validate the reverse proxy configuration.
7. Report root cause, evidence, safe fix, and rollback step.
Never delete containers, volumes, logs, or configuration without explicit approval.三、description 决定 Skill 会不会被正确触发
系统启动时通常只加载 Skill 的名称和描述；任务匹配后才读取完整说明。因此描述必须同时回答：
- 它能完成什么结果？
- 什么用户表达或场景应该触发？
- 哪些相近任务不属于它？
不要只写“helps with deployment”。更好的描述会明确 Docker、Nginx、502、容器重启等触发场景，同时避免把所有服务器任务都抢过来。
四、渐进式加载为什么重要
- 发现阶段：只加载名称和描述。
- 激活阶段：任务匹配后加载完整
SKILL.md。 - 执行阶段：需要时才读取 references、运行 scripts 或使用 assets。
这样可以同时安装很多 Skill，又不会把全部说明塞进每一次上下文。主文件保持简洁，长篇规范、错误字典和厂商文档放进 references。
五、好 Skill 的七条标准
- 范围单一，完成标准清楚。
- 步骤有顺序，并说明每一步如何验证。
- 危险操作列出审批条件和回滚动作。
- 脚本可重复执行，失败时给出明确错误。
- 引用文件按需加载，不让主说明无限膨胀。
- 模板和输出格式固定，便于审计和复用。
- 用真实表达测试“该触发”和“不该触发”的边界。
六、最容易踩的坑
- 把公司密码、Token 或真实客户数据打包进 Skill。
- 把几十种无关工作塞进一个“万能 Skill”。
- 只描述理想流程，没有异常处理和验证步骤。
- 脚本默认修改或删除数据，没有 dry-run 与确认机制。
- description 太宽，导致无关请求频繁误触发。
- 依赖没有写清版本、操作系统与网络要求。
七、发布前测试清单
[ ] SKILL.md frontmatter 合法
[ ] 名称为小写字母、数字和连字符
[ ] 描述覆盖正确触发词和边界
[ ] 新手能独立完成步骤
[ ] 危险操作需要批准
[ ] 日志和输出不会泄露密钥
[ ] 脚本包含依赖与失败说明
[ ] 至少测试 5 个应触发、5 个不应触发的请求
Responses