| name | shimmy-tool-aws |
| description | Guidance for using, changing, testing, and troubleshooting the AWS CLI shim in this repository, including AWS credential mounts, AWS env forwarding, and non-mutating AWS CLI smoke checks. |
AWS Shim
Use this skill when working with shims/aws, its tests, its docs, or AWS CLI usage through Shimmy.
Files
- Runtime shim:
../../../shims/aws
- User docs:
../../../docs/shims/aws.md
- Tests:
../../../scripts/test-shimmy.sh
- Installer:
../../../scripts/install-shimmy.sh
- README:
../../../README.md
- Contributor guidance:
../../../CONTRIBUTING.md
- Shared prompt:
../../../docs/prompt-shimmy-project.md
Installed Workflow
When this skill is installed outside the Shimmy source checkout, do not rely on the repo-relative Files paths above. Prefer activated commands such as <tool> --version, inspect selected profile state with shimmy status --format manifest, and use SHIMMY_PROFILE_ACTIVE=upstream <tool> --version when validating the upstream profile. Use repo-local paths such as ./shims/<tool> only when intentionally editing or testing source files in the Shimmy checkout.
Current Behavior
- Default image:
public.ecr.aws/aws-cli/aws-cli:2.31.21
- Runtime image override:
AWS_IMAGE
- Documented/conventional image override:
SHIMMY_AWS_IMAGE
- Pull override:
SHIMMY_AWS_IMAGE_PULL=always
- Runtime mode: TTY only when stdin and stdout are terminals
- Mounts:
$PWD to /work$HOME/.aws to /root/.aws:ro when present
- Forwarded env:
AWS_*
- Platform: shared Podman helper resolves
linux/amd64 on Linux and linux/arm64 on macOS
Change Rules
- Preserve the read-only AWS config mount unless the task explicitly changes credential behavior.
- Keep
AWS_* forwarding aligned with AWS CLI native configuration.
- Reconcile the
AWS_IMAGE vs SHIMMY_AWS_IMAGE mismatch deliberately before changing AWS image override behavior.
- Keep the wrapper minimal and pass
"$@" directly to the container image.
- Use non-mutating smoke checks such as
aws --version or read-only AWS calls such as aws sts get-caller-identity when credentials are intentionally available.
- If a Shimmy wrapper fails because of Podman reachability, sandboxing, or AI Agent approval symptoms, follow the
shimmy-escalation workflow before using a non-shim fallback.
- Update the runtime shim, docs, tests, installer behavior, and README together when behavior changes.
Validation
- Direct smoke:
./shims/aws --version
- Expected output contains
aws-cli/
- Keep exact argument and mount behavior covered in
../../../scripts/test-shimmy.sh.
Learning Guidance
- Capture AWS-specific lessons here when they affect credential discovery, read-only mounts, env forwarding, regions, profiles, SSO, or container image behavior.
- Promote reusable Shimmy design lessons to
../shimmy-create-tool/SKILL.md under Learning Guidance.
