agents-debug

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.

Quality

92%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Critical

Do not install without reviewing

Quality

Content

85%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A highly actionable, well-structured debugging skill with excellent command/code coverage, a clear diagnostic workflow, and clean progressive disclosure via doctor.md and a handoff table. Its main weakness is length: explanatory passages and the large inline symptom catalog could be trimmed for token efficiency.

Suggestions

Tighten or relocate the "Reading a trace" section and the merged-traces narrative — these explain concepts Claude already knows and inflate the body without adding actionable value.

Consider moving the rarer symptom playbooks (e.g. streaming keepalive, merged-traces, DELETING-stuck) into a reference file so the SKILL.md body stays a lean diagnostic overview, keeping the most common symptoms inline.

Cut restated framing such as the opening "Diagnose why your AgentCore agent or environment isn't working correctly" which duplicates the frontmatter description.

Dimension	Reasoning	Score
Conciseness	Mostly efficient and packed with actionable commands/code, but at ~31KB it includes explanatory prose Claude already knows (e.g. "A trace shows the full execution path of one agent invocation" and the long merged-traces narrative) and could be tightened without losing clarity.	2 / 3
Actionability	Dense with copy-paste-ready bash commands, Python/Dockerfile snippets, IAM JSON policy fragments, and lookup tables — each symptom ships a concrete fix rather than abstract direction.	3 / 3
Workflow Clarity	A clear sequenced Process (Step 0 problem-type triage → verify CLI version → understand symptom → read traces → diagnose) plus a doctor.md checklist for prerequisite validation; symptom sections each carry their own numbered, ordered fix steps.	3 / 3
Progressive Disclosure	Well-signaled one-level-deep reference to references/doctor.md (verified to exist) with inline links, plus a structured handoff table routing remaining cases to sibling skills' reference files — no deep nesting, easy navigation.	3 / 3
	Total	11 / 12 Passed

Description

100%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, third-person description with concrete capabilities, an explicit "Use when" trigger plus a long natural-language trigger list, and clear disambiguation from sibling skills. It fully satisfies the what/when/distinctiveness bar.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — "Reads traces and logs to diagnose root causes", "checks prerequisites when the CLI itself isn't working" — naming the domain and several specific diagnostic behaviors rather than vague language.	3 / 3
Completeness	Explicitly answers both what (diagnoses root causes by reading traces/logs, checks prerequisites) and when (a "Use when..." clause plus a "Triggers on:" list), satisfying the explicit-trigger requirement.	3 / 3
Trigger Term Quality	Broad coverage of natural phrases users would actually say ("agent not working", "wrong answer", "tool call failing", "check logs", "read traces", "broken", "500 error", "exit code 7", "connection refused local dev"), well beyond a single keyword.	3 / 3
Distinctiveness Conflict Risk	The debugging niche is clearly bounded by four "Not for..." exclusions routing deploy/optimize/build/VPC cases to sibling skills, making mis-triggering unlikely.	3 / 3
	Total	12 / 12 Passed

Validation

81%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 13 / 16 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (722 lines); consider splitting into references/ and linking	Warning
relative_links	Relative link issues: 11 suspicious	Warning
referenced_paths_exist	Referenced path issues: 11 missing	Warning

	Total	13 / 16 Passed

Repository: aws/agent-toolkit-for-aws
Path: plugins/aws-agents/skills/agents-debug/SKILL.md
Commit: 222ce56

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.