Docker Development Skill

imageLicense imageClaude Code Compatible

Agent Skill for Docker image development - Dockerfile best practices, CI testing patterns, and Docker Compose orchestration.

Features

• Dockerfile Best Practices - Multi-stage builds, layer optimization, security
• CI Testing Patterns - Test Docker images reliably in CI pipelines
• Docker Compose - Service orchestration, health checks, networking
• Docker Bake - Multi-platform builds with BuildKit
• Security - Vulnerability scanning, non-root users, secret management
• Windows / WSL2 - Run docker through WSL when Docker Desktop uses the WSL2 backend (separate docker-via-wsl skill)

Skills

This package bundles two skills:

• docker-development — Dockerfile, compose, bake, CI testing, and security patterns.
• docker-via-wsl — for AI agents running on a Windows host outside WSL: re-issue every docker/docker compose command inside WSL (via wsl.exe) so Docker Desktop's WSL2 backend does not corrupt bind-mount paths.

Automatic Triggers

The docker-development skill activates automatically when working with:

The docker-via-wsl skill activates when an agent on a Windows shell (Git Bash/MSYS/PowerShell, outside WSL) is about to run any docker command.

Installation

Marketplace (Recommended)

Add the Netresearch marketplace once, then browse and install skills:

# Claude Code
/plugin marketplace add netresearch/claude-code-marketplace
/plugin install docker-development@netresearch-claude-code-marketplace

Without a marketplace

Since Claude Code 2.1.157 a plugin directory under your personal skills directory loads on its own:

mkdir -p ~/.claude/skills
git clone https://github.com/netresearch/docker-development-skill.git \
  ~/.claude/skills/docker-development

It loads as docker-development@skills-dir on the next session. Update with git -C ~/.claude/skills/docker-development pull and start a new session; remove it by deleting the directory. This route has no claude plugin update.

npx (skills.sh)

Install with any Agent Skills-compatible agent:

npx skills add https://github.com/netresearch/docker-development-skill --skill docker-development
npx skills add https://github.com/netresearch/docker-development-skill --skill docker-via-wsl

Download Release

Download the latest release and extract to your agent's skills directory.

Git Clone

git clone https://github.com/netresearch/docker-development-skill.git

Composer (PHP Projects)

composer require netresearch/docker-development-skill

Requires netresearch/composer-agent-skill-plugin.

Usage

The skill activates automatically when working on:

• Dockerfile development
• Docker Compose configurations
• Docker Bake multi-platform builds
• CI/CD pipelines for container images
• Container troubleshooting

Example Prompts

• "Create a multi-stage Dockerfile for a Node.js app"
• "Set up GitHub Actions to build and push Docker images"
• "Why is my nginx config test failing in CI?"
• "Add health checks to my docker-compose.yml"
• "Create a docker-bake.hcl for multi-platform builds"

Key Patterns

Testing Images with Entrypoints

# Bypass entrypoint for direct testing
docker run --rm --entrypoint php myimage -v

Testing nginx Configs in Isolation

# Mock upstream DNS
docker run --rm --add-host backend:127.0.0.1 nginx-image nginx -t

Compose Validation in CI

# Create .env before validation
cp .env.example .env
sed -i 's/PLACEHOLDER/test_value/g' .env
docker compose config > /dev/null

References

Extended documentation in the skill references/ directories:

• docker-development/references/ci-testing.md - Retro-born CI testing gotchas
• docker-via-wsl/references/diagnosis-and-fix.md - Diagnose and fix a wrong bind mount caused by driving Docker from a Windows shell

Contributing

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

Tests

The behavioural tests live in tests/ and need bash, git and python3; tests/check-allowed-tools.sh also needs yq (v4):

bash tests/check-plugin-version.sh  # Build/Scripts/check-plugin-version.sh and Build/hooks/pre-push
bash tests/check-allowed-tools.sh   # allowed-tools in every skills/*/SKILL.md

tests/check-plugin-version.sh builds throwaway git repositories and checks that a semver tag at HEAD (with or without a v prefix) must match the version in .claude-plugin/plugin.json, that non-semver tags and untagged commits pass, that an empty version or a missing plugin.json fails, and that the pre-push hook passes the result on.

tests/check-allowed-tools.sh reads the allowed-tools list of every skills/*/SKILL.md and fails when an entry is not one of the read-only tools it names (Read, Glob, Grep, grep, uname and the read-only docker subcommands version, info, ps, images, inspect, history, logs). It reads the front matter with yq, so a YAML list and a string of tools are read in every YAML form; it needs bash, yq (v4) and python3.

Each check prints ok or FAIL; a FAIL line is followed by the expected and actual exit code and the script's output. The test exits 1 when any check failed. In CI, the Skill Tests workflow (.github/workflows/tests.yml) runs every tests/**/*.sh on each pull request and on pushes to main.

The skills themselves are instructions in Markdown and ship no executable scripts; Skill Validation and Eval Validation check their structure and the eval definitions in evals/evals.json. A pull request that adds or changes behaviour in a script adds or updates a check in tests/ that fails without the change.

Governance and policies

This repository follows the Netresearch organisation policies:

• Governance: ownership, roles, how decisions are made and disputes resolved, and continuity.
• Roadmap: planned and explicitly excluded work for the coming year.
• Handling of dependency and code analysis findings: thresholds, deadlines and the exception process for dependency (SCA) and static analysis (SAST) findings.
• Secret management: how CI and release credentials are stored, accessed and rotated.
• Access roster: who holds administrative access to this repository and the organisation.

The security assurance case for this skill (threat model, trust boundaries, countermeasures and limits) is in docs/SECURITY-ASSURANCE.md.

Checks that run on pull requests in this repository:

• Every pull request: Skill Validation (lint.yml: skill structure, markdownlint, yamllint, actionlint, JSON syntax, ShellCheck, ruff, checkpoint schema), Eval Validation (eval-validate.yml) and Skill Tests (tests.yml).
• Pull requests to main: security.yml with Betterleaks (secret scanning), zizmor (workflow static analysis), dependency review, Composer Audit and Opengrep SAST (both behind a preflight event-gate job); Harness Verification (harness-verify.yml) and Template Drift (check-template-drift.yml). The organisation's security policy sets when dependency review and Opengrep fail: see dependencies and static analysis (SAST).
• Also on every pull request: Labeler (labeler.yml), the DCO sign-off check, SonarCloud Code Analysis and the CodeRabbit review status (GitHub Apps) and, for dependency-update pull requests, auto-merge (auto-merge-deps.yml). CodeQL for actions runs through GitHub's default setup.

License

This project uses split licensing:

• Code (scripts, workflows, configs): MIT
• Content (skill definitions, documentation, references): CC-BY-SA-4.0

See the individual license files for full terms.

Author

Netresearch DTT GmbH