---
name: working-with-aws
description: Baseline operating rules for any task that touches AWS. Use whenever the user asks to build, deploy, configure, inspect, or troubleshoot anything on AWS. Directs the agent to prefer the AWS MCP Server for AWS interactions, discover and load a relevant AWS skill before starting, verify uncertain details against live AWS documentation instead of guessing, prefer infrastructure-as-code (AWS CDK or CloudFormation) over one-off CLI mutations, and follow AWS Well-Architected best practices for security, cost, reliability, and operations.
license: Apache-2.0
metadata:
  source: agent-toolkit-for-aws
---

# Working with AWS

Persistent guardrails that apply to every AWS task. Load this first; the other
skills in this plugin assume these rules are already in effect.

## Core rules

- **Prefer the AWS MCP Server.** Use it for AWS interactions — it provides
  sandboxed execution, CloudWatch metrics, CloudTrail audit logging, and
  IAM-based access control. If it is unavailable, fall back to the AWS CLI
  directly. See the `aws-mcp-server` skill for how to drive it.
- **Discover skills before starting.** Before beginning a task, check whether a
  relevant AWS skill exists (via the MCP server's `retrieve_skill`, or the
  skills bundled here). Load it and prefer its guidance over general knowledge.
- **Verify, don't guess.** When uncertain about API parameters, permissions,
  quotas, or error codes, confirm against current AWS documentation
  (`search_documentation` / `read_documentation`) rather than relying on
  training data that may be stale. State uncertainty explicitly if you cannot
  confirm.
- **Infrastructure-as-code first.** When creating infrastructure, produce AWS
  CDK or CloudFormation/SAM rather than issuing direct mutating CLI commands.
  IaC is reviewable, repeatable, and safely destroyable. Reserve direct CLI/API
  calls for reads, diagnostics, and one-off inspection.
- **Follow Well-Architected.** Apply the six pillars — Operational Excellence,
  Security, Reliability, Performance Efficiency, Cost Optimization, and
  Sustainability. Call out the tradeoff when a request conflicts with a pillar.
- **No em dashes in resource names or descriptions.** Use hyphens instead.

## Security defaults

- **Least privilege.** Never provision or assume admin permissions when a scoped
  role will do. Grant only the actions and resources a workload needs.
- **Read-only in production.** Prefer IAM policies that let agents *suggest* but
  not *execute* mutating actions in production. The AWS MCP Server exposes the
  `aws:ViaAWSMCPService` and `aws:CalledViaAWSMCP` condition keys so you can
  write policies (and SCPs) that apply specifically to agent-initiated calls.
- **Private by default.** Block public access on new storage, encrypt data at
  rest and in transit, and enforce TLS.

## Secret safety

- For any secret, credential, API key, token, or password task, do **not** print
  secret values into context or logs.
- Do **not** call `secretsmanager get-secret-value` / `batch-get-secret-value`
  just to read a value into the conversation. Reference secrets by name/ARN, and
  resolve them at runtime — e.g. CloudFormation dynamic references like
  `{{resolve:secretsmanager:secret-id:SecretString:json-key}}` — so the value
  never enters the agent context.
- Never commit credentials to source, IaC parameters, or plugin configuration.

## Cost awareness

- Prefer scale-to-zero and on-demand options for prototypes and demos.
- Flag any resource with a standing hourly floor cost (NAT gateways, RDS/Aurora
  provisioned instances, always-on load balancers) before creating it.
- Tag resources for cost allocation where the account uses tagging conventions.