Skip to content
Get packs

Guide · Agent skill

How to use the SageMaker IAM Preflight agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

SageMaker IAM Preflight is an agent skill from the huggingface/skills collection that makes your AI agent check for a usable SageMaker execution role before it deploys a model, starts a training job, or creates an endpoint. This guide is for developers who are unsure which IAM role SageMaker should use, or who sign in through AWS SSO without IAM write permissions. After reading it you will be able to install the skill, trigger it with a normal request, and understand what it checks and what it changes in your AWS account.

SageMaker IAM Preflighthuggingface/skills · Apache-2.0

Quick start

  1. 1Install the skill. Download the ZIP from the item page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps, upload the ZIP under Settings, Capabilities, Skills.
  2. 2Confirm AWS access. Run aws sts get-caller-identity in the shell you will use. It must return your identity before the helpers can work.
  3. 3Ask for the deployment. Make a normal request, such as deploying a model to a SageMaker endpoint, and let the agent run the preflight before it creates anything.
  4. 4Validate or discover the role. The agent validates a role you named, or runs check_role.py to find and rank existing SageMaker roles and return the first usable ARN.
  5. 5Create a role only if needed. If discovery finds nothing and you have IAM permissions, the agent runs create_role.py. Without permissions, it stops and asks your administrator for a role ARN or the needed permissions.
  6. 6Review before deploying. Check the selected role's policies against references/minimum-permissions.json and confirm only the required actions and resources are present.

What an agent skill is and what this one makes the agent do

An agent skill is a folder of instructions and helper files that an AI agent can load when a task matches the skill's description. This skill's main file, SKILL.md, tells the agent to handle SageMaker execution roles in a fixed order: discover, validate, and only create a role if necessary.

SageMaker needs an execution role, which is an AWS IAM role that SageMaker assumes to read model artifacts from S3, pull serving containers from ECR, and write logs. The skill makes the agent look for an existing role in your account first, check that its trust policy allows sagemaker.amazonaws.com to assume it, and stop to ask an administrator if you lack the permissions to create one.

  • Checks any role you name explicitly before using it
  • Lists roles that match common SageMaker naming patterns and ranks them by last-used date, then by newest creation date when no usage data exists
  • Creates a new role only when discovery finds nothing and you have IAM permissions
  • Tells the agent to stop and ask an administrator, rather than retry, when you cannot create roles

Install the skill in Claude Code or in the Claude apps

Download the ZIP of skills/hf-cloud-sagemaker-iam-preflight from the item page. Unzip it into your user skills folder, ~/.claude/skills/, so the skill is available in every project. To limit it to one project, unzip it into the .claude/skills/ folder inside that project instead.

If you use the Claude apps rather than a local folder, upload the ZIP in the app under Settings, then Capabilities, then Skills.

  • Personal install: ~/.claude/skills/
  • Project install: .claude/skills/ inside your project folder
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check the requirements before you run anything

The helpers are Python scripts that call the AWS CLI, so the machine needs Python 3 and AWS CLI v2 on the PATH. Your AWS credentials must work in the same shell: aws sts get-caller-identity has to return your identity. The discovery step needs IAM read permissions to list and inspect roles. Creating a role additionally needs iam:CreateRole and iam:PutRolePolicy.

The skill runs scripts and uses the network. The helpers only do useful work against a live AWS account, so you need AWS access and SageMaker work in progress.

  • Python 3
  • AWS CLI v2 on PATH with working credentials
  • IAM read permissions to list and inspect roles
  • iam:CreateRole and iam:PutRolePolicy only if you will create a role
aws sts get-caller-identity

Trigger the skill with a natural request

You do not need to name the skill. The skill description says to use it whenever the agent is about to create a SageMaker endpoint, model, training job, or any resource that needs an execution role. It is especially relevant when you have not given a role ARN, when a script is about to call iam:CreateRole, or when an AccessDenied error mentions an IAM action.

Requests that should trigger it include the examples below. The agent should run the preflight before creating anything that needs a role.

  • Deploy this model to a SageMaker endpoint. I don't have a role ARN.
  • Start a SageMaker training job for this dataset in my AWS account.
  • My SageMaker deploy script failed with AccessDenied on iam:CreateRole. What do I do?
  • Which execution role should this SageMaker model use?

Run the helpers yourself

You can run the helpers directly from the shell where the AWS CLI already works. With a role name or ARN, check_role.py validates that role. With no argument, it discovers candidate roles. create_role.py creates a role, and its optional second argument scopes S3 access to one bucket. If you omit the bucket, the script warns you and the policy can be updated later.

Use Python 3 on macOS and Linux. On Windows, use python from PowerShell or cmd.

  • Validate a specific role: check_role.py with the role name or ARN
  • Discover roles: check_role.py with no argument
  • Create a role: create_role.py with the role name and, optionally, the model bucket
python3 scripts/check_role.py "<role-name-or-arn>" python3 scripts/check_role.py python3 scripts/create_role.py "<role-name>" "<model-bucket>"

Understand the permissions the role gets

A role is usable when it exists, its trust policy allows sagemaker.amazonaws.com to call sts:AssumeRole, and its permissions cover only what this deployment needs. references/trust-policy.json holds the canonical trust policy. references/minimum-permissions.json is an inline policy for endpoint execution that covers s3:GetObject and s3:ListBucket on the model bucket, ECR pull permissions, and CloudWatch logs and metrics.

The skill does not attach AmazonSageMakerFullAccess. Before deployment, the agent compares the selected role's policies with the minimum permissions file and adds only missing actions, scoped to the required resources. Optional features such as async output or data capture need their own narrowly scoped permissions.

  • Trust policy: references/trust-policy.json
  • Minimum permissions: references/minimum-permissions.json
  • create_role.py replaces REPLACE_WITH_MODEL_BUCKET with the bucket you pass in

Find the role by hand with the AWS CLI

If the Python helper cannot see your identity, the skill includes the same preflight as plain AWS CLI calls. Run them in the shell where aws sts get-caller-identity works. Choose the most recently used role whose trust policy contains sagemaker.amazonaws.com. If LastUsedDate is empty for every role, choose the newest CreateDate. Use the resulting ARN as if check_role.py had returned it.

  • List candidates with aws iam list-roles
  • Read a role's trust policy with aws iam get-role and the AssumeRolePolicyDocument query
  • Read last-used and creation dates with aws iam get-role and the RoleLastUsed and CreateDate fields
aws iam list-roles --query "Roles[?contains(RoleName,'SageMaker') || contains(RoleName,'sagemaker')]" --output json aws iam get-role --role-name <role-name> --query "Role.AssumeRolePolicyDocument" --output json aws iam get-role --role-name <role-name> --query "Role.[RoleLastUsed.LastUsedDate, CreateDate]" --output text

What people use it for

  • Deploying a model to a SageMaker endpoint when you do not know which execution role to use
  • Starting a training job from an SSO login that has no IAM write permissions, using an existing role from your admin
  • Fixing an AccessDenied error on an IAM action during SageMaker setup by finding the correct role instead of retrying
  • Auditing which SageMaker roles exist in an account and which trust policies they carry

Frequently asked questions

How do I install the SageMaker IAM Preflight skill?

Download the ZIP of skills/hf-cloud-sagemaker-iam-preflight from the item page and unzip it into ~/.claude/skills/ for all projects, or into .claude/skills/ inside one project. In the Claude apps, upload the ZIP under Settings, then Capabilities, then Skills.

What do I need to run the SageMaker IAM Preflight skill?

You need Python 3, AWS CLI v2 on your PATH, and working AWS credentials. aws sts get-caller-identity must succeed in the same shell. IAM read permissions are needed for discovery, and iam:CreateRole and iam:PutRolePolicy are needed only if you create a role.

Is the SageMaker IAM Preflight skill free?

The skill is licensed under Apache-2.0, as listed on the item page. The source does not describe pricing, and the helpers run against your own AWS account, so AWS charges for SageMaker and other services you use are separate.

Why does the skill stop instead of creating a role when I get AccessDenied?

SSO principals often lack IAM write permissions, so creating a role fails. The skill tells the agent to stop, explain the problem, and ask an administrator for a role ARN or for iam:CreateRole and iam:PutRolePolicy on your permission set. This avoids repeated failing attempts.

Can I run the helper on Windows through WSL or Git Bash?

The source advises against it. Bash environments on Windows often do not share the Windows AWS config, credentials, SSO sessions, or proxy settings, so aws sts get-caller-identity can fail there. Run python scripts\check_role.py from PowerShell, or use the native AWS CLI commands in the shell where your identity works.

Should I use this skill in a production account?

Only after review. The create script can add IAM roles and policies directly, so production accounts where role creation goes through change control should review the script first. You can also skip create_role.py and inspect the role against references/minimum-permissions.json yourself.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you deploy or train models on SageMaker, are unsure which execution role to use, or work through an SSO login without IAM write permissions. Skip it if you have no AWS credentials or SageMaker work underway, if your production role changes must go through change control, or if you use a non-AWS machine learning platform.

Download the skill