Skip to content

AWS Investigator as a Shared Claude Code Skill

  • Date: 2026-03-16
  • Status: Accepted
  • Tags: tooling workflow ai-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/config to discover all configured profiles
  • Recommends the best profile for the request and confirms before switching
  • Verifies identity with aws sts get-caller-identity before 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 aws CLI 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.