DockerShark is a failure-mode-first skill for Dockerfiles, BuildKit builds, container images, and image supply-chain work.
LLMs often produce Dockerfiles that work locally but fail production requirements. They leak secrets through build layers, run as root, use mutable base tags, copy huge contexts, skip SBOM/provenance, and confuse build-time and runtime dependencies.
DockerShark forces the agent to diagnose those failure modes before it writes or reviews image artifacts.
The core SKILL.md is procedural and compact. Detailed guidance lives in focused reference files, loaded only when the diagnosed failure mode or detected runtime requires it.
DockerShark is grounded in Docker build guidance, BuildKit secret handling, CIS-style container hardening, OpenSSF/SLSA supply-chain principles, and OCI image practices. It is not affiliated with Docker, Inc.
Clone this repository and place it where your agent runtime discovers skills. For Codex repo-scoped use, copy or symlink the repository into .agents/skills/docker-skill.
mkdir -p .agents/skills
git clone https://github.com/LukasNiessen/docker-skill.git .agents/skills/docker-skillThen ask naturally:
Review this Dockerfile for security, size, and reproducibility issues.
Or invoke explicitly:
$docker-skill Create a production Dockerfile for this FastAPI app.
| Dimension | DockerShark | Generic Docker prompt |
|---|---|---|
| Diagnoses before generating | Yes | Usually no |
| Secret layer guidance | Explicit | Often missed |
| Runtime hardening | Required review dimension | Often omitted |
| Build context/cache risk | First-class failure mode | Rarely considered |
| Language-specific CRR | Node, Python, Go, Java, .NET | Usually generic |
| Supply-chain controls | SBOM, signing, scanning, provenance | Often superficial |
| Output contract | Assumptions, tradeoffs, validation, rollback | No consistent contract |
- Keep
SKILL.mdsmall and procedural. - Move detailed patterns into focused references.
- Load primary references by diagnosed failure mode.
- Load conditional references only when language, image family, BuildKit, Compose, or registry signals appear.
- Exclude generic Docker tutorials unless they prevent a concrete failure mode.
DockerShark uses conditional reference retrieval for language/runtime and tooling specifics:
- Node.js, Python, Go, Java/JVM, .NET
- Alpine, Debian/Ubuntu slim, distroless, scratch
- BuildKit/buildx, Docker Compose, registries
A plain Dockerfile review does not load every language and registry guide.
- A compact failure-mode workflow in
SKILL.md - Seven primary image failure-mode references
- Language and tool-specific conditional references
- Good, bad, and neutral pattern banks
- Validation and scanning guidance
- Runtime hardening and multi-stage build patterns
- UI metadata in
agents/openai.yaml
| File | Purpose |
|---|---|
SKILL.md |
Operational workflow for DockerShark |
agents/openai.yaml |
Codex app metadata |
references/secret-layer-leakage.md |
Secret handling and layer leakage |
references/insecure-runtime-defaults.md |
Root/runtime defaults and container hardening |
references/base-image-drift.md |
Base image trust, mutability, patch cadence |
references/bloated-fragile-images.md |
Image size, multi-stage builds, runtime minimization |
references/build-context-cache-risk.md |
.dockerignore, cache safety, context hygiene |
references/dependency-package-drift.md |
Lockfiles and deterministic installs |
references/sbom-signing-provenance-gaps.md |
SBOM, signing, scanning, provenance |
references/conditional/ |
Language, BuildKit, Compose, and registry references |
- Capture context: runtime, base image, builder, registry, target, security posture.
- Diagnose likely failure modes.
- Load only matching references.
- Propose changes with risk controls.
- Generate Dockerfile/build artifacts.
- Validate with build, inspect, scan, and smoke-test steps.
- Return assumptions, tradeoffs, tests, and rollback notes.
DockerShark covers:
- Dockerfiles and
.dockerignore - BuildKit/buildx image builds
- Docker Compose build concerns
- container image hardening and size reduction
- SBOM, signing, scanning, digest promotion
- registry push/pull/auth/retention concerns
DockerShark does not replace a full CI/CD skill for pipeline-wide release governance.
Does this only support Docker?
It focuses on Dockerfile-compatible container image workflows and OCI image concerns. Podman/buildah users can still reuse much of the guidance, but Docker/BuildKit are the default vocabulary.
Does it always require distroless?
No. Distroless is one option. DockerShark treats Alpine, Debian/Ubuntu slim, distroless, scratch, and vendor images as context-dependent choices.
Will it generate production-ready Dockerfiles?
It will generate safer Dockerfiles and validation steps. Production readiness still depends on build context, app behavior, registry controls, and deployment environment.
Contributions should reduce a named failure mode, improve conditional routing, or add concise validation patterns. Keep the skill lean.
MIT