CloudWatch Debugger Skill

Give Claude Code superpowers to monitor and debug your AWS infrastructure

One command to discover your infra. Natural language to debug it.

Getting Started · Commands · How It Works · Contributing

---

What is this?

A Claude Code skill that connects Claude to your AWS CloudWatch logs. Instead of copy-pasting AWS CLI commands, just tell Claude what's wrong:

/cloudwatch 500 errors in the last hour

Claude queries the right log groups, analyzes the results, saves the output, and gives you a diagnosis — all in seconds.

Features

Auto-Discovery Run /cloudwatch configure and the skill automatically discovers your log groups, ECS clusters, alarms, and region. No manual setup.	Smart Debugging Describe the problem in natural language. Claude picks the right log group, builds the query, and traces the root cause.
Health Monitoring Check system status, alarm states, error trends, and latency metrics without leaving your terminal.	Audit Trail Every query result is saved to a timestamped file. Full traceability for incident reviews.

Getting Started

Prerequisites

• Claude Code installed
• AWS CLI configured with valid credentials

Install

git clone https://github.com/torrresagus/cloudwatch-debugger-skill .claude/skills/cloudwatch

Configure

# In Claude Code
/cloudwatch configure

That's it. The skill discovers your AWS infrastructure and generates a config.json automatically.

Commands

Debugging (reactive)

Command	What it does
/cloudwatch <problem>	Describe any issue in natural language
/cloudwatch 500 errors in the last hour	Find HTTP 500s in backend logs
/cloudwatch OAuth callback failures	Debug authentication issues
/cloudwatch why are requests blocked by WAF	Check WAF blocked requests
/cloudwatch trace request abc-123	Trace a request by correlation ID
/cloudwatch check ECS crashes today	Find stopped/failed ECS tasks

Monitoring (proactive)

Command	What it does
/cloudwatch status	Quick health check — errors, alarms, ECS, CPU/memory
/cloudwatch report	Error trends, p95 latency, top affected endpoints
/cloudwatch alarms	All alarm states (OK / ALARM / INSUFFICIENT_DATA)
/cloudwatch diff	Compare error rates between two time windows

Setup

Command	What it does
/cloudwatch configure	Auto-discover AWS infrastructure
/cloudwatch configure --region eu-west-1	Configure for a specific region

How It Works

/cloudwatch 500 errors in the last hour
         |
         v
+-----------------------+
|  1. Read config.json  | <- log groups, clusters, region
+----------+------------+
           |
           v
+-----------------------+
|  2. Pick log group    | <- matches problem to the right logs
+----------+------------+
           |
           v
+-----------------------+
|  3. Query CloudWatch  | <- Logs Insights or filter-log-events
+----------+------------+
           |
           v
+-----------------------+
|  4. Save to file      | <- logs/20260314_143022_500_errors.txt
+----------+------------+
           |
           v
+-----------------------+
|  5. Analyze & report  | <- root cause, fix suggestion
+-----------------------+

Project Structure

cloudwatch-debugger-skill/
├── SKILL.md                      # Core skill — workflow + command dispatch
├── config.json                   # Auto-generated by /cloudwatch configure
├── scripts/
│   └── configure.sh              # AWS infrastructure auto-discovery
├── references/
│   ├── scenarios.md              # Debugging query templates
│   ├── recipes.md                # Logs Insights query recipes
│   └── monitoring.md             # Monitoring command templates
└── examples/
    └── config.example.json       # Example config for reference

IAM Permissions

The minimum IAM permissions needed:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "logs:DescribeLogGroups",
        "logs:FilterLogEvents",
        "logs:StartQuery",
        "logs:GetQueryResults",
        "ecs:ListClusters",
        "ecs:ListServices",
        "ecs:DescribeServices",
        "ecs:ListTasks",
        "ecs:DescribeTasks",
        "cloudwatch:DescribeAlarms",
        "cloudwatch:GetMetricStatistics",
        "sts:GetCallerIdentity"
      ],
      "Resource": "*"
    }
  ]
}

Tip: All ECS and CloudWatch Metrics permissions are optional. The skill works with just the logs:* permissions — it gracefully skips what it can't access.

Configuration

After configure, you get a config.json that you can customize:

Field	Description
aws_cli	Path to AWS CLI binary
region	AWS region
default_log_group	Which log group to query when not specified
log_groups	All discovered log groups with category and purpose
ecs	ECS clusters and services
alarms	CloudWatch alarms
output_dir	Where log files are saved (default: logs/)

config.json contains your account ID — it's .gitignored by default.

Contributing

PRs are welcome! The main branch is protected — direct pushes are not allowed. To contribute:

1. Fork the repo
2. Create a feature branch (git checkout -b my-feature)
3. Commit your changes
4. Open a Pull Request against main
5. Wait for review and approval (at least 1 approving review is required)

Ideas for contributions

• Multi-region support — query across regions
• AWS X-Ray integration — distributed tracing
• Terraform auto-detection — read infra context from .tf files
• More AWS services — Lambda, API Gateway, Step Functions, SNS
• Smarter log format detection — auto-detect JSON vs plaintext vs nginx
• Richer reports — ASCII charts, trend analysis, anomaly detection

License

MIT — use it, fork it, improve it.