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

88%

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

82%Weight 40%Scale 1-5

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

A thorough, highly actionable debugging skill with executable commands and code for every common symptom and strong workflow sequencing. Its main limitation is length: most diagnostic detail lives inline in SKILL.md, which keeps navigation easy but pushes against the progressive-disclosure ideal of splitting bulk detail into reference files.

Suggestions

Consider extracting the longer, less-frequent symptom sections (e.g., streaming keepalive, merged-traces/X-Ray sampling, DELETING-stuck runtime) into reference files under references/ and linking to them from a compact symptom index, to slim the SKILL.md body.

Add explicit validate→fix→retry feedback loops to the diagnosis branches that currently end at a fix command, so each symptom path has a verification step confirming the issue is resolved.

Tighten a few explanatory paragraphs (e.g., the cross-region inference profile prose in the 'model access denied' section) into terser bullet form to recover token budget without losing the AgentCore-specific facts.

Dimension	Reasoning	Score
Conciseness	The body is information-dense and avoids explaining concepts Claude already knows; nearly every section gives AgentCore-specific commands or platform behavior (e.g., the ~10s CloudWatch latency note, maxVms reclamation semantics). It is long, but the length reflects breadth of symptoms rather than padding, placing it above score 3 yet short of the fully lean score 5.	4 / 5
Actionability	Abundant copy-paste-ready, executable guidance throughout: `agentcore traces list/get`, `aws iam simulate-principal-policy`, Python keepalive streaming code, Dockerfile CMD examples, and IAM JSON policy blocks cover the common cases concretely.	5 / 5
Workflow Clarity	A clear Step 0→Step 4 process with a version-gate checkpoint ('If the version is older...run agentcore update before proceeding') and ordered fix sequences (e.g., maxVms 'try in this order', port diagnosis order). It falls short of score 5 because some diagnosis branches lack an explicit validate-then-retry feedback loop after applying a fix.	4 / 5
Progressive Disclosure	Well-organized with clear section headers and a real one-level-deep reference ([references/doctor.md] exists and is self-contained) for the environment-checklist concern. It stops at 4 rather than 5 because the bulk of symptom-by-symptom diagnosis is inlined in SKILL.md rather than split into per-symptom reference files, though this is partly justified by decision-time need.	4 / 5
	Total	17 / 20 Passed

Description

95%Weight 40%Scale 1-5

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 high-quality description that clearly states what the skill does, when to use it via a rich set of natural trigger phrases, and where not to use it via explicit handoffs to sibling skills. The only minor gap is a narrower action-verb list rather than a fully comprehensive enumeration of capabilities.

Dimension	Reasoning	Score
Specificity	Names the domain and several concrete actions ('Reads traces and logs to diagnose root causes', 'checks prerequisites when the CLI itself isn't working'), but the action list is focused rather than comprehensive. It sits above score 3 (which expects only 1-2 actions) but below score 5's comprehensive multi-action coverage.	4 / 5
Completeness	It explicitly answers both what ('Reads traces and logs to diagnose root causes', 'checks prerequisites') and when ('Use when your agent or environment is broken', plus a concrete 'Triggers on:' list), with explicit 'Not for' exclusions matching the score 5 anchor.	5 / 5
Trigger Term Quality	The 'Triggers on:' list is extensive and uses natural user phrasing ('agent not working', 'wrong answer', 'debug agent', 'check logs', 'read traces', 'stuck in DELETING', 'exit code 7', 'connection refused local dev'), covering synonyms and error-specific terms users would actually say.	5 / 5
Distinctiveness Conflict Risk	A clear debugging niche with explicit conflict-avoidance routing ('Not for deploy failures — use agents-deploy', 'Not for performance tuning — use agents-optimize', 'Not for VPC configuration — use agents-build'), minimizing the chance of triggering for the wrong skill.	5 / 5
	Total	19 / 20 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: 8ea26bd

Reviewed: 4 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.