troubleshooting-application-failures – 应用故障排查 Skill

Skill 详细介绍

aws/agent-toolkit-for-aws#troubleshooting-application-failures 是 AWS 官方仓库 agent-toolkit-for-aws 中的一个专项 Skill，名称可以识别为 troubleshooting-application-failures，直译即“应用程序故障排查”。

它不是一个独立运行的软件，也不是一个可执行程序。它的本质是一套面向 AWS 应用程序故障排查的 Agent 能力包（Skill），安装后让 AI Agent 具备按 AWS 官方排查思路来协助定位应用故障的能力。

它主要解决什么问题

当应用程序部署在 AWS 上出现异常——例如服务无响应、请求失败、延迟升高、任务失败、日志报错、资源异常——传统做法是人工逐项翻控制台、查日志、比对配置。这个 Skill 的价值在于：把 AWS 应用故障排查的常见路径和方法论交给 Agent，让 Agent 能按照结构化思路协助分析问题、梳理可能原因、给出排查方向和下一步操作建议。

安装后 Agent 增加的能力

– 围绕 AWS 应用程序故障，按照更接近官方实践的思路进行诊断推理
– 协助梳理故障现象、缩小排查范围、列出可能原因
– 给出针对性的排查步骤建议（查什么日志、看哪个服务、验证哪些配置）
– 帮助理解 AWS 相关服务在应用故障场景下的常见行为

它不是什么

– 不是 AWS CLI 的替代品
– 不是自动修复工具：它不会自己登录你的 AWS 账号去改配置、重启服务
– 不是监控或告警系统
– 不保证直接给出根因：故障排查最终仍需结合你真实的账号、架构、日志和指标

适合哪些用户

– 在 AWS 上部署和运维应用程序的开发、运维、SRE 人员
– 使用 AI Agent 辅助云上问题定位的技术团队
– 需要快速获得结构化排查思路、而不是漫无目的地翻文档的人

不适合哪些需求

– 需要一键自动修复生产故障的场景
– 与 AWS 无关的本地应用故障排查
– 需要 Agent 直接访问并操作你的 AWS 生产环境（该 Skill 本身不承担此职责）

Skill 安全评估

总体上，这是一个来源可信度较高的官方 Skill：它归属于 AWS 官方组织在 GitHub 上的 agent-toolkit-for-aws 仓库，而不是来源不明的第三方同名项目。从这个角度看，其供应链风险相对较低。

但“来源可信”不等于“零风险”。实际是否安全，取决于它在你的环境中被赋予什么权限，以及你用它做什么。

需要重点关注的风险点

– 权限范围：如果 Agent 在运行时同时具备 Shell、文件写入、网络访问甚至 AWS 凭证权限，那么无论 Skill 本身多“安全”，真正决定风险的是这些权限。故障排查类任务常常需要读取日志、配置文件、环境信息，因此 Agent 可能接触到敏感内容。
– 凭证与敏感信息：应用故障排查过程中，日志和配置里可能包含密钥、Token、连接串、内部地址。如果 Agent 把这些内容发送到外部模型服务，存在信息外泄风险。
– Prompt Injection：如果排查过程中 Agent 会读取日志、报错信息、第三方返回内容，这些内容里可能被植入恶意指令。对输入内容保持警惕。
– 改动风险：如果 Agent 具备对 AWS 资源或代码的写权限，排查过程中可能被诱导执行修改操作。建议排查阶段以只读为主。

降低风险的实操建议

– 排查阶段尽量给 Agent 只读权限，避免直接对生产环境做写操作
– 如果只是需要 Skill 协助分析故障、给建议，可以关闭 Agent 的自动执行 Shell 权限，由你手动执行命令
– 使用最小权限的 AWS 凭证，不要用管理员级别的长期凭证
– 日志和配置在交给 Agent 前，先去掉或脱敏密钥、Token 等敏感字段
– 不要在生产环境直接让 Agent 自动执行修复动作，先确认再执行

该 Skill 适合作为“诊断辅助”，不适合被当成“自动运维执行器”。把它定位成给思路、给方向的助手，风险是可控的。

Skill 使用要求

一、Agent / 客户端

该 Skill 来自 AWS 官方 agent-toolkit-for-aws 仓库。目前公开资料没有提供一份完整的第三方 Agent 兼容清单，因此以下区分“官方定位”与“通常兼容”。

– 官方面向的是支持 Agent Skill 机制的 Agent 环境。具体以该仓库当前说明为准。
– 从 Agent Skill 的通用工作方式看，在支持 Skills、自定义 Skill 或类似指令加载机制的环境中，通常也可以尝试在 Claude Code、Codex、Cursor、Trae、OpenClaw、WorkBuddy 等主流 AI Agent 中使用。
– 不同 Agent 的 Skill 加载方式、目录结构、触发机制可能不同，兼容程度也不一样，具体以对应 Agent 当前版本为准。

如果你主要在某个特定 Agent 里使用，最稳妥的方式是先在该 Agent 中确认它是否支持加载此类 Skill。

二、运行环境 / 依赖

这个 Skill 用于故障排查辅助，本身是否强制需要某套运行时，取决于你使用它的方式以及承载它的 Agent。

| 项目 | 要求 |
|—|—|
| Agent | 支持 Skill 加载机制的 AI Agent |
| 网络 | 通常需要，因为 Agent 调用模型服务；是否访问 AWS 取决于你的实际排查流程 |
| AWS 环境 | 排查对象是 AWS 上的应用时才有意义 |
| AWS CLI / SDK | 不是该 Skill 本身的硬性要求；是否使用取决于你的排查方式 |

官方资料未明确列出必须固定的 Node.js、Python 版本等硬性依赖，此处不臆测。若你的 Agent 或工作流本身需要这些环境，按对应工具的要求准备即可。

三、权限

– 文件读取：可选。排查时可能需要读取日志、配置文件。
– Shell：可选。是否开放取决于你是否让 Agent 直接执行命令。关闭后仍可让 Agent 只给建议。
– 网络：通常需要，用于 Agent 与模型服务通信。
– AWS 访问权限：可选，且强烈建议按最小权限、只读方式授予。

排查阶段推荐：文件读取开启，Shell 谨慎开启，AWS 凭证用只读、最小权限。

四、账号 / API Key

需要区分两件事：

1. Skill 本身：不需要你额外提供账号或 API Key。
2. 排查对象与运行环境：
– 如果你让 Agent 去访问 AWS 资源，则需要相应的 AWS 凭证（按最小权限配置）。
– 你使用的 AI Agent 本身可能需要其模型服务的 API Key，这与 Skill 无关，属于 Agent 层面的要求。

不要把“Agent 需要模型 Key”和“Skill 需要 AWS 凭证”混为一谈。

最小使用条件

1. 一个支持 Skill 加载机制的 AI Agent
2. 一个 AWS 上的应用故障作为排查对象
3. 网络（用于 Agent 通信）
4. 如需 Agent 实际访问 AWS，则准备最小权限的只读凭证

Skill 安装、使用与卸载教程

一、安装

本页面已单独提供该 Skill 的安装指令，直接复制本页面提供的安装指令，粘贴到对应 Agent 或终端执行即可。

如果你不确定自己用的 Agent 该怎么装，可以直接问当前 Agent：

如何安装 aws/agent-toolkit-for-aws#troubleshooting-application-failures？

如何在 Claude Code 中安装 aws/agent-toolkit-for-aws#troubleshooting-application-failures？

如何在 Cursor 中安装 aws/agent-toolkit-for-aws#troubleshooting-application-failures？

让当前 Agent 根据它自己的 Skill 加载与管理机制来指导安装，通常比照搬一套通用命令更可靠。

如果该仓库对安装有特殊说明（例如目录放置位置、命名要求），以仓库当前官方说明为准。

二、安装后如何使用

安装后，一般在与 Agent 的对话中直接描述你的 AWS 应用故障即可触发，不需要记忆特定命令。关键是把你掌握的现象说清楚：哪个服务、什么报错、什么时候开始、影响范围、已经试过什么。

适合交给它的任务类型：

– 现象描述后，让 Agent 给出排查方向
– 贴一段报错日志，让 Agent 分析可能原因
– 描述架构，让 Agent 列出需要检查的环节

自然语言使用示例：

使用 troubleshooting-application-failures，帮我分析这个 AWS 上的服务为什么突然返回 5xx。

使用 troubleshooting-application-failures，根据这段 CloudWatch 日志，列出最可能的原因和下一步排查步骤。

使用 troubleshooting-application-failures，我的 ECS 任务反复重启，帮我梳理排查思路。

向 Agent 描述需求时，越具体越好：服务名、时间点、错误码、相关日志、近期变更。信息越全，给出的方向越准。

三、卸载

卸载保持简单即可。不同 Agent 的 Skill 安装位置和管理方式不同：

– 使用对应 Agent / Skill 管理器提供的删除方式，移除该 Skill
– 或者直接问当前 Agent：

如何卸载 aws/agent-toolkit-for-aws#troubleshooting-application-failures？

如果没有统一的卸载命令，直接询问当前 Agent 如何移除通常更稳妥。官方资料未明确提供统一卸载命令时，不要套用来源不明的命令。

常见问题

1. 安装后 Agent 好像没识别这个 Skill，怎么办？

先确认 Agent 是否支持 Skill 加载机制，以及 Skill 是否放到了该 Agent 期望的位置。可以直接问当前 Agent：“我安装的 troubleshooting-application-failures 有没有生效？”让它自检。不同 Agent 的加载方式不同，这是最常见的原因。

2. 可以同时安装到多个 Agent 吗？

可以，只要各 Agent 的 Skill 目录和管理方式互不冲突。它本质上是一份能力包，不绑定单一 Agent。是否同时启用取决于你的使用习惯。

3. Skill 更新后需要重新安装吗？

如果你是通过仓库同步或包管理器安装的，通常以对应管理方式更新即可，不一定需要完整重装。具体以仓库当前说明和你的安装方式为准。

4. 中国大陆使用是否有网络要求？

这个 Skill 涉及 AWS 场景，使用时会涉及 Agent 与模型服务的通信，以及（如需要）对 AWS 的访问。AWS 相关域名在部分地区可能存在网络可达性问题，若排查对象在海外 AWS 区域，网络连通性需要单独确认。

5. 它会不会自己去改我的 AWS 生产环境？

Skill 本身不自动执行修复。真正会不会改动，取决于你给了 Agent 什么权限。排查阶段建议只给只读权限，把“分析”和“执行”分开。

6. 可以关闭 Shell 权限只用它给建议吗？

可以。你可以只让它分析日志、给排查方向，由你自己手动执行命令。这样既能获得结构化思路，又能避免 Agent 直接操作系统或云资源。

7. 它适合生产环境故障排查吗？

适合作为诊断辅助，用来梳理思路、缩小范围、给出方向。不建议把它当成自动修复工具直接作用于生产环境。是否用于生产，关键看你如何控制权限和是否人工确认后再执行。