agent skill实战：结构设计 + 故障排查实战

前言

本文将使用一个例子"线上故障排查"，结合该例子，来详细讨论一下skill在实战中的应用

skill的组成

text 复制代码

.
├── SKILL.md
├── references/
├── examples/
└── scripts/

SKILL.md：主入口文件
- 这个 Skill 是干什么的
- 什么时候触发
- 先读哪些参考资料
- 按什么顺序执行
- 输出结构是什么
- 哪些行为必须避免
references/：参考资料目录
- 规则和资料分离，维护更清楚
- 主文件不至于写成一坨
- 后面更新局部知识时，不用频繁改主 Skill
examples/：示例目录，这个目录里通常放两类东西：
- 标准输入示例
- 标准输出示例
scripts/：脚本目录

skill实践

下面我们来说一个，线上故障排查的例子

text 复制代码

.
├── SKILL.md
├── references/
│   ├── triage-playbook.md
│   ├── metrics-checklist.md
│   └── output-template.md
├── examples/
│   ├── alert-input.json
│   └── expected-analysis.md
└── scripts/

文件	示例路径	作用
主 skill 文件	`SKILL.md`	定义触发条件、执行流程、边界、输出要求
排障手册	`references/triage-playbook.md`	存放排障原则、先后顺序、常见排查思路
指标检查清单	`references/metrics-checklist.md`	规定看哪些指标、哪些现象该重点关注
输出模板	`references/output-template.md`	统一分析结果结构，避免每次输出漂移
输入样例	`examples/alert-input.json`	给这个 skill 一个标准化输入示例
输出样例	`examples/expected-analysis.md`	演示符合预期的排障分析结果

代码路径： skill实践

使用方式

使用claude code作为载体来使用skill，先将该项目移动到~/.claude/skills/下面
登陆claude code开始使用
得到结果

当使用标准的输入数据

复制代码

{
  "service": "order-service",
  "env": "prod",
  "time_window": "2026-04-24 14:05 ~ 14:12",
  "alert_title": "订单服务 5xx 错误率升高",
  "symptom": "/api/order/create 接口错误率从 0.3% 升到 18%",
  "logs": [
    "2026-04-24T14:06:13 ERROR order-service create order failed: dial tcp 10.21.4.15:3306: i/o timeout",
    "2026-04-24T14:06:14 ERROR order-service query inventory failed: dial tcp 10.21.4.15:3306: i/o timeout"
  ],
  "metrics": {
    "5xx_rate": "0.3% -> 18%",
    "p95_latency": "120ms -> 4.8s",
    "db_connection_timeout": "持续升高",
    "cpu": "无明显异常",
    "memory": "无明显异常"
  }
}

skill返回的答案通常是非常完整的，但是如果不给它这么全的数据的时候，结果会怎样？

提供非标数据

本次不用标准数据，而是非常笼统的数据咨询，看看得到的结果是什么

order-service出现了问题，订单服务 5xx 错误率升高，日志：2026-04-24T14:06:13 ERROR order-service create order failed: dial tcp 10.21.4.15:3306: i/o timeout

成功使用对应skill，开始分析

证据链太少，并不能分析出根因以及对应的解决方案，如果还需要继续排查，就要不断的提供对应的数据

添加数据查询工具

为了让skill在排查的过程中，能够获取到新的数据，在/scripts下添加一个查询工具：获取mysql的状态get_mysql_state
先告诉skill有工具可以调用，在SKILL.md中添加新的参考资料 references/tools.md
在references/tools.md添加脚本使用方式

再来看看效果：

skill启动之时，读取了参考资料，并且获取了mysql是否通畅的证据

function call 与 skill

skill的简单使用已经介绍完毕了，下面来对比一下function call与skill，这俩之间在什么场景下去使用

与之前介绍过的function call ：

进行对比：

	function call	skill
定位	function call更合适出现在底层工具的建设中	skill是ai agent的强力助手
环境依赖	不依赖 Claude Code、openclaw 环境，可作为独立服务部署	需要claude code、openclaw等环境，不能独立存在
优化策略	需要不断修改代码来进行不断优化（不管是流程代码，还是prompt）更像是传统开发流程	通过更新 references 下的 markdown 文档即可优化策略，当然也会有script的优化
最佳场景	自动化、集成到现有系统	ai agent的优秀辅助、结构化分析问题
共同协作	skill 调用 function call 作为工具	function call 参考 Skill 的流程规范

总结

本文介绍了skill的基本自称以及用了一个实际例子作为案例剖析展现了如何使用skill

再次对比了function call与skill，在各自对应的环境起到的作用

联系我

联系我，做深入的交流

至此，本文结束

在下才疏学浅，有撒汤漏水的，请各位不吝赐教...