agents-debug
An agent skill by aws, from aws/agent-toolkit-for-aws. Tags: ai, cli, debugging, logs, troubleshooting.
What it does
Use when your agent or environment is broken — wrong answers, errors, timeouts, tool failures, or CLI issues. Reads traces and logs to diagnose root causes. Also checks prerequisites when the CLI itself isn't working. Triggers on: "agent not working", "wrong answer", "agent error", "tool call failing", "debug agent", "check logs", "read traces", "broken", "500 error", "424 error", "model access denied", "command not found", "stuck in DELETING", "maxVms exceeded", "cold start diagnosis", "cold start slow", "agentcore create error", "create failed", "exit code 7", "connection refused local dev". Not for deploy failures — use agents-deploy. Not for performance tuning without errors — use agents-optimize. Not for VPC configuration — use agents-build. Not for observability setup or missing logs — use agents-optimize.
Install
With the skills CLI, which installs into Claude Code, Codex, Cursor and other agents:
npx skills add aws/agent-toolkit-for-aws --skill agents-debugOr copy the skill folder into Claude Code's skills directory by hand (~/.claude/skills for every project, or .claude/skills inside one):
git clone --depth 1 https://github.com/aws/agent-toolkit-for-aws
cp -r agent-toolkit-for-aws/plugins/aws-agents/skills/agents-debug ~/.claude/skills/agents-debugSafety box score
Grade D, elevated risk: 47 of 100 risk points, rated 2026-10-12. The grade rates what the skill and its scripts can reach on the machine of whoever installs it, across eight categories from shell execution to secrets access. How the score works.
This skill is a mostly read-only debugging helper for AgentCore, but it reaches into AWS traces, logs, IAM, and local process state to diagnose failures. The main risks are exposure of sensitive runtime data and a few fix commands that install software system-wide or run with elevated privileges, including one remote `curl | sh` installer.
| Category | Level | Why |
|---|---|---|
| Code & shell execution | 3 (high) | The skill repeatedly runs shell and CLI commands, and `references/doctor.md` includes a high-risk remote installer pipeline: `curl -LsSf https://astral.sh/uv/install.sh | sh`. |
| Network access | 2 (moderate) | It contacts external services for diagnostics (`agentcore traces/logs`, `aws logs tail`, `aws sts`, `aws bedrock`) and also downloads software from the internet, so data leaves the machine to AWS and public hosts. |
| Filesystem reach | 1 (low) | It reads local project and CLI state such as `agentcore/agentcore.json` and `agentcore/.cli/logs/dev/*.log`, and suggests sourcing `~/.bashrc` or `~/.zshrc`. |
| Secrets & credentials | 2 (moderate) | The core workflow reads traces and logs from AWS (`agentcore traces get`, `agentcore logs`, `aws logs tail`), which can contain prompts, tool inputs, tokens, or other sensitive runtime data. |
| Privilege & persistence | 3 (high) | `references/doctor.md` includes system-wide installs and service control, such as `npm install -g @aws/agentcore` and `sudo systemctl start docker`, which can change machine-wide state. |
| Instruction hijack surface | 0 (none) | There is no hidden prompt injection or instruction to ignore higher-level rules; the skill only directs the agent to inspect diagnostics and follow explicit CLI steps. |
| Irreversible actions | 0 (none) | The skill diagnoses problems and suggests manual fixes, but it does not itself deploy, publish, delete, or message external systems. |
| Transparency | 0 (none) | All shipped files are plain markdown and readable; there are no binaries, minified blobs, or decoded-at-runtime code. |
Before installing
- Read `references/doctor.md` first; it contains `curl | sh`, global installs, and a `sudo systemctl start docker` step.
- Decide whether you are comfortable with the skill reading CloudWatch traces/logs from your AWS account (`agentcore traces get`, `agentcore logs`, `aws logs tail`).
- If you use the Docker or global-install paths, try them in a disposable or least-privileged account first.
Rated 2026-10-12 by an automated review of 2 files from the skill's repository.
Source
- Repository
- aws/agent-toolkit-for-aws (all skills from this repository)
- Path
- plugins/aws-agents/skills/agents-debug/SKILL.md
- Branch
- main
- Collection
- aws-agents
- Updated
- 2026-09-19
Related skills
- app-platform-troubleshooting — Debug running App Platform applications by accessing containers, analyzing logs, running diagnostics, and applying fixes.
- troubleshooting-application-failures — Troubleshoots failing applications by discovering and analyzing CloudWatch log groups to identify error patterns, root causes, and actionable solutions.
- debugging-wizard — Parses error messages, traces execution flow through stack traces, correlates log entries to identify failure points.
- aws-observability — Builds, configures, debugs, and optimizes AWS observability with CloudWatch (Log Insights, Metrics, Alarms, Dashboards, EMF), X-Ray, CloudTrail.
- investigating-incidents-with-aws-devops-agent — Run a deep root-cause investigation on the AWS DevOps Agent.
- address-sanitizer — Builds and runs code under AddressSanitizer to catch buffer overflows, use-after-free, and other memory errors during fuzzing or tests.