# Aws Troubleshooting

> >

- **Type:** Skill
- **Install:** `agentstack add skill-aws-samples-sample-aws-ops-skills-for-agents-aws-troubleshooting`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [aws-samples](https://agentstack.voostack.com/s/aws-samples)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT-0
- **Upstream author:** [aws-samples](https://github.com/aws-samples)
- **Source:** https://github.com/aws-samples/sample-aws-ops-skills-for-agents/tree/main/aws-troubleshooting

## Install

```sh
agentstack add skill-aws-samples-sample-aws-ops-skills-for-agents-aws-troubleshooting
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AWS Troubleshooting

One skill for all AWS services. Reasoning framework is here; service-specific
facts come from MCP at runtime.

## When to use

Any AWS issue where the console alone is insufficient — status checks, logs,
connectivity, performance, permissions, deployments, state transitions.

## Investigation workflow

### Step 0 — ASK FIRST (before any diagnosis)

MUST:
- Check if critical context is missing before querying or diagnosing:
  - Network issues → need VPC topology, subnet type, NAT/endpoint config
  - Container/task failures → need exit code, error message, logs
  - Connection timeouts → need source, destination, protocol, port
  - Performance issues → need instance type, workload pattern, timeline
- If missing, ASK the user. A wrong diagnosis from assumptions wastes more
  time than a clarifying question.

### Step 1 — Identify and collect

Determine the affected service and resource, then collect initial evidence.

MUST:
- Identify the service, resource ID, and region
- Run the service's `describe-*` / `get-*` APIs to capture current state
- Check for status checks, health checks, or equivalent (service-dependent)
- Check CloudWatch metrics for anomalies in the relevant namespace
- Read `references/stable-guardrails.md` to avoid known misdiagnosis traps

SHOULD:
- Check CloudTrail for recent API calls that may have caused the issue
- Check AWS Health Dashboard for service-level events
- Collect logs (CloudWatch Logs, system logs, console output) if available

### Step 2 — Query real-time documentation

MUST:
- Use `aws-knowledge` MCP `search_documentation` to find current troubleshooting
  guidance for the specific symptom. See `references/mcp-query-patterns.md`
- If the search returns an SOP (`sop_name` field), retrieve it with
  `retrieve_agent_sop` for step-by-step instructions
- For ANY specific number (IOPS, limits, quotas, timeouts, cooldowns):
  query MCP — NEVER rely on memorized values

SHOULD:
- Cross-reference re:Post Knowledge Center articles for the error message
- Check if the service has SSM Automation runbooks (`AWSSupport-Troubleshoot*`)
  that can automate diagnosis

MAY:
- Use `aws-knowledge` `recommend` tool on a relevant doc page to discover
  related troubleshooting content

### Step 3 — Diagnose

MUST:
- Read `references/hallucination-patterns.yaml` before concluding
- State the root cause with specific evidence (API response, metric value, log excerpt)
- Classify severity: CRITICAL (service down) / HIGH (degraded) / MEDIUM (suboptimal)

SHOULD:
- Check blast radius — is only one resource affected, or is it AZ/region-wide?
- Distinguish between AWS-side issues (status checks, service events) and
  customer-side issues (config, permissions, application)

### Step 4 — Remediate and report

MUST:
- Propose immediate mitigation with specific CLI commands
- Propose long-term prevention (alarms, auto-recovery, architecture changes)
- Output structured YAML report (see Output Format below)

SHOULD:
- Verify the fix worked (re-check status/metrics after remediation)

## Output format

```yaml
service: ""
resource: ""
region: ""
root_cause: " — "
evidence:
  - type: 
    content: ""
severity: CRITICAL | HIGH | MEDIUM
blast_radius: ""
mitigation:
  immediate: ""
  long_term: ""
sources:
  - ""
```

## Anti-hallucination rules

1. NEVER state service-specific numbers (IOPS, limits, quotas, defaults) from
   memory. Always query MCP first.
2. Always cite evidence: API response, metric, log excerpt, or MCP doc URL.
3. Read `references/hallucination-patterns.yaml` — these are patterns where
   LLMs consistently get AWS behavior wrong.
4. Read `references/stable-guardrails.md` — these are architectural facts that
   are safe to assert without querying.
5. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.
6. If MCP returns no relevant results, say so explicitly. Do not fabricate guidance.

## References

| File | Purpose |
|------|---------|
| `references/stable-guardrails.md` | Architectural facts that don't change — safe to assert |
| `references/hallucination-patterns.yaml` | Cross-service LLM mistake patterns |
| `references/mcp-query-patterns.md` | How to query aws-knowledge MCP effectively |
| `references/investigation-framework.md` | Detailed Phase 1/2/3 methodology for complex cases |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [aws-samples](https://github.com/aws-samples)
- **Source:** [aws-samples/sample-aws-ops-skills-for-agents](https://github.com/aws-samples/sample-aws-ops-skills-for-agents)
- **License:** MIT-0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-aws-samples-sample-aws-ops-skills-for-agents-aws-troubleshooting
- Seller: https://agentstack.voostack.com/s/aws-samples
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.