Guide · Agent skill
How to use the pack agent skill to ship a smolvm environment
Updated · written with AI from the project's own documentation and checked against our catalogue data
The pack skill teaches an AI agent to take a prepared environment, either a stock container image or a virtual machine you have already set up, and bundle it into a single portable file that another compatible computer can run. It is for developers who need to ship a ready environment to a teammate or another host with no install step. After reading this guide you will know how to install the skill, how to ask for a pack in plain language, and how the skill confirms that your installed state actually made it into the artifact.
Pack a machine into a portable artifactsmol-machines/smolvm · Apache-2.0 Download the skill Quick start
- 1Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings, Capabilities, Skills.
- 2Make smolvm available. Confirm the smolvm CLI runs from your PATH, or set SMOLVM to its full path.
- 3Run the preflight. Ask the agent to run the read-only preflight and read the exporter_memory_ok and image_vm_memory_ok lines before packing.
- 4Pack the image or machine. Choose pack-image.sh for a stock image or pack-machine.sh for a provisioned machine, and let the agent run it.
- 5Verify the marker. Run verify-pack.sh and confirm machine_pack_carried_rootfs reports ok rather than a pass over zero artifacts.
- 6Clean up. Run cleanup.sh with --purge and your artifact paths to remove the test machines and stubs it made.
What the pack skill makes the agent do
The skill turns an image, or a machine already provisioned, into a self-contained artifact that runs on another compatible host. The agent follows a procedure: a read-only preflight check, packing from an image or from a machine, verifying the result, and cleaning up the test machines it created.
The key check is a value, not a boot. Before packing from a machine, the scripts write a marker value into the source machine and read it back from the artifact afterwards. A pack that lost its files would still boot and exit zero, so the marker is what shows the installed state is really inside.
- Packs a stock image such as alpine or python:3.12-alpine with pack-image.sh
- Packs a provisioned machine with pack-machine.sh, after asserting the marker on the source
- Checks memory before packing with preflight.sh, which warns but does not block
- Verifies both halves with verify-pack.sh and removes test machines with cleanup.sh
- Can forward an SSH agent into an artifact without copying keys
Install the pack skill
Download the ZIP of the pack skill from this page. Then install it in one of two ways. For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.
You can also upload the ZIP in the Claude apps under Settings, then Capabilities, then Skills.
- Personal: unzip into ~/.claude/skills/
- Project only: unzip into .claude/skills/ inside the project
- Claude apps: Settings, Capabilities, Skills, then upload the ZIP
unzip pack.zip -d ~/.claude/skills/Requirements before you start
The skill's scripts depend on the smolvm command-line tool and fail without it. If smolvm is not on your PATH, set the SMOLVM environment variable to its full path. You also need a Bash shell and a host that supports smolvm. The source reports that macOS on Apple silicon (arm64) and Linux on aarch64 were verified.
Packing pulls container images such as alpine, so the host needs network access. The skill's scripts run commands and use the network, so read them before you run them on a machine you care about.
- smolvm CLI installed, or SMOLVM set to its path
- Bash shell
- macOS arm64 or Linux aarch64 host (the verified platforms)
- Network access to pull images
export SMOLVM=/path/to/smolvmHow to trigger the skill with natural requests
You do not need to name the scripts. Describe the situation in plain words and the agent will pick this skill when the request matches. The skill covers shipping a prepared environment as one file, a packed artifact that runs without the state you installed, a pack create failure where the helper VM could not start, an older release refusing to export a branched machine, and the choice between packing from an image or from a machine.
Requests the skill is not meant for: keeping a machine you re-enter regularly (that belongs to a separate dev-env skill) and running untrusted code (that belongs to a separate throwaway-machine skill).
- Example: Pack my provisioned smolskill machine into one file I can send to a teammate.
- Example: My packed artifact runs but the packages I installed are missing. Help me find out why.
- Example: pack create fails with the export helper not becoming ready. What do I check?
- Example: Should I pack this from the stock python image or from my configured machine?
Pack from an image or from a machine
Pack from an image when you want a runnable artifact of a stock image. Pack from a machine when the point is the state installed in it. For a machine you provisioned yourself, the skill stops it first, because the export packs a stopped machine's snapshot and refuses a running one. Afterwards the machine can be started again.
An artifact made with the default settings is two files, and both must travel together. The skill can instead write one executable with --single-file.
- From an image: pack-image.sh, optionally with an image name and output folder
- From a machine: pack-machine.sh, which creates a machine with a workload that stays up, writes a marker and asserts it before export
- From your own machine: stop it, pack with --single-file, verify with your own marker file, then start it again
scripts/pack-image.sh python:3.12-alpine ./mypackCheck that the installed state is inside the artifact
The line that matters is machine_pack_carried_rootfs. It shows the marker survived into the artifact. The other lines are context. If you point verification at artifacts that do not exist, it reports nothing_verified and exits non-zero, so an empty check is never reported as a pass.
If you packed an image to a custom output folder, pass the same folder to the verify step, or it will look in the defaults and find nothing.
- Good result: machine_pack_carried_rootfs=ok (PACKED_STATE_PRESENT)
- Failure to watch for: result=nothing_verified
- Custom output: verify-pack.sh --image ./mypack
scripts/verify-pack.shWhat people use it for
- Shipping a configured smolvm development environment to a teammate as one file
- Diagnosing a packed artifact that starts but is missing packages installed into the machine
- Choosing between packing a stock python image and packing a machine you configured
- Forwarding your host SSH agent into an artifact you trust so it can sign requests without copying keys
Frequently asked questions
Is the pack agent skill free to use?
The source lists the item's licence as Apache-2.0. The skill itself is a set of instructions and scripts, and it requires the smolvm CLI to be installed separately. Check the licence file in the project for the full terms.
What do I need to run the pack skill?
You need the smolvm CLI, a Bash shell, a host that supports smolvm (macOS on Apple silicon and Linux on aarch64 were verified), and network access to pull images such as alpine. If smolvm is not on your PATH, set the SMOLVM variable to its path.
Why does my packed artifact run but the installed software is missing?
The artifact may have been packed without the state you installed. Run the verify step with your marker: if machine_pack_carried_rootfs does not report ok, the installed state did not make it into the artifact. Check the source machine's marker before packing, because a machine whose provisioning silently failed packs cleanly and contains nothing.
Why does pack create fail with 'agent did not become ready'?
The export helper VM could not start, often because of memory. The preflight reports exporter_memory_ok and image_vm_memory_ok. From the newer releases the helper asks for less memory, and you can set SMOLVM_EXPORT_HELPER_MEMORY_MIB to a size your host can give it. A failed start names this variable.
Is it safe to run the pack skill on my machine?
The skill runs scripts and uses the network, and it can create and delete test machines. Read the scripts first. Forward your SSH agent only to an artifact you trust, because the guest can request signatures while it runs. Do not use this skill to run untrusted code; use the separate throwaway-machine skill for that.
How is this different from the dev-env skill?
The pack skill is for shipping a prepared environment as one file to another host. The dev-env skill is for keeping a machine you re-enter regularly. The source says this is a workflow difference, not a safety one.
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 the pack skill if you need to hand a prepared smolvm environment to another compatible machine as one file and want a real check that the installed state came along. Pick something else if you only need to keep a machine you return to often, or if you need to run code you do not trust, since those belong to other skills. Also skip it if you cannot install the smolvm CLI, because every script depends on it.
Download the skill