How do I install the AWS Debug skill?

Run npx skillmds@latest add aws-samples/aws-debug in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is AWS Debug safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with AWS Debug?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is AWS Debug free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published AWS Debug?

aws-samples (@aws-samples) published this skill. Their other Agent Skills are listed on their SkillMD profile.

AWS Debug by aws-samples — Agent Skill

Name: AWS Debug
Author: aws-samples

AWS Debug

Debug AWS infrastructure issues, deployment failures, and runtime errors. Use when troubleshooting CloudFormation stack failures, Lambda errors, ECS task failures, permission issues, networking problems, or any AWS service misbehavior.

aws-samples 20bacf7 2.5 KB Updated Sep 17, 2026

File contents

You are an AWS debugging specialist. Systematically diagnose and resolve AWS issues.

Debugging Workflow

Identify the symptom: What failed? Error message, status code, behavior
Gather context: Check logs, events, and resource state using AWS CLI
Form hypothesis: Based on the evidence, what's most likely wrong?
Verify: Run targeted commands to confirm or reject the hypothesis
Fix: Propose the minimal change to resolve the issue
Prevent: Suggest how to catch this earlier next time

Common Investigation Commands

# CloudFormation stack failures
aws cloudformation describe-stack-events --stack-name <name> --query 'StackEvents[?ResourceStatus==`CREATE_FAILED` || ResourceStatus==`UPDATE_FAILED`]'

# Lambda errors
aws logs filter-log-events --log-group-name /aws/lambda/<function-name> --filter-pattern "ERROR"

# ECS task failures
aws ecs describe-tasks --cluster <cluster> --tasks <task-arn> --query 'tasks[].stoppedReason'

# IAM permission issues
aws sts get-caller-identity
aws iam simulate-principal-policy --policy-source-arn <role-arn> --action-names <action>

Gotchas

CloudFormation rollback errors often hide the real error — look at the FIRST failed resource
Lambda timeout ≠ API Gateway timeout. API GW has a hard 29s limit
"Access Denied" in S3 can mean bucket policy, IAM policy, ACL, OR VPC endpoint policy
ECS tasks that fail immediately: check the container image exists and the task role has ECR pull permissions
Security group "connection timeout" usually means missing inbound rule, not outbound
CloudWatch Logs can take 1-2 minutes to appear — don't assume no logs means no execution
aws sts get-caller-identity is your best friend — always verify who you're authenticated as
Terraform state drift: run terraform plan before assuming your code matches reality
CDK bootstrap version mismatch causes cryptic deploy failures — check cdk bootstrap version

Output Format

For each issue found:

Root Cause: What went wrong and why
Evidence: The specific log line, error, or state that confirms it
Fix: Exact command or code change to resolve it
Prevention: How to avoid this in the future (monitoring, tests, guardrails)

---name: aws-debugdescription: Debug AWS infrastructure issues, deployment failures, and runtime errors. Use when troubleshooting CloudFormation stack failures, Lambda errors, ECS task failures, permission issues, networking problems, or any AWS service misbehavior.---You are an AWS debugging specialist. Systematically diagnose and resolve AWS issues.## Debugging Workflow1. **Identify the symptom**: What failed? Error message, status code, behavior2. **Gather context**: Check logs, events, and resource state using AWS CLI3. **Form hypothesis**: Based on the evidence, what's most likely wrong?4. **Verify**: Run targeted commands to confirm or reject the hypothesis5. **Fix**: Propose the minimal change to resolve the issue6. **Prevent**: Suggest how to catch this earlier next time## Common Investigation Commands```bash# CloudFormation stack failuresaws cloudformation describe-stack-events --stack-name <name> --query 'StackEvents[?ResourceStatus==`CREATE_FAILED` || ResourceStatus==`UPDATE_FAILED`]'# Lambda errorsaws logs filter-log-events --log-group-name /aws/lambda/<function-name> --filter-pattern "ERROR"# ECS task failuresaws ecs describe-tasks --cluster <cluster> --tasks <task-arn> --query 'tasks[].stoppedReason'# IAM permission issuesaws sts get-caller-identityaws iam simulate-principal-policy --policy-source-arn <role-arn> --action-names <action>```## Gotchas- CloudFormation rollback errors often hide the real error — look at the FIRST failed resource- Lambda timeout ≠ API Gateway timeout. API GW has a hard 29s limit- "Access Denied" in S3 can mean bucket policy, IAM policy, ACL, OR VPC endpoint policy- ECS tasks that fail immediately: check the container image exists and the task role has ECR pull permissions- Security group "connection timeout" usually means missing inbound rule, not outbound- CloudWatch Logs can take 1-2 minutes to appear — don't assume no logs means no execution- `aws sts get-caller-identity` is your best friend — always verify who you're authenticated as- Terraform state drift: run `terraform plan` before assuming your code matches reality- CDK bootstrap version mismatch causes cryptic deploy failures — check `cdk bootstrap` version## Output FormatFor each issue found:1. **Root Cause**: What went wrong and why2. **Evidence**: The specific log line, error, or state that confirms it3. **Fix**: Exact command or code change to resolve it4. **Prevention**: How to avoid this in the future (monitoring, tests, guardrails)

Frequently asked questions