amazon-ec2-image-builder
Creates and automates custom image builds with EC2 Image Builder - Linux, Windows, and macOS AMIs, and container images to ECR. Covers the build IAM role, Amazon-managed and custom components, image recipes, infrastructure and distribution configuration (launch templates, SSM parameters, other Regions), one-off builds, recurring scheduled pipelines for golden AMI automation and OS patching, custom image workflows, and diagnosing failed builds. Applies when creating, automating, or scheduling AMI or container image builds with Image Builder, or when debugging a failed build. Not for launching instances from existing AMIs, AMI lifecycle/retirement, or general EC2 fleet management.
- Installs
- 2.2K
- Last 24h
- +39
- Trending rank
- #3966
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/aws/agent-toolkit-for-aws --skill amazon-ec2-image-builder- 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 amazon-ec2-image-builder 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.
Amazon EC2 Image Builder
Overview
Domain expertise for building custom AMIs and container images with EC2 Image Builder — from the build IAM role through recipes, pipelines, distribution, and troubleshooting.
Works best with the AWS MCP server — recommended for sandboxed execution and audit logging. All guidance also works with standard AWS CLI access.
Guardrail — where this skill's own files live (MCP vs local install)
This skill can be loaded two ways, and they resolve the skill's own bundled files from different places. Determine how the skill was loaded before reading a reference or running a script:
- Loaded through the AWS MCP
retrieve_skilltool: The skill is not installed on the local filesystem. You MUST fetch each reference or script viaretrieve_skillwith thefileparameter (e.g.file="references/creating-images.md"), and use the returned content. Do NOTfile_readthese paths locally — they do not exist on disk. - Installed locally (e.g.
.kiro/skills/amazon-ec2-image-builder/or~/.claude/skills/amazon-ec2-image-builder/): Read files from the local skill directory using relative paths.
This distinction applies only to the skill's own packaged files. User data and
session artifacts are always read from and written to the user's working
directory. Never fetch or write user data through retrieve_skill.
First decision: one-off image or recurring pipeline
Ask this before creating anything — it changes what you build.
| The user wants | Do this |
|---|---|
| One custom AMI, once | Follow creating-images.md through step 7a: create-image with a recipe and infrastructure configuration — no pipeline needed. |
| A golden AMI that stays current (scheduled rebuilds that pick up base-image updates and patches) | An image pipeline: follow creating-images.md — the schedule is part of the create-image-pipeline call (step 7b). |
Related skills — route there instead
| Use this skill | When the request is about |
|---|---|
| launching-ec2-instance-with-best-practices | Launching instances from an AMI the user already has |
| setting-up-ec2-instance-profiles | Instance profiles in general (not the build IAM role this skill creates) |
| aws-compute | AMI sharing, retiring, and lifecycle management; general EC2 fleet questions |
Not covered here: AMI lifecycle/retirement (route via the table above) and VM/ISO image import and export (follow the AWS documentation directly).
Routing (references in this skill)
Read the matching reference before answering. The exact commands, failure fixes, and platform requirements live in the references — answering Image Builder questions from general knowledge is how agents get the details subtly wrong.
| User need | Read |
|---|---|
| Create an image or pipeline end to end: role, components, recipe, infrastructure, schedules, patching, scanning, chaining | creating-images.md |
Get the output AMI where it's needed: launch templates, SSM parameters (the service-linked role writes only under /imagebuilder/), other Regions | distribution-options.md |
| A build failed, hangs, or an Image Builder API call errors | troubleshooting.md |
| Windows (exit-3010 reboots), macOS (Mac Dedicated Hosts required), container images to ECR (extra build-role policy) | other-image-types.md |
| Custom image workflows (advanced — always require an execution role) | custom-workflows.md |
Reference files carry specific ARNs, Amazon-managed resource names, and service defaults — when precision matters, confirm against the AWS documentation.
Guardrails (every workflow)
- Quote CLI filter values that contain spaces:
--filters "name=name,values=Amazon Linux 2023 x86". Unquoted spaces are a CLI parse error. - Use the exact ARN each create call returns — never construct ARNs by hand.
- For a "latest" base image use an Amazon-managed image ARN with the
x.x.xwildcard, or anssm:parameter reference where no managed image exists. Never list versions and sort them as strings — the list is not semver-ordered. - Keep architecture consistent across the base image, every component's binaries, and the infrastructure instance types. Image Builder performs no create-time validation of this; a mismatch only fails mid-build when the component runs.
- For component failures, the root cause lives in CloudWatch log group
/aws/imagebuilder/<image-name>(on by default; also in the S3 logs if configured) — never in the API state. See troubleshooting.md. - To reboot mid-build, exit the step with code
194(Linux) or3010(Windows). The build re-runs that same step after the reboot — not the next step — so guard it with a marker file. A plain reboot command fails the step. - If a resource the user describes isn't visible to
get-image/get-image-pipeline, say you can't find it and check the Region and credentials in use — then keep troubleshooting from the user's description; a failed lookup is not proof the resource doesn't exist. - Distribution handles launch templates and SSM publishing natively (
launchTemplateConfigurations,ssmParameterConfigurations) — never add Lambda glue or manual launch-template versions for AMI propagation. - Default to: Amazon Linux 2023 base, IMDSv2 required (
instanceMetadataOptions httpTokens=required), and at least two instance types in the infrastructure configuration. S3 build logging is opt-in — CloudWatch logging is on regardless. - Check Amazon-managed components (
aws imagebuilder list-components --owner Amazon) before writing component YAML. Common needs (AWS CLI, OS updates, CloudWatch agent, STIG hardening) are already covered.
Security considerations
The defaults above are the security posture: IMDSv2 required on build instances, no inbound security-group rules, least-privilege build IAM role (two managed policies for AMI builds plus only the scoped grants a workflow needs), no secrets in components or logs, and log buckets with Block Public Access. Build logs capture full command output that can carry sensitive material; CloudWatch Logs encrypts them at rest by default, and associating a customer-managed KMS key with each /aws/imagebuilder/... log group (aws logs associate-kms-key) is recommended. For auditing and operational visibility, enable CloudTrail in the account so Image Builder API calls are recorded, and configure EventBridge rules or CloudWatch alarms on build failures (source aws.imagebuilder, detail-type EC2 Image Builder Image State Change) so misconfigurations and unauthorized changes surface promptly. Per-build notifications are covered by the SNS topic option (creating-images.md step 6) — prefer a customer-managed key on that topic too. Deviations from these should be explicit user decisions. Reference: EC2 Image Builder security best practices.
FAQ
What does the amazon-ec2-image-builder skill do?
Creates and automates custom image builds with EC2 Image Builder - Linux, Windows, and macOS AMIs, and container images to ECR. Covers the build IAM role, Amazon-managed and custom components, image recipes, infrastructure and distribution configuration (launch templates, SSM parameters, other Regions), one-off builds, recurring scheduled pipelines for golden AMI automation and OS patching, custom image workflows, and diagnosing failed builds. Applies when creating, automating, or scheduling AMI or container image builds with Image Builder, or when debugging a failed build. Not for launching instances from existing AMIs, AMI lifecycle/retirement, or general EC2 fleet management.
How do I install amazon-ec2-image-builder?
Run npx skills add https://github.com/aws/agent-toolkit-for-aws --skill amazon-ec2-image-builder 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/amazon-ec2-image-builder/ (personal) or .claude/skills/amazon-ec2-image-builder/ (project).
Which AI agents can use amazon-ec2-image-builder?
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 amazon-ec2-image-builder 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 amazon-ec2-image-builder?
It is published by aws in aws/agent-toolkit-for-aws. It has 2,197 recorded installs.
More from aws/agent-toolkit-for-aws
aws-iam
aws/agent-toolkit-for-aws
Provides verified corrections for IAM behaviors that AI agents frequently get wrong — policy evaluation edge cases, trust policy gotchas, STS session limits, Organizations quirks, and SAML/MFA specifics. Also provides structured workflows for IAM role management and baseline policy generation from application source code or a Terraform plan JSON. Covers condition operator safety (ForAnyValue/ForAllValues with Null checks), bucket policy deny patterns (VPC endpoint restrictions, org paths), confused deputy protection, and service role creation for AWS services (Glue, CloudTrail, Lambda, ECS, etc.) with aws:SourceAccount/aws:SourceArn trust conditions. Applies when creating IAM roles, writing IAM or bucket policies, generating policies from application source code or a Terraform plan JSON, working with STS, Organizations, or condition operators, or any task needing a service or execution role. Does not cover non-IAM authorization like Cognito user-pool policies or app-level RBAC.
aws-serverless
aws/agent-toolkit-for-aws
Routes serverless requests to a compute form factor and the skill that owns it. Applies first to Lambda, API Gateway, EventBridge, Step Functions and event-driven work while the compute, orchestration or integration choice is open — API backends, webhooks, jobs, cron, queue/stream consumers, durable workflows, event routing, Step Functions vs Durable Functions, and Pipes vs native event source mappings for queues and streams. Decides Event Functions on-demand vs Managed Instances, Web Functions, MicroVMs, EventBridge rules/Scheduler/Pipes/bus, HTTP vs REST API. Owns shared Lambda references (cold starts, SnapStart, concurrency, event sources, function URLs, throttling, troubleshooting). Defers to the specialized skill once a request commits to one form factor or service, or describes its defining feature, even unnamed (durable checkpointing and automatic step retries, Firecracker sandbox, managed instances, Node.js server). Not for EC2, ECS/EKS/Fargate or Amplify hosting.
aws-observability
aws/agent-toolkit-for-aws
Builds, configures, debugs, and optimizes AWS observability - operator-symptom questions and detecting Omni vs classic CloudWatch. CloudWatch on an already-reporting service: Log Insights, metric/composite/anomaly alarms, custom metrics/EMF, dashboards, X-Ray/ADOT tracing, canaries, CloudTrail, Dynamic Instrumentation (live breakpoints/snapshots), the Application Signals service map, and fleet health views. CloudWatch Omni on an existing Space: SQL over logs and traces, PromQL over metrics, Omni dashboards, Omni alerts, context graph for root cause, programmatic/IaC access (API/SDK/CLI/CloudFormation), driving Omni from a coding agent or skills, and evaluating AI agent quality from traces - on-demand and online scoring of live traffic, readback, custom evaluators. For first-time setup - creating an Omni Space, granting access, ingestion, or ADOT instrumentation for Application Signals (ServiceEvents, CI/CD metadata) or Omni - use setting-up-cloudwatch-observability. Not for app logging
aws-cdk
aws/agent-toolkit-for-aws
Authors, deploys, and troubleshoots AWS infrastructure using CDK with TypeScript or Python. Covers best practices, stack architecture, and construct patterns. Applies when writing CDK constructs, bootstrapping environments, running cdk deploy/synth/diff, fixing CDK or CloudFormation errors, planning stack structure, importing existing resources, resolving drift, or refactoring stacks without resource replacement.
aws-containers
aws/agent-toolkit-for-aws
Builds and deploys containerized workloads on Elastic Kubernetes Service (EKS), Elastic Container Service (ECS), Fargate, and ECR (Elastic Container Registry). Covers general EKS knowledge, Karpenter, AWS Load Balancer Controller and leveraging various open source Kubernetes projects with EKS. Covers general ECS knowledge, task definitions, Fargate services, ECS Exec, ECS Express Mode and ECS Managed Instances. Covers general Elastic Beanstalk knowledge, Elastic Beanstalk configuration and platforms supported by Elastic Beanstalk. Covers general ECR knowledge, ECR repository setup and lifecycle policies. Includes recommending, enabling, and reading Amazon ECS Action Logs to troubleshoot control-plane failures (deployment rollback/circuit-breaker, task placement, scaling, task replacement). Applies when deploying, debugging, or optimizing containers on AWS. Should be used instead of relying on internal knowledge for these services.
aws-billing-and-cost-management
aws/agent-toolkit-for-aws
Analyze AWS costs, find savings, manage budgets, evaluate Savings Plans and Reserved Instances, right-size EC2/Lambda/RDS/EBS with Compute Optimizer, look up service pricing, query CUR with Athena, detect cost anomalies, scope costs to billing views, and monitor Free Tier usage. Triggers on: AWS bill, cost analysis, reduce spend, savings plan, reserved instance, right-size, budget alert, cost optimization, pricing, free tier, cost anomaly, CUR, cost audit, billing view, billing view ARN.
Popular media & creative skills
hyperframes
heygen-com/hyperframes
Read first to make, edit, animate or render any video with HyperFrames (HTML rendered to video), including launch films, explainers, music videos, charts, maps, vertical clips, title cards, captions and overlays. Holds the render contract, the work loop and what each kind of video needs.
media-use
heygen-com/hyperframes
Get or make any media for a HyperFrames video - music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks - with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull, or should be stylized or hidden.
hyperframes-registry
heygen-com/hyperframes
About 450 ready-made HyperFrames blocks and components installed as editable source - transitions, overlays, titles, kinetic type, captions, charts, map overlays, 3D, camera moves. Use it before hand-building any named visual (CRT scanlines, glitch, film grain, a chart); also for hyperframes add and catalog.
hyperframes-creative
heygen-com/hyperframes
Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use hyperframes-animation.
ai-video-generation
101-skills/superpowers
Generate AI videos with Google Veo, Seedance 2.0, HappyHorse, Wan, Grok and 40+ models via inference.sh CLI. Models: Veo 3.1, Veo 3, Seedance 2.0, HappyHorse 1.0, Wan 2.5, Grok Imagine Video, OmniHuman, Fabric, HunyuanVideo. Capabilities: text-to-video, image-to-video, reference-to-video, video editing, lipsync, avatar animation, video upscaling, foley sound. Use for: social media videos, marketing content, explainer videos, product demos, AI avatars. Triggers: video generation, ai video, text to video, image to video, veo, animate image, video from image, ai animation, video generator, generate video, t2v, i2v, ai video maker, create video with ai, runway alternative, pika alternative, sora alternative, kling alternative, seedance, happyhorse
ai-image-generation
101-skills/superpowers
Generate AI images with GPT-Image-2, FLUX, Gemini, Grok, Seedream, Reve and 50+ models via inference.sh CLI. Models: GPT-Image-2, FLUX Dev LoRA, FLUX.2 Klein LoRA, Gemini 3 Pro Image, Grok Imagine, Seedream 4.5, Reve, ImagineArt. Capabilities: text-to-image, image-to-image, inpainting, LoRA, image editing, upscaling, text rendering. Use for: AI art, product mockups, concept art, social media graphics, marketing visuals, illustrations. Triggers: flux, image generation, ai image, text to image, stable diffusion, generate image, ai art, midjourney alternative, dall-e alternative, text2img, t2i, image generator, ai picture, create image with ai, generative ai, ai illustration, grok image, gemini image, gpt image, openai image, chatgpt image