Devcontainers best practices

Skill afonsograca/devcontainers-best-practices/skills/devcontainers-best-practices

Agent skill for devcontainer.json, the Dev Container spec, Features, Templates & tools (VS Code, Codespaces, Cursor, Zed, Podman).

Install

npx -y skills add afonsograca/devcontainers-best-practices --skill devcontainers-best-practices

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Expert reference for the Dev Container ecosystem. Consult this skill whenever the user is setting up a dev container, configuring or debugging devcontainer.json, working in a Docker-based development environment, or asking about dev containers, GitHub Codespaces, DevPod, or Zed — even if they don't say "devcontainer" explicitly. Covers the full Dev Container spec, schema validation, tool-specific behaviors and limitations (VS Code, Cursor, Zed, Codespaces, CodeSandbox, Podman), Features and Templates (choosing, authoring, publishing), lifecycle scripts, environment variables, port forwarding, multi-container setups, and official best practices from containers.dev and devcontainers.github.io. Also use when the user is confused by container behavior that differs between tools, wants to write or publish a custom Feature, or needs to validate or debug a devcontainer.json.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

10.8 KB, as published. Nobody here has run it

Devcontainers Best Practices

This skill guides you to the right documentation and references for the Development Container ecosystem. Use it when working with devcontainer.json, selecting Features or Templates, or when the user asks about dev containers, containers.dev, or supporting tools.

Quick start

Minimal devcontainer.json using an image and a Feature: "image": "mcr.microsoft.com/devcontainers/base:ubuntu", "features": { "ghcr.io/devcontainers/features/git:1": {} }. For property details and validation, see Quick lookup item 1 and references/schema.md.

When to use this skill

Editing or validating devcontainer.json
Looking up a property (syntax, type, tool support)
Choosing or referencing a Feature or Template
Checking which tools support the spec or have tool-specific properties/limitations
Understanding the spec (lifecycle, merge logic, image metadata)
Authoring or publishing a Dev Container Feature (see the Authoring section in references/features.md and the containers.dev authoring guide)
Configuring multiple dev containers (multi-project, shared Compose); see references/tools.md and VS Code / multi-container docs

Canonical sources

All content in this skill and its references is traceable to these sources:

Spec and reference: containers.dev/implementors/spec, containers.dev/implementors/json_reference
Schema: containers.dev/implementors/json_schema
Guides: containers.dev/guides (prebuilds, using Dockerfile/Compose, Feature authoring best practices, GitLab CI)
Supporting tools: devcontainers.github.io/supporting
Features: containers.dev/implementors/features, github.com/devcontainers/features
Templates: containers.dev/implementors/templates, github.com/devcontainers/templates

Reference files

Detailed material is in the references/ directory. Load only what you need.

Need	File
When to use the full spec, key concepts, merge logic, lifecycle	references/spec.md
JSON reference vs schema, canonical URLs, how to validate	references/schema.md
Supporting tools, tool-specific properties, limitations	references/tools.md
VS Code workflows, requirements, prebuild, ports, extensions, limitations, dotfiles, managing containers	references/vscode-containers.md
Tips and tricks (OS, Git, performance, troubleshooting, profile persistence, reporting)	references/tips-and-tricks.md
Official Features, OCI refs, versioning, options, install order, authoring Features	references/features.md
Official Templates, when to use template vs Feature vs Dockerfile	references/templates.md

Quick lookup

Property or behavior in devcontainer.json
Use the Dev Container metadata reference (or references/spec.md) for property-by-property details. For validation, use the devcontainer.json schema or Dev Container CLI; see references/schema.md.
Tool support or tool-specific settings
Check devcontainers.github.io/supporting for the list of tools, customizations.* (e.g. customizations.vscode, customizations.codespaces), and limitations. Summary in references/tools.md.
Advanced scenarios (env vars, mounts, performance, non-root user, remote Docker, multiple containers, Git credentials)
See VS Code Advanced container configuration. Summary and workflow links in references/vscode-containers.md.
Multiple dev containers (multi-project, shared Docker Compose)
See references/tools.md “Multiple containers / multi-project” and Chris Ayers – Multiple dev containers.
OS-specific or troubleshooting (Git, Docker Desktop, cleanup, logs)
See VS Code Dev Containers Tips and Tricks. Summary in references/tips-and-tricks.md.
Feature ID, options, or install order
Official Features: containers.dev/features, github.com/devcontainers/features. OCI refs: ghcr.io/devcontainers/features/<name>:<version>. Details in references/features.md. For authoring Features, see the Authoring section there and containers.dev/guide/feature-authoring-best-practices.
Template or "template vs Feature vs Dockerfile"
Official Templates: containers.dev/templates, github.com/devcontainers/templates. When to use which: references/templates.md.
Spec concepts (lifecycle, merge, image metadata)
Full spec: containers.dev/implementors/spec. Summary: references/spec.md.

Best practices (from official docs)

Only apply recommendations that are stated in the spec or official devcontainer documentation; cite the source when relevant.

Environment variables: Prefer containerEnv over remoteEnv when possible so all processes in the container see the variable and it is not client-specific. Use remoteEnv when the value is not static and you want to avoid rebuilding. (Dev Container metadata reference – containerEnv/remoteEnv.)
Port forwarding: In most cases use the forwardPorts property rather than appPort; forwarded ports behave like localhost to the application. Use appPort (or Docker Compose ports) when you need published/network-visible ports. (VS Code – Forwarding or publishing a port, Dev Container metadata reference.)
Pre-build when possible: Pre-building images (e.g. with Dev Container CLI or GitHub Actions) speeds up startup and lets you pin tool versions; image metadata can be inherited so repos need only a minimal devcontainer.json. (VS Code – Pre-building dev container images, containers.dev/guides.)
Security and trust: Dev container configs and images can run arbitrary commands. Only use configs and images from trusted sources. For sandboxing and security context, see the spec and community articles (e.g. The Red Guild – Where do you run your code with attribution).
Feature versions: To pin to a specific version, append it to the Feature ID (e.g. from the versions list). The :latest tag is applied implicitly if omitted. (Features – containers.dev.)
Rebuild after changes: After changing the dev container configuration, rebuild so tools pick up changes (e.g. "Dev Containers: Rebuild Container" or "Codespaces: Rebuild Container" in the command palette, in VS Code or compatible editors such as Cursor). (VS Code Dev Containers extension, GitHub Codespaces.)
Lifecycle script order: Creation scripts run in this order: onCreateCommand → updateContentCommand → postCreateCommand. If one fails, later scripts are not run. (Dev Container metadata reference – Lifecycle scripts.)

When the spec or official docs do not state a recommendation, do not present it as a best practice; either omit it or phrase it as a suggestion with a clear citation.

Optional / community guidance: Community articles (e.g. Daytona – Ultimate guide to dev containers) suggest practices such as keeping images lightweight, caching dependencies, and using Docker Compose for multi-service setups. Use with attribution and prefer spec/official docs when they conflict.

Summary

Use this skill when editing devcontainer.json, choosing Features/Templates, authoring Features, or answering questions about dev containers or containers.dev.
Resolve questions via the canonical URLs above and the reference files under references/.
Best practices: cite containers.dev or devcontainers.github.io; only include guidance that appears there. For OS-specific or troubleshooting issues, consult VS Code Dev Containers Tips and Tricks and references/tips-and-tricks.md.