overthinkos/merge
ov/skills/merge/SKILL.md
Post-build layer optimization via merging consecutive small layers. MUST be invoked before any work involving: ov image merge command, image layer reduction, merge configuration, or post-build optimization.
development
Updated Apr 27, 2026
$ install --global
skillsauthnpx skillsauth add overthinkos/overthink-plugins mergeInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 27, 2026, 9:43 AM61.9s1 file scanned
SKILL.md
- name:
- merge
- description:
- |
- MUST be invoked before any work involving:
- ov image merge command, image layer reduction, merge configuration, or post-build optimization.
ov image merge -- Post-Build Layer Optimization
Invoked as ov image merge [<image>]. See /ov:image for the family overview.
Overview
Reduces image layer count by merging consecutive small layers. Uses go-containerregistry to load the image, groups consecutive layers below a size threshold, deduplicates filesystem entries (last writer wins), and reconstructs the image. Idempotent -- safe to run multiple times.
Quick Reference
| Action | Command | Description |
|--------|---------|-------------|
| Merge single image | ov image merge <image> | Merge layers in specified image |
| Dry run | ov image merge <image> --dry-run | Show what would be merged without changing anything |
| Custom threshold | ov image merge <image> --max-mb N | Set max layer size for merge candidates (default: 128 MB) |
| Merge all auto | ov image merge --all | Merge all images that have merge.auto: true |
Usage
Basic Merge
# Merge consecutive small layers in an image
ov image merge sway-browser-vnc
# Preview without changing
ov image merge sway-browser-vnc --dry-run
Custom Size Threshold
# Only merge layers smaller than 64 MB
ov image merge sway-browser-vnc --max-mb 64
Automatic Merge for All Configured Images
# Merge all images that opt in via image.yml
ov image merge --all
Configuration in image.yml
images:
sway-browser-vnc:
merge:
auto: true # Include in `ov image merge --all`
max_mb: 128 # Size threshold (default: 128)
How It Works
- Load image via
go-containerregistry - Group consecutive layers where each is below
max_mb - Deduplicate filesystem entries across merged layers (last writer wins) and suppress whiteout conflicts
- Reconstruct image with merged layers
- Inline merge also runs automatically after each build level during
ov image build
Whiteout Handling
OCI/Docker images use special "whiteout" files to represent file deletions across layers. When merging layers, these must be handled correctly to prevent EEXIST errors during overlay unpack.
Three cases:
-
Regular whiteout — A file
.wh.<name>in layer N indicates that<name>was deleted. If an earlier layer contains the original file, the merge suppresses the original (keeps the whiteout marker so the deletion is preserved in the merged output). -
Opaque whiteout — A file
.wh..wh..opqin directory D means "the entire directory was replaced." All entries under D from earlier layers are suppressed. Only entries from the layer containing the opaque marker (and later layers) survive. -
Reintroduction supersedes whiteout — If a file is deleted (whiteout in layer M) then re-created (same path in layer N, where N > M), the whiteout is suppressed and the re-introduced file is kept. This prevents the merged layer from containing both a file and its own whiteout, which would cause overlay unpack failures.
Why this matters: Without whiteout suppression, merged layers could contain contradictory entries (a file and its .wh.* marker coexisting), causing EEXIST errors when the container runtime unpacks the layer onto an overlay filesystem.
Project directory override
ov image merge resolves image.yml via os.Getwd(). Override with -C <dir> / --dir <dir> / OV_PROJECT_DIR=<dir>. See /ov:image "Project directory resolution".
Cross-References
ov image family siblings
/ov:image-- Family overview + image.yml composition reference/ov:build-- Building images (merge runs inline after each build level)/ov:generate-- Containerfile generation/ov:inspect-- Inspect merged images/ov:list-- Enumerate images before merging/ov:new-- Scaffold new layers/ov:pull-- Pull prebuilt images into local storage/ov:validate-- Validate before merging
Related skills
/ov:layer-- Layer authoring (layer size affects merge behavior)
Related Skills
overthinkos/charly
tools
VerifiedTrustedCommunity
OpenCharly CLI (charly) binary installed into container/VM images for in-container use. Use when working with charly binary deployment inside containers, native D-Bus support, or the full charly toolchain (charly binary + virtualization + gocryptfs + socat).
SKILL.mdUpdated Jun 10, 2026
overthinkos/charly-cachyos
development
VerifiedTrustedCommunity
Operator CachyOS workstation profile — a kind:local template + target:local deploy that installs the full dev stack (30 candies) onto a CachyOS host via ShellExecutor. Lives in the overthinkos/cachyos submodule. MUST be invoked before editing or applying the charly-cachyos workstation profile.
SKILL.mdUpdated Jun 10, 2026
overthinkos/charly-fedora
tools
VerifiedTrustedCommunity
Fedora box with the full charly toolchain using shared candies. Rootless-first — runs as uid=1000 with passwordless sudo (no root, no cap_add: ALL). Same candy list as charly-arch. Includes NVIDIA GPU runtime. MUST be invoked before building, deploying, configuring, or troubleshooting the charly-fedora box.
SKILL.mdUpdated Jun 10, 2026
overthinkos/charly-arch
tools
VerifiedTrustedCommunity
Arch Linux box with the full charly toolchain. Rootless-first — runs as uid=1000 with passwordless sudo (no root, no cap_add: ALL). Composes /charly-coder:charly-mcp so the box is reachable as an MCP gateway on port 18765. NVIDIA GPU runtime composed in. MUST be invoked before building, deploying, configuring, or troubleshooting the charly-arch box.
SKILL.mdUpdated Jun 10, 2026