hf-cloud-sagemaker-iam-preflight
Ensure a usable SageMaker execution role exists before deploying or training. Use this skill whenever about to create a SageMaker endpoint, model, training job, or any resource that requires an execution role. Use it especially when the user has not provided a role ARN explicitly, when scripts are about to call iam:CreateRole, or when an AccessDenied error mentions an IAM action. Never blindly call iam:CreateRole — always check for existing roles first. This skill prevents the most common SageMaker deployment failure: trying to create IAM resources from an SSO principal that has no IAM write permissions.
- Installs
- 546
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/huggingface/skills --skill hf-cloud-sagemaker-iam-preflight- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads hf-cloud-sagemaker-iam-preflight automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
SageMaker IAM Preflight
Every SageMaker resource needs an execution role — the IAM role SageMaker assumes to read model artifacts from S3, pull serving containers from ECR, and write logs. Most deployments fail here because the script tried to create a new role without checking if a usable one already existed, then blew up because the caller is an SSO principal.
This skill encodes the right order: discover, validate, only create if necessary.
Running the helpers (cross-platform)
The helpers are Python so they run identically on Windows, macOS, and Linux:
python3 scripts/check_role.py # macOS / Linux
python scripts/check_role.py # Windows (PowerShell / cmd)
Run them from the shell where the AWS CLI already works — i.e. wherever aws sts get-caller-identity succeeds. The script shells out to that same aws binary and inherits the shell's profile, region, SSO session, proxy, and credential chain.
Windows / WSL / Git Bash caveat. Do not invoke these through a Bash shim (WSL, Git Bash, MSYS) on Windows. Those Bash environments frequently do not share the Windows AWS config, credentials, SSO sessions, environment variables, or proxy settings — so
aws sts get-caller-identityfails inside Bash even when it works natively in PowerShell. (This is exactly why the old.shhelpers failed on Windows and were replaced with Python.) If you're in PowerShell, runpython ...\check_role.pydirectly in PowerShell. If the helper still can't see your identity, run the same discovery natively (see "Native AWS CLI equivalent" below) in the shell whereaws sts get-caller-identityreturns your ARN.
Order of operations
Step 1 — Did the user provide a role?
Validate that one specifically:
python3 scripts/check_role.py "<role-name-or-arn>"
On success it prints the ARN to stdout (exit 0). On failure it logs why on stderr. Don't try to silently fix a broken role — surface the problem.
Step 2 — Discover existing roles
python3 scripts/check_role.py
Lists roles matching common SageMaker patterns (AmazonSageMaker-ExecutionRole-*, SageMakerExecutionRole*, etc.), ranks by last-used date (most recent first), validates trust policy in that order, returns the first usable ARN. Most accounts that have used SageMaker before already have one.
Why rank by last-used: in accounts with multiple roles (auto-generated 2021 role + manual project role + etc.), the alphabetically-first one is rarely the actively-maintained one. The most-recently-used role is more likely to have current policies — including cross-account ECR pull. The script prints the ranking so you can see which got picked.
IAM frequently reports no RoleLastUsed at all (tracking only covers recent activity). When every candidate ties at "never used", the script falls back to newest creation date — a newer role is more likely to have current policies than a 2021 leftover.
Step 3 — Create, only if discovery found nothing
If the user can create (has IAM permissions):
python3 scripts/create_role.py "<role-name>" "<model-bucket>"
Second arg scopes S3 access to a specific bucket. Omit if unknown; script warns and the user can update the policy later.
If the user cannot create (SSO principal — hf-cloud-aws-context-discovery will have flagged this):
Stop and surface this clearly. Don't retry alternative IAM operations hoping one works:
I can't find an existing SageMaker execution role, and you're authenticated via SSO so you can't create one directly. Please either:
- Ask your AWS admin for a SageMaker execution role ARN, or
- Have them grant your SSO permission set
iam:CreateRole,iam:PutRolePolicy
Specific instructions get unblocked fast; vague "permission denied" messages don't.
What "validated" means
A role is usable when (1) it exists, (2) its trust policy allows sagemaker.amazonaws.com to sts:AssumeRole, and (3) its permissions grant only the actions and resources this deployment needs. See references/trust-policy.json for the canonical trust policy.
check_role.py verifies existence and trust because policy evaluation depends on the deployment's exact S3, ECR, logging, and optional output resources. Before deployment, inspect the selected role's policies and compare them with references/minimum-permissions.json; add only missing actions and scope them to the required resources. Do not attach AmazonSageMakerFullAccess or defer permission review until an AccessDenied failure.
Minimum permissions
references/minimum-permissions.json is the standalone inline policy for endpoint execution:
s3:GetObject+s3:ListBucketon the model artifact bucket- ECR pull permissions
- CloudWatch logs and metrics
create_role.py installs this inline policy without attaching a managed FullAccess policy. Replace REPLACE_WITH_MODEL_BUCKET in the template with the actual bucket name — create_role.py does this automatically when given a bucket as its second argument. Add narrowly scoped permissions separately for optional features such as async output or data capture.
Native AWS CLI equivalent (fallback)
If the Python helper can't run or can't see your identity (rare — usually a broken PATH or running under a Bash shim that lacks AWS context), do the same preflight by hand in the shell where aws sts get-caller-identity works. The logic is just AWS CLI calls; the helper exists only to bundle and rank them.
PowerShell:
# 1. List candidate SageMaker roles
aws iam list-roles --query "Roles[?contains(RoleName,'SageMaker') || contains(RoleName,'sagemaker')]" --output json
# 2. For each candidate, confirm the trust policy allows sagemaker.amazonaws.com
aws iam get-role --role-name <role-name> --query "Role.AssumeRolePolicyDocument" --output json
# 3. Prefer the most-recently-used role with SageMaker-execution naming
# (LastUsedDate is often None for every role — then prefer newest CreateDate)
aws iam get-role --role-name <role-name> --query "Role.[RoleLastUsed.LastUsedDate, CreateDate]" --output text
Pick the most-recently-used role whose trust policy contains sagemaker.amazonaws.com. Use the resulting ARN exactly as if check_role.py had returned it. Bash/macOS/Linux use the same commands.
FAQ
What does the hf-cloud-sagemaker-iam-preflight skill do?
Ensure a usable SageMaker execution role exists before deploying or training. Use this skill whenever about to create a SageMaker endpoint, model, training job, or any resource that requires an execution role. Use it especially when the user has not provided a role ARN explicitly, when scripts are about to call iam:CreateRole, or when an AccessDenied error mentions an IAM action. Never blindly call iam:CreateRole — always check for existing roles first. This skill prevents the most common SageMaker deployment failure: trying to create IAM resources from an SSO principal that has no IAM write permissions.
How do I install hf-cloud-sagemaker-iam-preflight?
Run npx skills add https://github.com/huggingface/skills --skill hf-cloud-sagemaker-iam-preflight in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/hf-cloud-sagemaker-iam-preflight/ (personal) or .claude/skills/hf-cloud-sagemaker-iam-preflight/ (project).
Which AI agents can use hf-cloud-sagemaker-iam-preflight?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is hf-cloud-sagemaker-iam-preflight safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains hf-cloud-sagemaker-iam-preflight?
It is published by huggingface in huggingface/skills. It has 546 recorded installs.
More from huggingface/skills
hf-cli
huggingface/skills
Hugging Face Hub CLI (hf) for downloading, uploading, and managing models, datasets, spaces, buckets, repos, papers, jobs, and more on the Hugging Face Hub. Use when: handling authentication; managing local cache; managing Hugging Face Buckets; running or scheduling jobs on Hugging Face infrastructure; managing Hugging Face repos; discussions and pull requests; browsing models, datasets and spaces; reading, searching, or browsing academic papers; managing collections; querying datasets; configuring spaces; setting up webhooks; or deploying and managing HF Inference Endpoints. Make sure to use this skill whenever the user mentions 'hf', 'huggingface', 'Hugging Face', 'huggingface-cli', or 'hugging face cli', or wants to do anything related to the Hugging Face ecosystem and to AI and ML in general. Also use for cloud storage needs like training checkpoints, data pipelines, or agent traces. Use even if the user doesn't explicitly ask for a CLI command. Replaces the deprecated huggingfa
huggingface-datasets
huggingface/skills
Use this skill for Hugging Face Dataset Viewer API workflows that fetch subset/split metadata, paginate rows, search text, apply filters, download parquet URLs, and read size or statistics.
huggingface-gradio
huggingface/skills
Build Gradio web UIs and demos in Python. Use when creating or editing Gradio apps, components, event listeners, layouts, or chatbots.
huggingface-llm-trainer
huggingface/skills
Train or fine-tune language and vision models using TRL (Transformer Reinforcement Learning) or Unsloth with Hugging Face Jobs infrastructure. Covers SFT, DPO, GRPO and reward modeling training methods, plus GGUF conversion for local deployment. Includes guidance on the TRL Jobs package, UV scripts with PEP 723 format, dataset preparation and validation, hardware selection, cost estimation, Trackio monitoring, Hub authentication, model selection/leaderboards and model persistence. Use for tasks involving cloud GPU training, GGUF conversion, or when users mention training on Hugging Face Jobs without local GPU setup.
huggingface-papers
huggingface/skills
Look up and read Hugging Face paper pages in markdown, and use the papers API for structured metadata such as authors, linked models/datasets/spaces, Github repo and project page. Use when the user shares a Hugging Face paper page URL, an arXiv URL or ID, or asks to summarize, explain, or analyze an AI research paper.
transformers-js
huggingface/skills
Use Transformers.js to run state-of-the-art machine learning models directly in JavaScript/TypeScript. Supports NLP (text classification, translation, summarization), computer vision (image classification, object detection), audio (speech recognition, audio classification), and multimodal tasks. Works in browsers and server-side runtimes (Node.js, Bun, Deno) with WebGPU/WASM using pre-trained models from Hugging Face Hub.
Popular devops & cloud skills
microsoft-foundry
microsoft/azure-skills
Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent create, managed harness agent create, GitHub Copilot harness agent, create agent, update agent, add tool to agent, invoke agent, agent insights, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, Agent Optimizer scaffold, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure
azure-diagnostics
microsoft/azure-skills
Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.
azure-prepare
microsoft/azure-skills
Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.
azure-ai
microsoft/azure-skills
Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.
azure-deploy
microsoft/azure-skills
Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.
azure-validate
microsoft/azure-skills
Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.