container-layer

Container Layer

Build a reproducible, cached environment overlay for ephemeral containers using a Dockerfile-like spec.

When NOT to use this skill

This authors and caches a layer spec. It is not a Docker troubleshooting tool.

Situation	Use
A build is slow or failing	read the build log; this skill will not help
Managing a running container	docker/podman directly
Session boot sequence and hooks	the workspace's own boot docs

The tell is tense: this skill is for the environment you want next session, not the container you are fighting now.

Concept

The container resets every session, but your environment shouldn't. This skill:

1. Parses a Containerfile (Dockerfile subset) that declares your environment
2. Caches the built result as a tarball in GitHub Releases
3. Restores from cache on subsequent boots (single fetch vs. N installs)
4. Provides a uv shim that captures ad-hoc installs back into the Containerfile

Supported Containerfile Instructions

# Environment variables
ENV KEY=value

# Shell commands (including package installs)
RUN apt-get install -y foo        # system packages
RUN uv pip install pandas numpy   # Python packages (preferred)
RUN pip install requests          # also works

# Fetch files from URLs or GitHub
FETCH https://example.com/file.tar.gz /dest/path
FETCH github:user/repo /dest/path              # latest tarball
FETCH github:user/repo@ref /dest/path          # specific ref

# Set working directory for subsequent RUN commands
WORKDIR /some/path

# Declare paths to include in the cached layer snapshot
# (auto-detected for FETCH destinations and pip/uv installs)
SNAPSHOT /additional/path/to/capture

# Ignored (Dockerfile compat, no-op here):
# FROM, EXPOSE, CMD, ENTRYPOINT, LABEL, ARG, VOLUME, USER, SHELL

Usage

Single layer — build / restore

from scripts.containerfile import ContainerLayer

layer = ContainerLayer(
    containerfile_path="/path/to/Containerfile",
    cache_repo="oaustegard/claude-container-layers",  # GitHub repo for release assets
    gh_token="...",
)

# Try cache first, fall back to full build
layer.restore_or_build()