aws-cli

name	aws-cli
description	Use when interacting with AWS - managing S3, EC2, Lambda, IAM, CloudFormation, ECS/EKS, RDS, DynamoDB, CloudWatch, or any AWS service

AWS CLI

MANDATORY: All AWS CLI commands MUST run in subagents.

Use Task tool with subagent_type: "general". Never run aws directly in your session. AWS operations can be long-running, may require investigation, and must be isolated from your main context. No exceptions.

CLI Structure

aws <service> <command> [options]

Investigation Pattern (for subagents)

You are running in a subagent. Use built-in help to discover commands and options:

1. aws help - List all services
2. aws <service> help - List commands for a service
3. aws <service> <command> help - Full command documentation with all flags

This is the preferred way to learn command syntax rather than guessing.

Essential Flags

Flag	Purpose
--output json	Scriptable output (also: text, table)
--query <expr>	JMESPath filtering
--profile <name>	Use named profile
--region <r>	Specify region
--no-cli-pager	Disable pager (critical for scripts)

REQUIRED: Always specify --profile and --region: Do not rely on defaults or environment variables. Every command must include --profile <name> --region <region> for predictable, explicit behavior.

Profile Discovery

Before running ANY AWS command, discover available profiles:

aws configure list-profiles

Profile selection logic:

1. User specified profile: Use it exactly as given
2. Single profile exists: Use it (no ambiguity)
3. Multiple profiles - infer from context:
   • Task mentions "production/prod" → look for profile containing prod
   • Task mentions "qa" → look for profile containing qa
   • Task mentions "development/dev" → look for profile containing dev
   • Task mentions specific account/environment → match by name
4. Cannot infer confidently: ASK the user - list available profiles and request selection

Example inference:

Available: default, mycompany-dev, mycompany-prod, mycompany-qa
Task: "Check production EC2 instances"
→ Infer: mycompany-prod (contains "prod", matches "production" in task)

When to ask (use Question tool):

• Multiple profiles match (e.g., prod-us, prod-eu when task says "production")
• No profile matches task context
• Task is destructive (delete, terminate, modify) and you want confirmation
• Profile names are ambiguous or don't follow conventions

When NOT to Use

• AWS CDK/SDK: For programmatic access (boto3, JS SDK), use those libraries' docs
• Terraform/Pulumi: Infrastructure-as-code tools have their own patterns
• AWS Console: This skill is CLI-specific
• LocalStack: Different endpoints and behavior

Quick Examples

All commands require --profile <p> --region <r> (omitted below for brevity)

Task	Command
Caller identity	aws sts get-caller-identity
List S3 buckets	aws s3 ls
Describe instances	aws ec2 describe-instances
List functions	aws lambda list-functions
Deploy stack	aws cloudformation deploy --template-file t.yaml --stack-name s
Get secret	aws secretsmanager get-secret-value --secret-id name

JMESPath Query Patterns

# Filter by tag
--query 'Reservations[].Instances[?Tags[?Key==`Name`].Value|[0]==`web`]'

# Extract specific fields
--query 'Reservations[].Instances[].[InstanceId,State.Name]' --output table

# Get first matching item
--query 'Buckets[?starts_with(Name,`prod`)].Name | [0]' --output text

Common Mistakes

• Missing --profile or --region: Commands may target wrong account/region silently
• Running aws directly: Always delegate to subagent via Task tool
• Guessing syntax: Use aws <service> <command> help instead of guessing flags
• Ignoring pager: Scripts hang without --no-cli-pager or AWS_PAGER=""

Rationalization Table

Excuse	Reality
"I'll just run this one command quickly"	AWS commands can hang on pager, trigger rate limits, or need retries. Context isolation protects your main session.
"The default profile/region is fine"	Defaults change, env vars get misconfigured. One wrong-account command can cause outages.
"I remember this syntax"	AWS CLI has 200+ services with dozens of commands each. Memory errors are guaranteed. Use aws help.
"This is a read-only command, it's safe"	Safety isn't the issue—context isolation is. Even describe can reveal you need 5 more commands.
"Subagent overhead is unnecessary"	Subagent launch takes seconds; debugging context pollution takes minutes.
"I can guess which profile to use"	Profile names vary wildly. Run aws configure list-profiles - takes 1 second, prevents wrong-account disasters.
"There's probably only one profile"	Many systems have 5+ profiles. Discovery is cheap; wrong-account commands are expensive.
"Asking the user slows things down"	Running against wrong account is slower. When in doubt, ask.

All of these mean: Delegate to subagent. No exceptions.

Dispatching Subagents

When delegating AWS tasks, include in your subagent prompt:

1. Load the aws-cli skill and review ./gotchas.md (relative to this skill) before running commands
2. Run aws configure list-profiles first to discover available profiles
3. If user didn't specify profile: infer from context or ask using Question tool
4. Always use --profile <name> --region <region> explicitly
5. Use aws <service> <command> help to verify syntax
6. Report findings back

Example dispatch prompt (profile specified):

Check the status of EC2 instance i-0abc123 in us-east-1 using profile 'prod'. Load the aws-cli skill first and check ./gotchas.md. Use explicit --profile and --region flags. Report instance state and any relevant details.

Example dispatch prompt (profile NOT specified):

Check if our production Lambda functions are healthy. Load the aws-cli skill first. Run aws configure list-profiles to discover available profiles. Infer the correct profile from context (look for 'prod' in profile names). If multiple profiles match or none match, ask the user which profile to use. Check ./gotchas.md, use explicit --profile and --region.

Cross-Service Gotchas

See: ./gotchas.md (in this skill's directory) for non-obvious behaviors that cause common errors.

Testing Status

TODO: This skill needs TDD validation per writing-skills guidelines.

Required tests:

1. Pressure scenario: "Urgently check if EC2 instance is running" - verify subagent delegation
2. Pressure scenario: "Quick S3 bucket check" - verify --profile/--region compliance
3. Document baseline rationalizations agents use without skill loaded
4. Verify skill changes agent behavior under pressure