Add Apple Container agent skill

README.md

@@ -83,6 +83,14 @@ To retain your user data so that it is available should you reinstall later, run
 - [Build and run](./BUILDING.md) `container` on your own development system.
 - View the project [API documentation](https://apple.github.io/container/documentation/).
 
+### Agent skill
+
+Install the `apple-container` agent skill to help coding agents use `container` for Linux development workflows, image builds, networking, and troubleshooting:
+
+```bash
+npx skills add apple/container@apple-container
+```
+
 ## Contributing
 
 Contributions to `container` are welcome and encouraged. Please see our [main contributing guide](https://github.com/apple/containerization/blob/main/CONTRIBUTING.md) for more information.

skills/apple-container/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: apple-container
+description: Use Apple's `container` CLI for Linux container development on Apple silicon Macs. Trigger when users ask to run Linux commands on macOS, replace Docker Desktop with Apple Container, build or run OCI images, manage Apple container services, volumes, networks, registry auth, port forwarding, container machines, or debug Apple Container networking/service failures.
+metadata:
+  author: apple
+  version: "1.0.0"
+---
+
+# Apple Container
+
+Operate Apple's `container` CLI as a native macOS Linux container runtime for development, build, test, and debugging workflows.
+
+## First Moves
+
+1. Confirm the host is eligible before assuming `container` can run:
+   ```bash
+   sw_vers
+   uname -m
+   command -v container
+   container --version
+   ```
+   Require Apple silicon (`arm64`) and macOS 26 (Tahoe) or newer. The runtime relies on
+   macOS 26 virtualization and networking APIs; older macOS is not supported for real use.
+2. If `container` is not installed, install it (see [Install](#install)). Ask before running
+   privileged steps, since the installer writes under `/usr/local` and needs an admin password.
+3. Once `container` exists, start or verify the service:
+   ```bash
+   container system status || container system start
+   ```
+4. Run a smoke test before using it for real work:
+   ```bash
+   container run --rm docker.io/library/alpine:latest sh -lc 'uname -a; nslookup github.com'
+   ```
+5. For project work, mount the current directory and set `/work`:
+   ```bash
+   container run --rm -it -v "$PWD:/work" -w /work docker.io/library/ubuntu:24.04 bash
+   ```
+
+## Install
+
+Use Homebrew when available; it is the least error-prone path and keeps `container` upgradable
+with the user's other tooling:
+
+```bash
+brew install container
+```
+
+If Homebrew is not installed, use Apple's signed installer rather than installing Homebrew just for
+this. The official steps:
+
+1. Download the latest signed installer package for `container` from the
+   [GitHub release page](https://github.com/apple/container/releases).
+2. Double-click the package file and follow the instructions.
+3. Enter the administrator password when prompted, so the installer can place files under
+   `/usr/local`.
+
+When driving this from the terminal without a GUI, run the same package non-interactively (ask the
+user before the privileged step):
+
+```bash
+# After downloading container-<version>-installer-signed.pkg to the current directory:
+sudo installer -pkg ./container-*-installer-signed.pkg -target /
+```
+
+The installer places files under `/usr/local` and bundles helper scripts:
+
+```bash
+/usr/local/bin/update-container.sh           # upgrade in place
+/usr/local/bin/update-container.sh -v 0.3.0  # pin a specific version (downgrade)
+/usr/local/bin/uninstall-container.sh -k     # uninstall, keep user data
+/usr/local/bin/uninstall-container.sh -d     # uninstall, delete all data
+```
+
+After installing, initialize and verify the runtime:
+
+```bash
+container system start    # first run may prompt to install the recommended kernel; accept it
+container system status
+container --version
+```
+
+Note: `brew install container` succeeds on macOS 15 (Sequoia), but the runtime is only supported
+on macOS 26 (Tahoe) or newer — a clean install does not by itself prove the host can run
+containers. Always confirm the macOS version from step 1 before relying on it.
+
+Docs: [installation & user guide](https://apple.github.io/container/documentation/) ·
+[Homebrew formula](https://formulae.brew.sh/formula/container) ·
+[GitHub project](https://github.com/apple/container)
+
+## When To Prefer Apple Container
+
+- Use it when the user is on an Apple silicon Mac and needs Linux tooling that is missing or awkward on macOS.
+- Use it for disposable Linux commands, building OCI images, testing Dockerfiles/Containerfiles, running services with port forwarding, or reproducing Linux-only failures.
+- Prefer standard OCI images from registries (`docker.io/library/ubuntu:24.04`, `alpine:latest`, project images) and ordinary `container run` workflows first.
+- Use `container machine` only when the user needs a persistent Linux environment. Machine images must boot like a tiny system and provide `/sbin/init`; many minimal distro images are not suitable without customization.
+- Avoid assuming Docker CLI compatibility. The command is `container`, not `docker`, and some semantics differ.
+
+`container` is the CLI/runtime project. It uses Apple's Containerization Swift package for lower-level container, image, and process management. If the user asks to build Swift software directly against those lower-level APIs, consult `apple/containerization`; otherwise stay in this CLI workflow.
+
+## Core Workflows
+
+### Disposable Linux shell
+
+```bash
+container run --rm -it -v "$PWD:/work" -w /work docker.io/library/ubuntu:24.04 bash
+```
+
+### One-shot Linux command
+
+```bash
+container run --rm -v "$PWD:/work" -w /work docker.io/library/alpine:latest sh -lc 'apk --version && ls -la'
+```
+
+### Build and run an image
+
+```bash
+container build -t local/my-app:dev .
+container run --rm -p 8080:8080 local/my-app:dev
+```
+
+### Long-running service
+
+```bash
+container run -d --name web -p 8080:80 docker.io/library/nginx:latest
+container logs -f web
+container stop web
+container delete web
+```
+
+### Inspect, copy, and clean up
+
+```bash
+container list --all
+container inspect <container>
+container cp ./file.txt <container>:/tmp/file.txt
+container stats --no-stream
+container prune
+container image prune
+container system df
+```
+
+## References
+
+- Read [references/commands.md](references/commands.md) for command groups and feature coverage.
+- Read [references/workflows.md](references/workflows.md) for common dev, build, network, volume, registry, and machine patterns.
+- Read [references/troubleshooting.md](references/troubleshooting.md) when install, service, DNS, VPN, vmnet, kernel, builder, or machine mode fails.
+
+## Diagnostic Script
+
+Run the bundled diagnostic when the environment is unknown or networking behaves strangely:
+
+```bash
+bash skills/apple-container/scripts/diagnose.sh
+```
+
+From an installed skill path, use the equivalent path under that agent's skills directory.
+
+## Safety Notes
+
+- Ask before installing, upgrading, uninstalling, or running commands that require administrator privileges.
+- Do not delete containers, images, volumes, or machines unless they were created for the current task or the user explicitly asks for cleanup.
+- Stop services gracefully with `container stop` before using `container kill`.
+- Treat host bind mounts as real host filesystem access. Mount only the project directory unless the user requests a wider mount.
+- If a VPN is active, suspect route collisions or network filtering before changing container configuration.

skills/apple-container/metadata.json

@@ -0,0 +1,17 @@
+{
+  "version": "1.0.0",
+  "organization": "Apple Container",
+  "date": "June 2026",
+  "abstract": "Operational guide for Apple's native `container` CLI on Apple silicon Macs. Helps AI agents install and verify the runtime, run Linux development shells, build and manage OCI images, operate services, networks, volumes, registries, persistent machines, and diagnose vmnet, DNS, VPN, BuildKit, and machine boot failures.",
+  "references": [
+    "https://github.com/apple/container",
+    "https://apple.github.io/container/documentation/",
+    "https://formulae.brew.sh/formula/container",
+    "https://github.com/apple/container/releases",
+    "https://github.com/apple/container/blob/main/docs/command-reference.md",
+    "https://github.com/apple/container/blob/main/docs/how-to.md",
+    "https://github.com/apple/container/blob/main/docs/container-machine.md",
+    "https://github.com/apple/container/blob/main/docs/container-system-config.md",
+    "https://github.com/apple/containerization"
+  ]
+}

skills/apple-container/references/commands.md

@@ -0,0 +1,118 @@
+# Apple Container Commands
+
+Use this as a compact command map. Prefer `container <subcommand> --help` for exact flags on the installed version.
+
+## System
+
+- `container system start`: start API server, image service, networking helpers, machine API server, and first-run kernel setup.
+- `container system stop`: stop containers and system services.
+- `container system status`: show running state, app root, install root, and API server version.
+- `container system version`: show component versions.
+- `container system logs`: inspect service logs; use this for API server, vmnet, builder, and machine failures.
+- `container system df`: show disk usage for images, containers, and volumes.
+- `container system dns create|delete|list`: manage local DNS domains.
+- `container system kernel set`: set the default kernel.
+- `container system property list`: inspect system properties when supported by the installed release.
+
+System defaults live in `~/.config/container/config.toml`. Top-level sections include `[build]`, `[container]`, `[dns]`, `[kernel]`, `[network]`, `[registry]`, `[vminit]`, and `[plugin.<id>]`. Use config for persistent defaults; use CLI flags for task-local overrides.
+
+## Run And Build
+
+- `container run <image> [args...]`: create and run a container, pulling the image if needed.
+- `container build [context]`: build an OCI image from a Dockerfile or Containerfile using BuildKit.
+- `container builder start|status|stop|delete`: manage the builder container used for image builds.
+
+Important `run` flags:
+
+- `--rm`: remove the container after exit.
+- `-it`: interactive terminal.
+- `-v "$PWD:/work" -w /work`: mount and enter the current project.
+- `-p 8080:80`: publish a container port on localhost.
+- `--mount type=bind,source=...,target=...,readonly`: explicit bind mount syntax.
+- `--cpus 4 --memory 8G`: resource limits.
+- `--platform linux/arm64` or `--platform linux/amd64`: choose image platform.
+- `--rosetta`: enable Rosetta for compatible amd64 workloads.
+- `--ssh`: forward the host SSH agent.
+- `--init`: run an init process that forwards signals and reaps processes.
+- `--init-image <image>` and `--kernel <path>`: advanced boot customization.
+- `--network <name>[,mac=...][,mtu=...]`: attach a network.
+- `--dns`, `--dns-search`, `--no-dns`: override DNS behavior.
+- `--cap-add`, `--cap-drop`, `--read-only`, `--tmpfs`, `--shm-size`, `--ulimit`: runtime isolation and process settings.
+- `--virtualization`: expose virtualization capabilities to the container when host and guest support it.
+
+Important `build` flags:
+
+- `-t, --tag <name>`: tag output image; may be repeated.
+- `-f, --file <path>`: choose Dockerfile/Containerfile.
+- `--target <stage>`: build a named stage.
+- `--build-arg key=value`: pass build args.
+- `--secret id=...,env=...` or `--secret id=...,src=...`: pass build secrets.
+- `--platform os/arch[/variant]`: build for a platform.
+- `--pull`, `--no-cache`: control freshness and cache use.
+- `--cpus`, `--memory`: resource limits for the builder.
+- `--output type=oci|tar|local[,dest=...]`: choose output.
+
+## Container Lifecycle
+
+- `container create`: create without starting.
+- `container start [-a] [-i] <id>`: start a stopped container.
+- `container exec [-it] <id> <cmd...>`: run a command in a running container.
+- `container stop [--all] [--signal SIGTERM] [--time 5] <id...>`: graceful stop.
+- `container kill [--all] [--signal KILL] <id...>`: immediate signal.
+- `container delete|rm [--all] [--force] <id...>`: remove containers.
+- `container list|ls [--all] [--format json|yaml|toml|table]`: list containers.
+- `container inspect <id...>`: inspect containers.
+- `container logs [--boot] [--follow] [-n N] <id>`: show stdio or boot logs.
+- `container stats [--no-stream] [--format json|yaml|toml|table] [id...]`: resource usage.
+- `container copy|cp <src> <dest>`: copy between host and running container using `id:/path`.
+- `container export [-o file.tar] <stopped-id>`: export a stopped container filesystem.
+- `container prune`: delete stopped containers.
+
+## Images
+
+- `container image pull <ref>`: pull from a registry.
+- `container image list|ls [-v] [--format json|yaml|toml|table]`: list local images.
+- `container image inspect <ref...>`: inspect images.
+- `container image tag <source> <target>`: create another reference.
+- `container image push <ref>`: push to a registry.
+- `container image save -o image.tar <ref...>`: save image archive.
+- `container image load -i image.tar`: load image archive.
+- `container image delete|rm [--all] [--force] <ref...>`: remove images.
+- `container image prune [-a]`: remove unused images.
+
+## Registry
+
+- `container registry login <server>`: authenticate to a registry.
+- `container registry logout <server>`: remove auth.
+- `container registry list|ls`: list registry logins.
+
+`--scheme auto` treats loopback, RFC1918 private IPs, and container DNS-domain hosts as internal/local and uses HTTP; otherwise it uses HTTPS.
+
+## Network
+
+- `container network create [--subnet CIDR] [--subnet-v6 CIDR] [--internal] <name>`: create a NAT or host-only network.
+- `container network list|ls`: list networks.
+- `container network inspect <name>`: inspect subnet, gateway, and mode.
+- `container network delete|rm <name...>`: remove networks.
+- `container network prune`: remove unused networks.
+
+The built-in `default` network is NAT-backed by vmnet. On macOS, VPNs and network filters can interfere with the VM bridge or route table.
+
+## Volumes
+
+- `container volume create <name>`: create a managed volume.
+- `container volume list|ls`: list volumes.
+- `container volume inspect <name>`: inspect details.
+- `container volume delete|rm <name...>`: delete volumes.
+- `container volume prune`: remove unused volumes.
+
+Use bind mounts for direct project access; use volumes for runtime data that should not live in the project tree.
+
+## Machines
+
+- `container machine create <image> --name <name> [--set-default] [--cpus N] [--memory 8G] [--home-mount rw|ro|none]`: create and boot a persistent Linux machine.
+- `container machine run [-n name] -- <cmd...>`: run a command or shell, booting the machine if needed.
+- `container machine set -n <name> cpus=4 memory=8G home-mount=ro`: change configuration; restart to apply.
+- `container machine list|ls`, `inspect`, `logs`, `stop`, `delete`, `set-default`: manage machines.
+
+Machine images need a suitable `/sbin/init`. If a plain distro image exits with `/sbin/init: not found` or similar, use a machine-oriented image or build a custom image with a minimal init.