AWS Investigator as a Shared Claude Code Skill¶
- Date: 2026-03-16
- Status: Accepted
- Tags:
toolingworkflowai-agents
Context¶
Needed a repeatable, safe way to investigate AWS accounts from any Claude Code session — profile discovery, resource enumeration, S3 analysis, IAM review, cost checks. The same capability existed as a Windsurf skill (windsurf/skills/aws-investigator/SKILL.md) but was not available inside Claude Code. Running raw aws CLI commands ad hoc led to inconsistent approaches and no guardrails against accidental mutations.
Decision¶
Add claude/skills/aws-investigator.md as a Claude Code skill that provides structured, read-only AWS investigation via the /aws-investigator command. The skill mirrors the existing Windsurf version for consistency across tools.
- Parses
~/.aws/configto discover all configured profiles - Recommends the best profile for the request and confirms before switching
- Verifies identity with
aws sts get-caller-identitybefore any enumeration - Runs targeted read-only CLI commands scoped to the investigation request
- Uses CloudWatch metrics for S3 size/count — never recursive listing
- Explicitly refuses write operations without confirmation
Alternatives Considered¶
| Option | Why Rejected |
|---|---|
Ad hoc aws CLI commands in each session |
No consistency, no guardrails, repeated profile-discovery overhead |
| Windsurf skill only | Not available in Claude Code sessions — tooling should be symmetric |
| Full AWS MCP server | Overkill for investigation use cases; read-only skill is sufficient |
Consequences¶
Positive:
- Consistent, safe AWS investigation workflow from any Claude Code session
- Profile discovery and identity verification built in — no manual setup per session
- Read-only guarantee reduces risk of accidental mutations during exploration
- Mirrors Windsurf skill — same mental model across tools
Negative / Trade-offs:
- Requires
awsCLI configured with valid credentials on the host machine - Skill is a prompt/behavior definition only — no actual CLI execution enforcement; relies on Claude following the read-only instruction
Ongoing obligations:
- Keep Windsurf and Claude versions in sync when the investigation workflow changes
- Update allowed profiles section if AWS account structure changes
ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.