How to use the AWS CloudWatch Investigation agent skill

What the skill makes the agent do

Agent skills are folders of instructions that an AI agent loads when a task matches them. This one contains a single file, SKILL.md, which gives the agent a playbook for incident triage on AWS using CloudWatch Logs, Metrics and Alarms.

The skill supplies the method, not the access. The agent still needs its own tools and AWS credentials to run the queries. The skill has no scripts and makes no network calls itself.

• Error spike detection: finds the top errors in a time window, grouped by log stream.
• Latency breakdown: ranks operations by p50, p95 and p99 duration.
• Lambda cold starts: measures init duration and its impact during an incident.
• Memory exhaustion and timeouts: finds out-of-memory events and invocations that hit the timeout.
• Blast-radius narrowing: walks from account to region, service, operation and resource.
• Deploy correlation: checks CloudTrail for deployment events shortly before an alarm fired.
• Metric queries: shows metric math patterns such as error rate as a percentage and latency compared to a baseline.

Install the skill from the ZIP

Download the ZIP for this skill from this page and unzip it. The folder you get contains SKILL.md. Put that folder in one of the locations below so your agent can find it.

For a personal install that applies across your projects, unzip it into ~/.claude/skills/. To limit the skill to one project, unzip it into the .claude/skills/ folder inside that project.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/aws-cloudwatch-investigation/
• Project: .claude/skills/aws-cloudwatch-investigation/ inside your repository

Ask for it with natural requests

You do not need a special command. Describe the problem in plain words that match the skill's description, such as investigating a Logs Insights error spike, a latency increase, or an alarm that may follow a deploy. The agent decides whether the skill applies.

Give the agent the details it needs to scope the work: the alarm name or time it fired, the account and region, and the service or function name if you know it.

• "A CloudWatch alarm fired on payment-processor ten minutes ago. Triage it using the investigation skill."
• "Check whether the ALARM on our API Gateway prod stage lines up with a deployment in the last 30 minutes."
• "Find Lambda functions in us-east-1 with out-of-memory events in the last hour."
• "Narrow down where this latency spike is coming from: account, region, service, then resource."

Examples of what the agent produces

For deploy correlation, the skill defines an output format that records the event, time, actor, resource and a correlation strength. The example in the source shows a Lambda code update about 12 minutes before an alarm, from a CI/CD role, on the same function, rated STRONG.

The skill tells the agent to query CloudTrail Lake for deployment events in the 30 minutes before the alarm. A deploy counts as correlated when it targets the same resource, completed within 15 minutes before the alarm transition, and was made by a CI/CD role rather than a person applying a hotfix.

Requirements and what to prepare

The skill is only useful if the agent can reach your AWS environment. You need an AWS account with CloudWatch Logs, Metrics and Alarms access. For the deployment correlation step you also need CloudTrail or a CloudTrail Lake event data store, since the CloudTrail query uses an event data store ID that you supply.

The agent itself needs AWS access, for example AWS CLI or SDK credentials, to run the queries. The source does not describe any other setup.

• AWS account with CloudWatch Logs, Metrics and Alarms access
• CloudTrail or CloudTrail Lake event data store for deploy correlation
• An agent environment with AWS credentials, such as AWS CLI or SDK credentials

Safety notes: scripts, network and human review

The skill runs no scripts and uses no network. Its files are instructions and query text only. Any reads or writes to AWS happen through the agent's own tools, under the permissions of the credentials you give it, so scope those credentials to read-only access where you can.

The skill is read-oriented guidance. It does not decide on rollbacks or other production changes. During an incident, have a person review any change before it is made. Treat deploy correlation as a heuristic, because it can produce false positives, so do not use its output as a compliance-grade conclusion.

• Use read-only AWS credentials for investigation work.
• Review any production change yourself before it happens.
• Confirm correlations against the previous deploy cycle and other changes in the same window.

Tips for better results

Use the exact alarm transition time when you can. The deploy correlation window is built from that timestamp, so an accurate time makes the CloudTrail search more useful.

Work from the top of the decision tree down. If the alarm spans several accounts or services, the skill points you toward shared dependencies such as networking, IAM or the deployment pipeline before individual resources.

Replace the TARGET placeholders in the metric queries with your own function or API names. The Logs Insights queries use fields such as @duration and @initDuration, which appear in Lambda logs.