Setup guide

The mandatory pre-flight probe that proves which account, principal and partition the credentials resolve to before any read or mutation.

↳ Requires no IAM permission at all and cannot be denied by an identity policy, so it is safe to call from any principal.

Baseline for every investigation: describe/list/get across services so the skill can enumerate resources, resolve blast radius and verify post-state.

↳ arn:aws:iam::aws:policy/job-function/ViewOnlyAccess is narrower (it omits data-plane reads such as s3:GetObject and dynamodb:GetItem); narrower still is a hand-written policy listing only the describe/list actions the task needs.

Switches into the target account, or into the elevated write role named by a profile's role_arn.

↳ Scope Resource to the exact role ARNs the agent may assume, and require sts:ExternalId plus aws:MultiFactorAuthPresent in the role's trust policy.

Enumerates which regions are enabled for the account so multi-region sweeps never guess and OptInRequired is diagnosed correctly.

↳ Included in ReadOnlyAccess; account:ListRegions is an alternative that also reports opt-in status.

Primary inventory read used to resolve tag and state filters into a concrete instance id list before any change.

↳ Cannot be resource-scoped; constrain it with a Condition on ec2:Region or aws:RequestedRegion instead.

Tests whether the caller is allowed to perform a specific action on a specific resource ARN before the mutation is attempted.

↳ Scope Resource to the caller's own role ARN so the agent can simulate itself but not audit other principals; note it does not evaluate service control policies.

Decodes the encoded blob returned with UnauthorizedOperation so a denial can be reported as a specific action and resource rather than a dead end.

↳ Cannot be resource-scoped; it is read-only and safe to grant broadly, but the decoded output contains policy detail so keep it out of shared logs.

The reversible-mutation example: gated behind --dry-run plus explicit human confirmation, with start-instances as the documented rollback.

↳ Grant only in the write role, scoped with Condition ec2:ResourceTag/Environment matching non-production values; keep ec2:TerminateInstances out of the policy entirely unless the task demands it.

Produces the reviewable plan for stack changes so the skill never applies an unexamined template.

↳ Pair with cloudformation:DescribeChangeSet and cloudformation:DescribeStacks but withhold cloudformation:ExecuteChangeSet until a change is approved; scope Resource to specific stack ARNs.

Applies a change set only after its Changes list, including any Replacement=True rows, has been shown and confirmed.

↳ Scope Resource to the named stack ARNs and add a Condition on cloudformation:ChangeSetName so ad-hoc change sets cannot be executed.

Cross-service, tag-scoped inventory used to resolve 'everything tagged Environment=x' into explicit ARNs before a change is proposed.

↳ Read-only and included in ReadOnlyAccess; no resource-level scoping is available for this action.

Attributes an unexpected change to a principal and timestamp when reconciling drift or investigating a failed call.

↳ Read-only; grant only when investigation is in scope, and prefer a dedicated audit role if CloudTrail data is sensitive.

Cause: No credential source resolved: the profile has neither static keys nor a live SSO/role session, or AWS_PROFILE names a profile that only exists in ~/.aws/credentials while the config lives elsewhere.

Fix: Run `aws configure list --profile <p>` to see where each value comes from, then `aws sso login --sso-session <name>` or set the profile's source_profile. Never invent keys.

Cause: AWS_PROFILE names a profile that is not in ~/.aws/config, or the block is written as [acme-staging] in config where it must be [profile acme-staging].

Fix: Run `aws configure list-profiles`, fix the block header (only ~/.aws/credentials uses the bare [name] form), or point AWS_CONFIG_FILE at the right file.

Cause: The temporary session (IAM Identity Center or assume-role) passed its duration - typically one hour - mid-task.

Fix: Re-run `aws sso login --sso-session <name>` or re-assume the role. Structurally, use a profile with role_arn/sso_session so the SDK refreshes automatically instead of exporting AWS_SESSION_TOKEN once.

Cause: No cached IAM Identity Center token for this start URL, or the ~/.aws/sso/cache entry was cleared or belongs to a different sso-session name.

Fix: Run `aws sso login --sso-session <name>` (or `aws sso login --profile <p>`) and complete the browser device flow; add --no-browser on a headless host.

Cause: Either the caller's identity policy lacks sts:AssumeRole for that role ARN, or the role's trust policy does not name the caller - or it requires an ExternalId or MFA that was not supplied.

Fix: Fix both sides: allow sts:AssumeRole on the exact role ARN in the caller's policy, and add the caller as a Principal in the role's trust policy. Pass --external-id and --serial-number/--token-code when the trust policy conditions on them.

Cause: EC2's authorization failure for a mutating call - an identity policy, permission boundary, or SCP denied it.

Fix: Run `aws sts decode-authorization-message --encoded-message <blob> --query DecodedMessage --output text` to see the exact action, resource and matched statement, then request that specific permission rather than a broader policy.

Cause: An AWS Organizations SCP denies the action for the whole account, so no identity policy can grant it - and iam:SimulatePrincipalPolicy will not have predicted it.

Fix: Stop and escalate to the organization administrator; do not attempt workarounds, alternate regions, or a different principal in the same account.

Cause: Not a failure - this is the success signal for a --dry-run pre-check, but the CLI still exits 254 and will abort a `set -e` script.

Fix: Capture the output (out=$(aws ... --dry-run 2>&1) || true) and match on DryRunOperation instead of relying on the exit status.

Cause: The target region is an opt-in region this account has not enabled, or the service is not activated for the account.

Fix: Enable the region in Account settings (or via account:EnableRegion) and set sts_regional_endpoints = regional so STS works there; otherwise pick an enabled region from `aws ec2 describe-regions`.

Cause: Too many API calls per second, usually from looping single-resource describes or from client-side --query filtering that pulls every page.

Fix: Set AWS_RETRY_MODE=adaptive and AWS_MAX_ATTEMPTS=10, use paginators with --page-size, and push predicates into server-side --filters instead of --query.

Cause: No region resolved from --region, AWS_REGION, AWS_DEFAULT_REGION, the profile's region key, or instance metadata.

Fix: Pass --region explicitly on every scripted command, or set the region key on the profile; never rely on an ambient default when mutating.

Cause: The access key was deleted, deactivated or rotated, the secret does not match the key id, or the credentials belong to a different partition (aws-us-gov, aws-cn).

Fix: Re-issue or re-export the credentials, confirm the key id and secret are from the same pair, and check the endpoint partition matches the account.