Claude Skill

container-layer

Authors and caches a personalized container environment from a Dockerfile- like spec, as a single layer or as a composition of independently cached layers. Use when the user mentions "container layer", "Containerfile", "custom container", "cache my installs", "composable layers",

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download oaustegard-claude-skills-plugins_environment-and-config_skills_container-layer-e39c726.zip · 26 KB

Install

skills CLI npx skills add https://github.com/oaustegard/claude-skills/tree/main/plugins/environment-and-config/skills/container-layer
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oaustegard-claude-skills@llmmart
Git git clone https://github.com/oaustegard/claude-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oaustegard/claude-skills collection as a plugin from our marketplace. Git is the plain clone.

README

container-layer

Custom, cached environment overlays for Claude's ephemeral containers.

What This Does

Claude.ai and Claude Code on the Web run in ephemeral containers — every session starts from a blank slate. This skill lets you declare your environment in a Containerfile (a Dockerfile subset), build it once, cache the result as a tarball in GitHub Releases, and restore it in seconds on subsequent sessions.

First session: parse Containerfile → execute instructions → snapshot filesystem delta → push ~3 MB tarball to GitHub Releases.

Every session after: download tarball → extract → done. One fetch replaces N installs.

Components

File Purpose
SKILL.md Skill metadata and documentation
Containerfile Default environment spec (edit this)
boot.sh Boot script for Claude.ai project instructions
boot-ccotw.sh Boot script for Claude Code (SessionStart hook)
scripts/containerfile.py Parser + executor with baseline diffing
scripts/layer_cache.py GitHub Releases tarball cache
scripts/cli.py CLI: build, restore, hash, inspect
scripts/uv_shim.sh Captures ad-hoc uv pip install to Containerfile

Supported Instructions

FETCH github:user/repo /dest          # GitHub repo tarball
FETCH github:user/repo@ref /dest      # Specific ref
RUN uv pip install --system pandas     # Shell commands
ENV KEY=value                          # Environment variables  
WORKDIR /path                          # Working directory
SNAPSHOT /path                         # Include in cached layer

FROM, EXPOSE, CMD, ENTRYPOINT, etc. are silently ignored (Dockerfile compatibility).

Smart Snapshotting

The executor captures a filesystem baseline before building, then diffs against it — only new files from pip install / uv pip install are included in the tarball, not the entire dist-packages directory. FETCH destinations are captured in full. This keeps tarballs small (~3 MB for a full skills repo + Python packages).

Cache Invalidation

The cache key is a SHA-256 of the Containerfile contents. Pass --invalidate-on user/repo to include a GitHub repo's HEAD SHA in the key — when that repo gets a new commit, the cache auto-invalidates and triggers a rebuild.

python3 -m scripts.cli --invalidate-on oaustegard/claude-skills restore ./Containerfile

Ad-Hoc Install Capture

Source the uv shim to automatically append new installs to your Containerfile:

source ./scripts/uv_shim.sh ./Containerfile
uv pip install --system pandas    # installs AND appends RUN line

Test Repo

See container-layer-test for a working example with Claude Code on the Web SessionStart hooks.

Skill manifest

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()

Or via CLI:

python -m scripts.cli restore /path/to/Containerfile --repo user/cache-repo

Multi-layer composition (v0.2.0+)

Decompose a heavy environment into named layers, each cached independently. Compose them in order on session start so most-changed bits don't invalidate stable bits.

from scripts.containerfile import compose

compose(
    containerfile_paths=[
        "layers/Containerfile",            # name='base'  (always-on)
        "layers/Containerfile.scientific", # name='scientific'
        "layers/Containerfile.mojo",       # name='mojo'
    ],
    cache_repo="user/cache-repo",
)

Each layer gets its own cache release tag layer-<name>-<hash> so retention policies (keep last N) and cache invalidation operate per-name.

Default layer names are derived from the Containerfile path:

  • Containerfile → base
  • Containerfile.scientific → scientific
  • layers/Containerfile.X → X

CLI equivalent:

python -m scripts.cli compose \
    layers/Containerfile \
    layers/Containerfile.scientific \
    layers/Containerfile.mojo \
    --repo user/cache-repo

Per-layer name override

If filename doesn't derive cleanly, pass --name NAME:PATH per layer:

python -m scripts.cli compose \
    --name base:weird-named-file.txt \
    --name mojo:other-file.txt \
    weird-named-file.txt other-file.txt

Single-layer naming (back-compat)

build / restore / hash / inspect accept --name:

python -m scripts.cli restore Containerfile.mojo --name mojo
# Cache tag becomes 'layer-mojo-<hash>' instead of 'layer-<hash>'.
# Omit --name to keep the old back-compat tag for existing callers.

The uv Shim

After building, install the shim to capture future installs:

source /path/to/container-layer/scripts/uv_shim.sh /path/to/Containerfile

Now uv pip install foo both installs the package AND appends RUN uv pip install foo to your Containerfile.

Rebuilding the Cache

After modifying the Containerfile:

layer.build_and_push()  # Execute, snapshot, upload

Architecture

Read scripts/containerfile.py for the parser/executor and scripts/layer_cache.py for the GitHub Releases caching logic. The cache key is a SHA-256 of the Containerfile contents — any change triggers a rebuild.

Configuration

The skill expects these environment variables (or pass as constructor args):

  • GH_TOKEN — GitHub token with repo scope (for releases)
  • Cache repo can be any repo the token has write access to

Workflow Integration

This skill is designed to be invoked from a boot script. Example Containerfile:

# Skills
FETCH github:oaustegard/claude-skills /mnt/skills/user

# Python environment
RUN uv pip install --system pandas numpy requests

# Path config
RUN echo '/mnt/skills/user/remembering' > /usr/local/lib/python3.12/dist-packages/muninn-remembering.pth

# Custom setup
ENV MY_VAR=hello
WORKDIR /home/claude
Files (claude-skills)
  • scripts
    • cli.py 8.1 KB
      Loading…
    • containerfile.py 20 KB
      Loading…
    • layer_cache.py 8.4 KB
      Loading…
    • test_baseline_paths.py 4.9 KB
      Loading…
    • test_named_layers.py 6.6 KB
      Loading…
    • uv_shim.sh 2.5 KB
      Loading…
    • __init__.py 26 B
      Loading…
    • __main__.py 30 B
      Loading…
  • boot-ccotw.sh 2.7 KB
    Loading…
  • boot.sh 2.9 KB
    Loading…
  • CHANGELOG.md 4.3 KB
    Loading…
  • Containerfile 1.4 KB · in bundle
  • README.md 2.8 KB
    # container-layer
    
    Custom, cached environment overlays for Claude's ephemeral containers.
    
    ## What This Does
    
    Claude.ai and Claude Code on the Web run in ephemeral containers — every session starts from a blank slate. This skill lets you declare your environment in a `Containerfile` (a Dockerfile subset), build it once, cache the result as a tarball in GitHub Releases, and restore it in seconds on subsequent sessions.
    
    **First session:** parse Containerfile → execute instructions → snapshot filesystem delta → push ~3 MB tarball to GitHub Releases.
    
    **Every session after:** download tarball → extract → done. One fetch replaces N installs.
    
    ## Components
    
    | File | Purpose |
    |------|---------|
    | `SKILL.md` | Skill metadata and documentation |
    | `Containerfile` | Default environment spec (edit this) |
    | `boot.sh` | Boot script for Claude.ai project instructions |
    | `boot-ccotw.sh` | Boot script for Claude Code (SessionStart hook) |
    | `scripts/containerfile.py` | Parser + executor with baseline diffing |
    | `scripts/layer_cache.py` | GitHub Releases tarball cache |
    | `scripts/cli.py` | CLI: `build`, `restore`, `hash`, `inspect` |
    | `scripts/uv_shim.sh` | Captures ad-hoc `uv pip install` to Containerfile |
    
    ## Supported Instructions
    
    ```dockerfile
    FETCH github:user/repo /dest          # GitHub repo tarball
    FETCH github:user/repo@ref /dest      # Specific ref
    RUN uv pip install --system pandas     # Shell commands
    ENV KEY=value                          # Environment variables  
    WORKDIR /path                          # Working directory
    SNAPSHOT /path                         # Include in cached layer
    ```
    
    `FROM`, `EXPOSE`, `CMD`, `ENTRYPOINT`, etc. are silently ignored (Dockerfile compatibility).
    
    ## Smart Snapshotting
    
    The executor captures a filesystem baseline before building, then diffs against it — only new files from `pip install` / `uv pip install` are included in the tarball, not the entire `dist-packages` directory. `FETCH` destinations are captured in full. This keeps tarballs small (~3 MB for a full skills repo + Python packages).
    
    ## Cache Invalidation
    
    The cache key is a SHA-256 of the Containerfile contents. Pass `--invalidate-on user/repo` to include a GitHub repo's HEAD SHA in the key — when that repo gets a new commit, the cache auto-invalidates and triggers a rebuild.
    
    ```bash
    python3 -m scripts.cli --invalidate-on oaustegard/claude-skills restore ./Containerfile
    ```
    
    ## Ad-Hoc Install Capture
    
    Source the uv shim to automatically append new installs to your Containerfile:
    
    ```bash
    source ./scripts/uv_shim.sh ./Containerfile
    uv pip install --system pandas    # installs AND appends RUN line
    ```
    
    ## Test Repo
    
    See [container-layer-test](https://github.com/oaustegard/container-layer-test) for a working example with Claude Code on the Web SessionStart hooks.
    
  • SKILL.md 5.7 KB
    ---
    name: container-layer
    description: >-
      Authors and caches a personalized container environment from a Dockerfile-
      like spec, as a single layer or as a composition of independently cached
      layers. Use when the user mentions "container layer", "Containerfile",
      "custom container", "cache my installs", "composable layers", "uv shim",
      or wants package installations, skills and environment config to survive
      an ephemeral session. Also for snapshotting, restoring or rebuilding that
      environment, and for capturing ad-hoc installs into a reproducible spec.
    metadata:
      version: 0.4.0
    ---
    
    # 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
    
    ```dockerfile
    # 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
    
    ```python
    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()
    ```
    
    Or via CLI:
    
    ```bash
    python -m scripts.cli restore /path/to/Containerfile --repo user/cache-repo
    ```
    
    ### Multi-layer composition (v0.2.0+)
    
    Decompose a heavy environment into named layers, each cached independently. Compose them in order on session start so most-changed bits don't invalidate stable bits.
    
    ```python
    from scripts.containerfile import compose
    
    compose(
        containerfile_paths=[
            "layers/Containerfile",            # name='base'  (always-on)
            "layers/Containerfile.scientific", # name='scientific'
            "layers/Containerfile.mojo",       # name='mojo'
        ],
        cache_repo="user/cache-repo",
    )
    ```
    
    Each layer gets its own cache release tag `layer-<name>-<hash>` so retention policies (keep last N) and cache invalidation operate per-name.
    
    Default layer names are derived from the Containerfile path:
    - `Containerfile`            → `base`
    - `Containerfile.scientific` → `scientific`
    - `layers/Containerfile.X`   → `X`
    
    CLI equivalent:
    
    ```bash
    python -m scripts.cli compose \
        layers/Containerfile \
        layers/Containerfile.scientific \
        layers/Containerfile.mojo \
        --repo user/cache-repo
    ```
    
    ### Per-layer name override
    
    If filename doesn't derive cleanly, pass `--name NAME:PATH` per layer:
    
    ```bash
    python -m scripts.cli compose \
        --name base:weird-named-file.txt \
        --name mojo:other-file.txt \
        weird-named-file.txt other-file.txt
    ```
    
    ### Single-layer naming (back-compat)
    
    `build` / `restore` / `hash` / `inspect` accept `--name`:
    
    ```bash
    python -m scripts.cli restore Containerfile.mojo --name mojo
    # Cache tag becomes 'layer-mojo-<hash>' instead of 'layer-<hash>'.
    # Omit --name to keep the old back-compat tag for existing callers.
    ```
    
    ### The uv Shim
    
    After building, install the shim to capture future installs:
    ```bash
    source /path/to/container-layer/scripts/uv_shim.sh /path/to/Containerfile
    ```
    
    Now `uv pip install foo` both installs the package AND appends `RUN uv pip install foo` to your Containerfile.
    
    ### Rebuilding the Cache
    
    After modifying the Containerfile:
    ```python
    layer.build_and_push()  # Execute, snapshot, upload
    ```
    
    ## Architecture
    
    Read `scripts/containerfile.py` for the parser/executor and `scripts/layer_cache.py` for the GitHub Releases caching logic. The cache key is a SHA-256 of the Containerfile contents — any change triggers a rebuild.
    
    ## Configuration
    
    The skill expects these environment variables (or pass as constructor args):
    - `GH_TOKEN` — GitHub token with `repo` scope (for releases)
    - Cache repo can be any repo the token has write access to
    
    ## Workflow Integration
    
    This skill is designed to be invoked from a boot script. Example Containerfile:
    
    ```dockerfile
    # Skills
    FETCH github:oaustegard/claude-skills /mnt/skills/user
    
    # Python environment
    RUN uv pip install --system pandas numpy requests
    
    # Path config
    RUN echo '/mnt/skills/user/remembering' > /usr/local/lib/python3.12/dist-packages/muninn-remembering.pth
    
    # Custom setup
    ENV MY_VAR=hello
    WORKDIR /home/claude
    ```
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.