@kothar-hq/host-container-capabilities 0.0.0-stage → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Justin Dearing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# host-container-capabilities
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [agent skill](https://agentskills.io) that finds out which container engines a host has, and routes container work to a local engine or to CI.
+
+Coding agents run on Windows hosts (some with WSL), on Linux and macOS, inside WSL, and in cloud sandboxes. An agent that assumes `docker` reaches a Linux engine gets it wrong on a Windows host in Windows-container mode, and one that "fixes" that by switching Docker Desktop stops every container on the host. This skill gives the agent a probed report instead:
+
+- **Windows engine:** whether one answers, and the isolation (`process` or `hyperv`) that ltsc2019, ltsc2022 and ltsc2025 images need on this host build.
+- **Linux engine:** the default WSL distro's own Docker, then other WSL 2 distros, then the default docker context, then an existing Docker Desktop Linux pipe. On Linux and macOS, the docker CLI's current context.
+- **Routing:** run locally when the engine exists, otherwise offer the project's CI workflow.
+- **Shared-host safety:** everything the agent creates is named and labelled, and only that is cleaned up. Docker Desktop is never switched, and no daemon is started or installed without asking.
+
+The report is cached per project for 24 hours.
+
+## Install
+
+With the [skills CLI](https://skills.sh), from GitHub:
+
+```sh
+npx skills add kothar-hq/host-container-capabilities
+```
+
+From npm, with the installer in the package:
+
+```sh
+npx @kothar-hq/host-container-capabilities install            # into ./.claude/skills
+npx @kothar-hq/host-container-capabilities install --global   # into ~/.claude/skills
+npx @kothar-hq/host-container-capabilities install --dir .agents/skills
+```
+
+Or as a dev dependency, synced by the skills CLI:
+
+```sh
+npm install --save-dev @kothar-hq/host-container-capabilities
+npx skills experimental_sync
+```
+
+Then add `.claude/*.local.json` to the project's `.gitignore`: the probe caches its report in `.claude/host-container-capabilities.<platform>.local.json`.
+
+## Use
+
+The agent loads the skill before container work. To read the report yourself:
+
+```sh
+sh .claude/skills/host-container-capabilities/scripts/host-capabilities.sh
+```
+
+```pwsh
+.claude/skills/host-container-capabilities/scripts/Get-HostCapabilities.ps1 -AsJson
+```
+
+[SKILL.md](skills/host-container-capabilities/SKILL.md) describes the report's fields, the routing rules, the naming and labelling convention, and the per-host overrides file.
+
+## Requirements
+
+- Windows: PowerShell 7. Linux, macOS and WSL: a POSIX `sh`.
+- The installer needs Node.js 20 or later. The skill itself doesn't need Node.
+- Docker is the only container runtime probed today. Podman and others are tracked in the [issues](https://github.com/kothar-hq/host-container-capabilities/issues).
+
+## Versions
+
+0.9 is the first public release: the skill as it has been used in [zippy1981/windows-nano-baseimages](https://github.com/zippy1981/windows-nano-baseimages), made project-neutral. The report's `schemaVersion` is 1. 1.0 will follow once the report's fields are settled. See the [changelog](CHANGELOG.md).
+
+## Develop
+
+```sh
+npm test          # node --test: the package, the installer, and the real probe for this platform
+npm run lint:md   # markdownlint
+```
+
+CI also runs shellcheck, actionlint, PSScriptAnalyzer and CodeQL, and the tests on Linux, macOS and Windows. A change to `main` goes through a pull request.
+
+A release is a pull request that changes `version` in `package.json`, in `SKILL.md` and in `CHANGELOG.md` (a test checks that they agree). Merging it runs the `release` workflow, which publishes to npm with provenance, and creates the `vX.Y.Z` tag and the GitHub release.
+
+## Licence
+
+[MIT](LICENSE)

package/bin/host-container-capabilities.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// Installs the host-container-capabilities skill from this package into a project's (or the user's) skills directory.
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const skillName = 'host-container-capabilities';
+const skillSource = join(packageRoot, 'skills', skillName);
+
+const usage = `Usage: ${skillName} <command> [options]
+
+Commands:
+  install          Copy the skill into .claude/skills/${skillName} in the current directory
+  path             Print the directory of the skill inside this package
+  version          Print the package version
+
+Options for install:
+  --global         Install into ~/.claude/skills instead of the current directory
+  --dir <path>     Install into <path>/${skillName} instead (for other agents' skills directories)
+  --force          Replace an existing copy
+`;
+
+function fail(message) {
+    process.stderr.write(`${skillName}: ${message}\n`);
+    process.exit(1);
+}
+
+function install(args) {
+    let target = join(process.cwd(), '.claude', 'skills');
+    let force = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--global') {
+            target = join(homedir(), '.claude', 'skills');
+        } else if (arg === '--dir') {
+            const dir = args[++i];
+            if (!dir) fail('--dir needs a path');
+            target = resolve(dir);
+        } else if (arg === '--force') {
+            force = true;
+        } else {
+            fail(`unknown option '${arg}'`);
+        }
+    }
+    const destination = join(target, skillName);
+    if (existsSync(destination)) {
+        if (!force) fail(`${destination} already exists. Pass --force to replace it.`);
+        rmSync(destination, { recursive: true });
+    }
+    mkdirSync(target, { recursive: true });
+    cpSync(skillSource, destination, { recursive: true });
+    process.stdout.write(`Installed ${skillName} to ${destination}\n`);
+}
+
+const [command, ...rest] = process.argv.slice(2);
+switch (command) {
+    case 'install':
+        install(rest);
+        break;
+    case 'path':
+        process.stdout.write(`${skillSource}\n`);
+        break;
+    case 'version':
+    case '--version':
+    case '-v':
+        process.stdout.write(`${JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).version}\n`);
+        break;
+    case undefined:
+    case 'help':
+    case '--help':
+    case '-h':
+        process.stdout.write(usage);
+        break;
+    default:
+        process.stderr.write(usage);
+        fail(`unknown command '${command}'`);
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@kothar-hq/host-container-capabilities",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.0",
+  "description": "An agent skill that finds out which container engines a host has (Windows, Linux, WSL) and routes container work to a local engine or to CI.",
+  "keywords": [
+    "agent-skill",
+    "agent-skills",
+    "skills",
+    "claude-code",
+    "docker",
+    "wsl",
+    "windows-containers"
+  ],
+  "license": "MIT",
+  "author": "Justin Dearing",
+  "homepage": "https://github.com/kothar-hq/host-container-capabilities#readme",
+  "bugs": "https://github.com/kothar-hq/host-container-capabilities/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kothar-hq/host-container-capabilities.git"
+  },
+  "type": "module",
+  "bin": {
+    "host-container-capabilities": "bin/host-container-capabilities.mjs"
+  },
+  "files": [
+    "bin",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint:md": "npx -y markdownlint-cli@0.50.0 --dot \"**/*.md\""
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/skills/host-container-capabilities/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: host-container-capabilities
+description: Find out which container engines this host has (a Windows engine for Windows containers, a Linux engine such as a WSL distro's own Docker, both, or neither) and route container work to a local engine or to CI. Use before any docker command, before building or testing an image, before running Linux tools such as shellcheck or actionlint in a container, or when asked whether this machine can run Linux or Windows containers.
+license: MIT
+metadata:
+  version: "0.9.0"
+  repository: https://github.com/kothar-hq/host-container-capabilities
+---
+
+# Host container capabilities
+
+Coding agents run on Windows hosts (some with WSL), on Linux and macOS, inside WSL, and in cloud sandboxes. Don't assume which engines exist. Read the probe's report, then route the task.
+
+The probe scripts are in this skill's `scripts/` directory, next to this file. Below, `<skill>` is the directory that holds this `SKILL.md`.
+
+## 1. Read the report
+
+| Shell | Command |
+| --- | --- |
+| PowerShell (Windows) | `<skill>/scripts/Get-HostCapabilities.ps1 -AsJson` |
+| Bash or sh (any OS; Git Bash hands off to the PowerShell script) | `sh <skill>/scripts/host-capabilities.sh` |
+
+Run it from inside the project. The project root is the git work tree around the current directory, or `HOST_CONTAINER_CAPABILITIES_ROOT` if that's set.
+
+A cached report is reused for 24 hours, so it's cheap to read again. Probe again (`-Refresh`, or `--refresh` for the sh script) when a docker command can't reach its engine, when the user says something on the host changed, or before telling the user the host can't do something. On Windows a fresh probe boots WSL distros, one after another, until one has a working Docker.
+
+The fields that decide things:
+
+| Field | Meaning |
+| --- | --- |
+| `platform` | `windows`, `wsl` (the agent is running inside WSL), `linux` or `macos` |
+| `windowsEngine.available`, `.invoke` | Whether a Windows engine answers, and the command that reaches it (`docker`, or `docker.exe` from inside WSL) |
+| `windowsEngine.ltsc.<2019\|2022\|2025>.isolation` | `process`, `hyperv`, or `null` when that Windows version's images can't run here. Only filled in on Windows. |
+| `linuxEngine.available`, `.invoke` | Whether a Linux engine answers, and the command that reaches it, for example `["wsl.exe","--distribution","Ubuntu","--exec","docker"]` |
+| `linuxEngine.repoPath` | The project's path as the Linux engine's host sees it, for bind mounts |
+| `linuxEngine.containers` minus `.claudeContainers` | Containers that belong to someone else (the user's devcontainers, CI runners). Leave them alone. |
+| `linuxEngine.reason`, `.tried` | Why there's no Linux engine, and what was tried |
+| `policy.sharedHost` | `true` unless the user overrode it. Shared means strict cleanup (section 4). |
+| `policy.createdByLabel`, `.sessionLabelKey` | The labels to put on everything you create (section 4) |
+| `github.authenticated` | Whether `gh` can dispatch workflows |
+
+## 2. Route the task
+
+If the project has its own routing table (in `CLAUDE.md`, `AGENTS.md` or its docs), follow it. Otherwise:
+
+| Task | Run locally when | Otherwise |
+| --- | --- | --- |
+| Build or test a Windows container image | `windowsEngine.available`, and that Windows version's `isolation` isn't `null`. Pass `--isolation <value>`. Hyper-V isolated builds default to 1 GB of memory, so pass `--memory 4g` or more. | The project's CI workflow for that image |
+| Build or test a Linux container image | `linuxEngine.available` | The project's CI workflow for that image |
+| Linux tools in a container (shellcheck, actionlint, a build script) | `linuxEngine.available`, with the tool version CI uses | The project's lint or build workflow |
+| A release, or anything published | Never locally, unless the project says otherwise | The project's release workflow |
+| Tools that need no container (PSScriptAnalyzer, Pester, npm scripts) | Any host that has the tool | CI |
+
+Dispatching a workflow is outward-facing, so ask before `gh workflow run`. If `github.authenticated` is false, ask the user to log in with `gh auth login`. Never handle tokens.
+
+## 3. Run on the engine
+
+Use `invoke` exactly as the report gives it, with the docker arguments after it.
+
+```pwsh
+$report = <skill>/scripts/Get-HostCapabilities.ps1
+$linux = $report.linuxEngine
+& $linux.invoke[0] @($linux.invoke | Select-Object -Skip 1) run --rm --name agent-lint-3f9a `
+    --label $report.policy.createdByLabel --label "$($report.policy.sessionLabelKey)=3f9a" `
+    --volume "$($linux.repoPath):/src:ro" --workdir /src rhysd/actionlint:1.7.12 -color
+```
+
+- **Prefer PowerShell on Windows.** Git Bash rewrites arguments that look like paths (`/src` becomes `C:/Program Files/Git/src`), so in Bash prefix the command with `MSYS_NO_PATHCONV=1`.
+- **`--exec` runs docker without a shell** inside the distro. Don't pass `bash -lc '...'` through `wsl.exe`: the quoting breaks and `$variables` are expanded in the wrong place.
+- **`/mnt/c` is slow.** That's fine for linters and for reading the project. For a real build, copy the sources into the container or a Linux directory instead of building on the bind mount.
+- **Line endings:** a shell script checked out with CRLF fails in a Linux container. Check that `.gitattributes` keeps `*.sh` LF before running the project's scripts from a Windows checkout.
+- **Registry pulls:** if a pull is denied, the image is private, and logging in is the user's call.
+
+## 4. Name, label and clean up
+
+On a shared host (`policy.sharedHost`, the default), everything you create carries:
+
+- a name `agent-<task>-<tag>`, where `<tag>` is 4 hex characters you pick once per session
+- `--label <policy.createdByLabel> --label <policy.sessionLabelKey>=<tag>`, on `docker run`, `docker create` and `docker build`
+
+Prefer images that are already present (`docker images`). If you pull one, note that it wasn't there before, and remove exactly that reference when you're done.
+
+Clean up only what carries your session's label, on the engine you created it on:
+
+```sh
+docker ps -aq --filter label=<policy.sessionLabelKey>=<tag> | xargs -r docker rm -f
+docker images -q --filter label=<policy.sessionLabelKey>=<tag> | xargs -r docker rmi
+```
+
+Never `docker system prune`, `docker image prune` or `docker builder prune` on a shared host.
+
+## 5. When an engine is missing
+
+- **No Linux engine, but WSL is installed** (`linuxEngine.tried` names the distros): offer to install Docker Engine in the distro, or to start its daemon if `tried` says it isn't reachable. Both are host changes, so ask first. Otherwise, offer the CI workflow.
+- **No Linux engine and no WSL** (Windows without WSL, or a Linux or macOS host without Docker): offer the CI workflow, or report what's missing.
+- **No Windows engine** (Linux, macOS, or a cloud sandbox): Windows container images can only be built in CI, on a Windows runner. Don't try workarounds.
+
+## 6. Never
+
+- Switch Docker Desktop between Windows and Linux containers, on any host. `policy.dockerDesktopSwitch` is always `never`: switching stops every container on the engine that's switched away from.
+- Run `wsl --shutdown` or `wsl --terminate`. They stop the user's devcontainers.
+- Start, stop or reconfigure a daemon, or install software, without asking.
+- Touch containers or images you didn't create, on either engine.
+
+## Overrides
+
+Per host, in `.claude/host-container-capabilities.overrides.local.json` in the project, which should be gitignored. It's a flat JSON object. Any key can be left out.
+
+```json
+{
+  "linuxEngine": "wsl:Ubuntu",
+  "sharedHost": true,
+  "maxAgeHours": 24,
+  "createdByLabel": "io.github.kothar-hq.created-by=agent",
+  "sessionLabelKey": "io.github.kothar-hq.session",
+  "runnerContainerPattern": "my-runner-*"
+}
+```
+
+- `linuxEngine`: `auto` (the default), `none`, `wsl:<distro>` (Windows only), `docker` (the default docker context, if it's a Linux engine), or `docker-desktop-linux` (Windows only: Docker Desktop's Linux engine pipe, if it already exists; it's never switched to)
+- `sharedHost`: set `false` only on a host that nothing else uses
+- `maxAgeHours`: how long a report is reused
+- `createdByLabel`, `sessionLabelKey`: the labels from section 4, for a project that already has a labelling convention
+- `runnerContainerPattern`: a wildcard for CI runner containers on the Windows engine. `windowsEngine.runnerContainers` counts the matches, and is `null` when the pattern is empty.
+
+Editing the overrides file invalidates the cache. Reports are kept in `.claude/host-container-capabilities.<platform>.local.json`, one per platform, so a Windows session and a WSL session on the same checkout don't overwrite each other. Add `.claude/*.local.json` to the project's `.gitignore`.

package/skills/host-container-capabilities/scripts/Get-HostCapabilities.ps1

@@ -0,0 +1,304 @@
+<#
+.SYNOPSIS
+Reports which container engines this host can use (a Windows engine, a Linux engine, both or neither), and caches
+the answer for 24 hours.
+
+.DESCRIPTION
+The host-container-capabilities skill runs this before any container work, and routes each task to a local engine
+or to CI.
+
+On Windows it checks:
+- the Windows engine behind the default docker context: its version, default isolation, and the isolation each of
+  ltsc2019, ltsc2022 and ltsc2025 needs on this host build
+- a Linux engine, in this order: the default WSL distro's own Docker, any other WSL 2 distro's Docker (the
+  docker-desktop distros are skipped), the default docker context if it is a Linux engine, and Docker Desktop's
+  Linux engine pipe if it already exists. It stops at the first that answers. Probing a stopped WSL distro boots it.
+- gh, and whether it is logged in (the exit code only; nothing it prints is kept)
+
+It never switches Docker Desktop between Windows and Linux containers, never starts a daemon, and installs nothing.
+
+The project root is $env:HOST_CONTAINER_CAPABILITIES_ROOT if set, otherwise the git work tree that contains the
+current directory, otherwise the current directory.
+
+The report is cached in <root>/.claude/host-container-capabilities.windows.local.json, which should be gitignored.
+A cached report is reused until it is older than maxAgeHours, the overrides file is newer than it, or -Refresh is
+given. Overrides are read from <root>/.claude/host-container-capabilities.overrides.local.json, a flat JSON object:
+  linuxEngine             'auto' (default), 'none', 'wsl:<distro>', 'docker' (the default docker context) or
+                          'docker-desktop-linux'
+  sharedHost              true (default). Set false only on a host that nothing else uses.
+  maxAgeHours             24 (default)
+  createdByLabel          the key=value label the agent puts on everything it creates
+                          (default 'io.github.kothar-hq.created-by=agent')
+  sessionLabelKey         the label key that carries the session tag (default 'io.github.kothar-hq.session')
+  runnerContainerPattern  a wildcard for the names of CI runner containers on the Windows engine, which are counted
+                          in windowsEngine.runnerContainers (default '', not counted)
+
+On Linux and macOS it runs host-capabilities.sh (in the same directory) instead, which writes the same report.
+
+.PARAMETER Refresh
+Probe again even if the cached report is still fresh, for example after a docker command failed to reach its engine.
+
+.PARAMETER AsJson
+Print the report as JSON text instead of returning an object.
+
+.EXAMPLE
+./Get-HostCapabilities.ps1 -AsJson
+
+.EXAMPLE
+(./Get-HostCapabilities.ps1 -Refresh).linuxEngine.invoke
+#>
+#Requires -Version 7.0
+[CmdletBinding()]
+param(
+    [switch]$Refresh,
+    [switch]$AsJson
+)
+$ErrorActionPreference = 'Stop'
+
+if (-not $IsWindows) {
+    $shArgs = @("$PSScriptRoot/host-capabilities.sh")
+    if ($Refresh) { $shArgs += '--refresh' }
+    $json = (& sh @shArgs) -join "`n"
+    if ($LASTEXITCODE) { throw "host-capabilities.sh failed with exit code $LASTEXITCODE" }
+    if ($AsJson) { $json } else { $json | ConvertFrom-Json }
+    return
+}
+
+# The project root: the environment variable, else the git work tree around the current directory, else the
+# current directory.
+function Resolve-ProjectRoot {
+    if ($env:HOST_CONTAINER_CAPABILITIES_ROOT) {
+        return (Resolve-Path -LiteralPath $env:HOST_CONTAINER_CAPABILITIES_ROOT).Path
+    }
+    try {
+        $top = & git rev-parse --show-toplevel 2>$null
+        if ($LASTEXITCODE -eq 0 -and $top) { return (Resolve-Path -LiteralPath $top).Path }
+    } catch {
+        Write-Verbose "git is not available: $_"
+    }
+    (Get-Location).Path
+}
+
+$schemaVersion = 1
+$projectRoot = Resolve-ProjectRoot
+$cachePath = Join-Path $projectRoot '.claude/host-container-capabilities.windows.local.json'
+$overridesPath = Join-Path $projectRoot '.claude/host-container-capabilities.overrides.local.json'
+
+$overrides = [ordered]@{
+    linuxEngine            = 'auto'
+    sharedHost             = $true
+    maxAgeHours            = 24
+    createdByLabel         = 'io.github.kothar-hq.created-by=agent'
+    sessionLabelKey        = 'io.github.kothar-hq.session'
+    runnerContainerPattern = ''
+}
+if (Test-Path $overridesPath) {
+    $userOverrides = Get-Content -Raw $overridesPath | ConvertFrom-Json -AsHashtable
+    foreach ($key in @($userOverrides.Keys)) {
+        if ($overrides.Contains($key)) { $overrides[$key] = $userOverrides[$key] } else { Write-Warning "Ignoring unknown override '$key'" }
+    }
+    if ($overrides.linuxEngine -notmatch '^(auto|none|docker|docker-desktop-linux|wsl:.+)$') {
+        throw "Override linuxEngine '$($overrides.linuxEngine)' must be auto, none, docker, docker-desktop-linux or wsl:<distro>"
+    }
+    if ($overrides.createdByLabel -notmatch '^[^=\s]+=\S+$') {
+        throw "Override createdByLabel '$($overrides.createdByLabel)' must be key=value, without spaces"
+    }
+    if ($overrides.sessionLabelKey -notmatch '^[^=\s]+$') {
+        throw "Override sessionLabelKey '$($overrides.sessionLabelKey)' must be a label key, without spaces or '='"
+    }
+}
+
+if (-not $Refresh -and (Test-Path $cachePath)) {
+    $cachedJson = Get-Content -Raw $cachePath
+    $cached = $cachedJson | ConvertFrom-Json
+    $ageHours = ([DateTimeOffset]::UtcNow.ToUnixTimeSeconds() - $cached.probedAtEpoch) / 3600
+    $overridesChanged = (Test-Path $overridesPath) -and
+        (Get-Item $overridesPath).LastWriteTimeUtc -gt (Get-Item $cachePath).LastWriteTimeUtc
+    if ($cached.schemaVersion -eq $schemaVersion -and $ageHours -lt $overrides.maxAgeHours -and -not $overridesChanged) {
+        if ($AsJson) { $cachedJson.TrimEnd() } else { $cached }
+        return
+    }
+}
+
+# Runs a native command and returns its exit code and output. A missing command is exit code -1.
+function Invoke-Native {
+    param([Parameter(Mandatory)][string[]]$Command)
+    $ErrorActionPreference = 'Continue'
+    try {
+        $output = & $Command[0] @($Command | Select-Object -Skip 1) 2>&1
+        [pscustomobject]@{ ExitCode = $LASTEXITCODE; Output = (@($output | ForEach-Object { "$_" }) -join "`n").Trim() }
+    } catch {
+        [pscustomobject]@{ ExitCode = -1; Output = "$_" }
+    }
+}
+
+# Asks a docker CLI (an array such as 'wsl.exe','-d','Ubuntu','--exec','docker') about its engine. Returns $null
+# and sets $script:probeError when the engine doesn't answer.
+function Get-EngineFact {
+    param([Parameter(Mandatory)][string[]]$Docker)
+    $version = Invoke-Native ($Docker + @('version', '--format', '{{.Server.Os}}|{{.Server.Version}}'))
+    if ($version.ExitCode -ne 0 -or $version.Output -notmatch '^(\w+)\|(\S+)$') {
+        $script:probeError = ($version.Output -split "`n" | Where-Object { $_ } | Select-Object -First 1) ?? 'no output'
+        return $null
+    }
+    $os, $serverVersion = $Matches[1], $Matches[2]
+    $info = Invoke-Native ($Docker + @('info', '--format', '{{.OperatingSystem}}|{{.Isolation}}'))
+    $operatingSystem, $isolation = if ($info.ExitCode -eq 0) { $info.Output -split '\|', 2 } else { $null, $null }
+    $endpoint = Invoke-Native ($Docker + @('context', 'inspect', '--format', '{{.Endpoints.docker.Host}}'))
+    $names = Invoke-Native ($Docker + @('ps', '-a', '--format', '{{.Names}}'))
+    $mine = Invoke-Native ($Docker + @('ps', '-aq', '--filter', "label=$($overrides.createdByLabel)"))
+    [pscustomobject]@{
+        Os              = $os
+        ServerVersion   = $serverVersion
+        OperatingSystem = $operatingSystem
+        Isolation       = if ($isolation) { $isolation } else { $null }
+        Endpoint        = if ($endpoint.ExitCode -eq 0) { $endpoint.Output } else { $null }
+        Names           = @($names.Output -split "`n" | Where-Object { $_ })
+        ClaudeCount     = @($mine.Output -split "`n" | Where-Object { $_ }).Count
+    }
+}
+
+# Host
+$os = Get-CimInstance Win32_OperatingSystem
+$hostBuild = [Environment]::OSVersion.Version.Build
+$hypervisorPresent = [bool](Get-CimInstance Win32_ComputerSystem).HypervisorPresent
+$dockerDesktopInstalled = Test-Path (Join-Path $env:ProgramFiles 'Docker/Docker/Docker Desktop.exe')
+$dockerDesktopLinuxPipe = Test-Path '\\.\pipe\dockerDesktopLinuxEngine'
+
+# The default docker context: usually the Windows engine, or a Linux engine if Docker Desktop is in Linux mode
+$defaultEngine = Get-EngineFact @('docker')
+$defaultError = $script:probeError
+
+# Windows engine. Process isolation needs the image's build to match the host's; anything else needs Hyper-V.
+# Microsoft documents a few more cross-build process-isolation pairs, which this ignores.
+$windowsEngine = [ordered]@{
+    available = $false; invoke = $null; endpoint = $null; serverVersion = $null; defaultIsolation = $null
+    ltsc = $null; runnerContainers = $null; reason = $null
+}
+if ($defaultEngine -and $defaultEngine.Os -eq 'windows') {
+    $ltsc = [ordered]@{}
+    foreach ($entry in @(@('2019', 17763), @('2022', 20348), @('2025', 26100))) {
+        $isolation = if ($hostBuild -eq $entry[1]) { 'process' } elseif ($hypervisorPresent) { 'hyperv' } else { $null }
+        $ltsc[$entry[0]] = [ordered]@{ imageBuild = $entry[1]; isolation = $isolation }
+    }
+    $windowsEngine.available = $true
+    $windowsEngine.invoke = @('docker')
+    $windowsEngine.endpoint = $defaultEngine.Endpoint
+    $windowsEngine.serverVersion = $defaultEngine.ServerVersion
+    $windowsEngine.defaultIsolation = $defaultEngine.Isolation
+    $windowsEngine.ltsc = $ltsc
+    if ($overrides.runnerContainerPattern) {
+        $windowsEngine.runnerContainers = @($defaultEngine.Names | Where-Object { $_ -like $overrides.runnerContainerPattern }).Count
+    }
+} elseif ($defaultEngine) {
+    $windowsEngine.reason = "the default docker context is a $($defaultEngine.Os) engine; Docker Desktop is never switched"
+} else {
+    $windowsEngine.reason = "docker: $defaultError"
+}
+
+# WSL distros. WSL_UTF8 makes wsl.exe print UTF-8 instead of UTF-16.
+$previousWslUtf8 = $env:WSL_UTF8
+$env:WSL_UTF8 = '1'
+try {
+    $wslList = Invoke-Native @('wsl.exe', '--list', '--verbose')
+    $distros = @()
+    if ($wslList.ExitCode -eq 0) {
+        foreach ($line in $wslList.Output -split "`n") {
+            if ($line -match '^\s*(\*)?\s*(\S+)\s+(\S+)\s+([12])\s*$' -and $Matches[2] -ne 'NAME') {
+                $distros += [pscustomobject][ordered]@{
+                    name = $Matches[2]; state = $Matches[3]; version = [int]$Matches[4]; default = [bool]$Matches[1]
+                }
+            }
+        }
+    }
+    $wsl = [ordered]@{
+        installed     = $wslList.ExitCode -eq 0
+        defaultDistro = ($distros | Where-Object default | Select-Object -First 1).name
+        distros       = $distros
+    }
+
+    # Linux engine candidates, in the order the skill prefers them
+    $candidates = @()
+    $wslCandidates = @($distros | Where-Object { $_.version -eq 2 -and $_.name -notlike 'docker-desktop*' } |
+        Sort-Object { -not $_.default })
+    switch -Regex ($overrides.linuxEngine) {
+        '^auto$' {
+            $candidates += $wslCandidates | ForEach-Object { [pscustomobject]@{ Kind = 'wsl'; Distro = $_.name } }
+            $candidates += [pscustomobject]@{ Kind = 'docker'; Distro = $null }
+            if ($dockerDesktopLinuxPipe) { $candidates += [pscustomobject]@{ Kind = 'docker-desktop-linux'; Distro = $null } }
+        }
+        '^wsl:(.+)$' { $candidates += [pscustomobject]@{ Kind = 'wsl'; Distro = $Matches[1] } }
+        '^(docker|docker-desktop-linux)$' { $candidates += [pscustomobject]@{ Kind = $Matches[1]; Distro = $null } }
+    }
+
+    $linuxEngine = [ordered]@{
+        available = $false; kind = $null; distro = $null; invoke = $null; endpoint = $null; serverVersion = $null
+        operatingSystem = $null; containers = $null; claudeContainers = $null; repoPath = $null; reason = $null; tried = @()
+    }
+    foreach ($candidate in $candidates) {
+        $docker = switch ($candidate.Kind) {
+            'wsl' { @('wsl.exe', '--distribution', $candidate.Distro, '--exec', 'docker') }
+            'docker' { @('docker') }
+            'docker-desktop-linux' { @('docker', '--host', 'npipe:////./pipe/dockerDesktopLinuxEngine') }
+        }
+        $fact = if ($candidate.Kind -eq 'docker') { $defaultEngine } else { Get-EngineFact $docker }
+        $failure = if (-not $fact) { if ($candidate.Kind -eq 'docker') { $defaultError } else { $script:probeError } }
+            elseif ($fact.Os -ne 'linux') { "it is a $($fact.Os) engine" }
+        if ($failure) {
+            $linuxEngine.tried += [ordered]@{ kind = $candidate.Kind; distro = $candidate.Distro; error = $failure }
+            continue
+        }
+        $repoPath = if ($candidate.Kind -eq 'wsl') {
+            (Invoke-Native @('wsl.exe', '--distribution', $candidate.Distro, '--exec', 'wslpath', '-a', $projectRoot)).Output
+        } else { $null }
+        $linuxEngine.available = $true
+        $linuxEngine.kind = $candidate.Kind
+        $linuxEngine.distro = $candidate.Distro
+        $linuxEngine.invoke = $docker
+        $linuxEngine.endpoint = $fact.Endpoint
+        $linuxEngine.serverVersion = $fact.ServerVersion
+        $linuxEngine.operatingSystem = $fact.OperatingSystem
+        $linuxEngine.containers = $fact.Names.Count
+        $linuxEngine.claudeContainers = $fact.ClaudeCount
+        $linuxEngine.repoPath = $repoPath
+        break
+    }
+    if (-not $linuxEngine.available) {
+        $linuxEngine.reason = if ($overrides.linuxEngine -eq 'none') { 'disabled by the linuxEngine override' }
+            elseif (-not $wsl.installed) { 'WSL is not installed and no other Linux engine answered' }
+            else { 'no candidate answered; see tried' }
+    }
+} finally {
+    $env:WSL_UTF8 = $previousWslUtf8
+}
+
+$gh = [bool](Get-Command gh -ErrorAction SilentlyContinue)
+$report = [ordered]@{
+    schemaVersion = $schemaVersion
+    probedAt      = [DateTimeOffset]::UtcNow.ToString("yyyy-MM-dd'T'HH:mm:ss'Z'")
+    probedAtEpoch = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
+    platform      = 'windows'
+    overrides     = $overrides
+    policy        = [ordered]@{
+        sharedHost          = [bool]$overrides.sharedHost
+        dockerDesktopSwitch = 'never'
+        createdByLabel      = $overrides.createdByLabel
+        sessionLabelKey     = $overrides.sessionLabelKey
+    }
+    host          = [ordered]@{
+        os                = 'windows'
+        caption           = $os.Caption
+        build             = $hostBuild
+        productType       = if ($os.ProductType -eq 1) { 'workstation' } else { 'server' }
+        hypervisorPresent = $hypervisorPresent
+        dockerDesktop     = [ordered]@{ installed = $dockerDesktopInstalled; linuxEnginePipe = $dockerDesktopLinuxPipe }
+    }
+    windowsEngine = $windowsEngine
+    linuxEngine   = $linuxEngine
+    wsl           = $wsl
+    github        = [ordered]@{ gh = $gh; authenticated = $gh -and (Invoke-Native @('gh', 'auth', 'status')).ExitCode -eq 0 }
+}
+$json = $report | ConvertTo-Json -Depth 8
+New-Item -ItemType Directory -Force -Path (Split-Path -Parent $cachePath) | Out-Null
+Set-Content -Path $cachePath -Value $json -Encoding utf8NoBOM
+if ($AsJson) { $json } else { $json | ConvertFrom-Json }

package/skills/host-container-capabilities/scripts/host-capabilities.sh

@@ -0,0 +1,208 @@
+#!/bin/sh
+# host-capabilities.sh: report, as JSON, which container engines this host can use, and cache the answer
+# (the host-container-capabilities skill).
+#
+#   host-capabilities.sh            print the cached report, probing first if it is missing or stale
+#   host-capabilities.sh --refresh  probe again
+#
+# For Linux, macOS and WSL. On Windows (Git Bash, MSYS, Cygwin) it runs Get-HostCapabilities.ps1 instead.
+# The project root is $HOST_CONTAINER_CAPABILITIES_ROOT, else the git work tree around the current directory,
+# else the current directory. The report is cached in <root>/.claude/host-container-capabilities.<platform>.local.json.
+# Overrides are read from <root>/.claude/host-container-capabilities.overrides.local.json, a flat JSON object with
+# linuxEngine (auto, none or docker), sharedHost (true), maxAgeHours (24), createdByLabel, sessionLabelKey and
+# runnerContainerPattern. It never starts a daemon and installs nothing.
+set -eu
+
+here=$(cd "$(dirname "$0")" && pwd)
+refresh=0
+case "${1:-}" in
+    --refresh) refresh=1 ;;
+    '') ;;
+    -h | --help) sed -n '2,13p' "$0"; exit 0 ;;
+    *) echo "host-capabilities.sh: unknown argument '$1'" >&2; exit 2 ;;
+esac
+
+case "$(uname -s)" in
+    MINGW* | MSYS* | CYGWIN*)
+        if [ "$refresh" = 1 ]; then
+            exec pwsh -NoProfile -File "$here/Get-HostCapabilities.ps1" -AsJson -Refresh
+        fi
+        exec pwsh -NoProfile -File "$here/Get-HostCapabilities.ps1" -AsJson
+        ;;
+    Darwin) platform=macos ;;
+    *) if grep -qi microsoft /proc/sys/kernel/osrelease 2>/dev/null; then platform=wsl; else platform=linux; fi ;;
+esac
+
+if [ -n "${HOST_CONTAINER_CAPABILITIES_ROOT:-}" ]; then
+    root=$(cd "$HOST_CONTAINER_CAPABILITIES_ROOT" && pwd)
+elif root=$(git rev-parse --show-toplevel 2>/dev/null) && [ -n "$root" ]; then
+    :
+else
+    root=$(pwd)
+fi
+
+schema=1
+cache="$root/.claude/host-container-capabilities.$platform.local.json"
+overrides="$root/.claude/host-container-capabilities.overrides.local.json"
+
+# json_value <file> <key>: a top-level string, number or boolean from a flat JSON file (empty if absent)
+json_value() {
+    [ -f "$1" ] || return 0
+    tr -d '\n\r' <"$1" | sed -n "s/.*\"$2\"[[:space:]]*:[[:space:]]*\"\{0,1\}\([^\",}[:space:]]*\).*/\1/p"
+}
+# js <value>: a JSON string, or null when empty
+js() {
+    if [ -z "$1" ]; then printf null; return; fi
+    printf '"%s"' "$(printf '%s' "$1" | tr -d '\n\r\t' | sed 's/\\/\\\\/g; s/"/\\"/g')"
+}
+# jn <value>: a JSON number, or null when empty
+jn() { if [ -z "$1" ]; then printf null; else printf '%s' "$1"; fi; }
+
+ov_engine=$(json_value "$overrides" linuxEngine)
+ov_shared=$(json_value "$overrides" sharedHost)
+ov_age=$(json_value "$overrides" maxAgeHours)
+ov_label=$(json_value "$overrides" createdByLabel)
+ov_session=$(json_value "$overrides" sessionLabelKey)
+ov_runners=$(json_value "$overrides" runnerContainerPattern)
+: "${ov_engine:=auto}" "${ov_shared:=true}" "${ov_age:=24}"
+: "${ov_label:=io.github.kothar-hq.created-by=agent}" "${ov_session:=io.github.kothar-hq.session}"
+case "$ov_engine" in auto | none | docker) ;; *)
+    echo "host-capabilities.sh: override linuxEngine '$ov_engine' must be auto, none or docker here" >&2; exit 2 ;;
+esac
+case "$ov_shared" in true | false) ;; *) echo "host-capabilities.sh: override sharedHost must be true or false" >&2; exit 2 ;; esac
+case "$ov_age" in '' | *[!0-9]*) echo "host-capabilities.sh: override maxAgeHours must be a whole number" >&2; exit 2 ;; esac
+case "$ov_label" in ?*=?*) ;; *) echo "host-capabilities.sh: override createdByLabel must be key=value" >&2; exit 2 ;; esac
+case "$ov_session" in *=*) echo "host-capabilities.sh: override sessionLabelKey must be a label key, without '='" >&2; exit 2 ;; esac
+
+now=$(date +%s)
+if [ "$refresh" = 0 ] && [ -f "$cache" ] && [ -z "$(find "$overrides" -newer "$cache" 2>/dev/null)" ]; then
+    cached_schema=$(json_value "$cache" schemaVersion)
+    cached_epoch=$(json_value "$cache" probedAtEpoch)
+    if [ "$cached_schema" = "$schema" ] && [ -n "$cached_epoch" ] && [ $((now - cached_epoch)) -lt $((ov_age * 3600)) ]; then
+        cat "$cache"
+        exit 0
+    fi
+fi
+
+# probe <docker command...>: asks a docker CLI about its engine. Sets p_os, p_version, p_osname, p_isolation,
+# p_endpoint, p_total and p_mine, or p_error when the engine doesn't answer.
+probe() {
+    p_os='' p_version='' p_osname='' p_isolation='' p_endpoint='' p_total='' p_mine='' p_error=''
+    if ! out=$("$@" version --format '{{.Server.Os}}|{{.Server.Version}}' 2>&1) || [ "${out#*|}" = "$out" ]; then
+        p_error=$(printf '%s\n' "$out" | sed -n '/./{p;q;}')
+        : "${p_error:=no output}"
+        return 1
+    fi
+    p_os=${out%%|*} p_version=${out#*|}
+    info=$("$@" info --format '{{.OperatingSystem}}|{{.Isolation}}' 2>/dev/null || true)
+    p_osname=${info%%|*} p_isolation=${info#*|}
+    p_endpoint=$("$@" context inspect --format '{{.Endpoints.docker.Host}}' 2>/dev/null || true)
+    p_total=$("$@" ps -aq 2>/dev/null | wc -l | tr -d ' ')
+    p_mine=$("$@" ps -aq --filter "label=$ov_label" 2>/dev/null | wc -l | tr -d ' ')
+}
+
+# Linux engine: the docker CLI's current context (DOCKER_HOST, Docker Desktop, colima, a distro's own Docker)
+l_available=false l_kind='' l_invoke=null l_version='' l_osname='' l_endpoint='' l_total='' l_mine='' l_reason='' l_tried=''
+if [ "$ov_engine" = none ]; then
+    l_reason='disabled by the linuxEngine override'
+elif ! command -v docker >/dev/null 2>&1; then
+    l_reason='docker CLI not installed'
+    l_tried="{\"kind\": \"docker\", \"distro\": null, \"error\": $(js "$l_reason")}"
+elif probe docker && [ "$p_os" = linux ]; then
+    l_available=true l_kind=docker l_invoke='["docker"]' l_version=$p_version l_osname=$p_osname
+    l_endpoint=$p_endpoint l_total=$p_total l_mine=$p_mine
+else
+    if [ -n "$p_os" ]; then p_error="it is a $p_os engine"; fi
+    l_reason='no candidate answered; see tried'
+    l_tried="{\"kind\": \"docker\", \"distro\": null, \"error\": $(js "$p_error")}"
+fi
+
+# Windows engine: only reachable from WSL, through Windows' docker.exe
+w_available=false w_invoke=null w_endpoint='' w_version='' w_isolation='' w_runners='' w_reason=''
+if [ "$platform" != wsl ]; then
+    w_reason="a $platform host has no Windows engine"
+elif ! command -v docker.exe >/dev/null 2>&1; then
+    w_reason='docker.exe is not on the PATH (WSL interop off, or no Windows Docker)'
+elif probe docker.exe && [ "$p_os" = windows ]; then
+    w_available=true w_invoke='["docker.exe"]' w_endpoint=$p_endpoint w_version=$p_version w_isolation=$p_isolation
+    if [ -n "$ov_runners" ]; then
+        w_runners=0
+        for name in $(docker.exe ps -a --format '{{.Names}}' 2>/dev/null | tr -d '\r'); do
+            # shellcheck disable=SC2254 # the override is a wildcard pattern
+            case "$name" in $ov_runners) w_runners=$((w_runners + 1)) ;; esac
+        done
+    fi
+    w_reason='per-LTSC isolation is only worked out on Windows: run Get-HostCapabilities.ps1 with pwsh.exe'
+else
+    if [ -n "$p_os" ]; then p_error="docker.exe reaches a $p_os engine"; fi
+    w_reason="docker.exe: $p_error"
+fi
+
+gh=false gh_auth=false
+if command -v gh >/dev/null 2>&1; then
+    gh=true
+    if gh auth status >/dev/null 2>&1; then gh_auth=true; fi
+fi
+if [ "$platform" = macos ]; then os=macos; else os=linux; fi
+
+mkdir -p "$(dirname "$cache")"
+cat >"$cache" <<EOF
+{
+  "schemaVersion": $schema,
+  "probedAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "probedAtEpoch": $now,
+  "platform": "$platform",
+  "overrides": {
+    "linuxEngine": $(js "$ov_engine"),
+    "sharedHost": $ov_shared,
+    "maxAgeHours": $ov_age,
+    "createdByLabel": $(js "$ov_label"),
+    "sessionLabelKey": $(js "$ov_session"),
+    "runnerContainerPattern": "$(printf '%s' "$ov_runners" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+  },
+  "policy": {
+    "sharedHost": $ov_shared,
+    "dockerDesktopSwitch": "never",
+    "createdByLabel": $(js "$ov_label"),
+    "sessionLabelKey": $(js "$ov_session")
+  },
+  "host": {
+    "os": "$os",
+    "caption": $(js "$(uname -sr)"),
+    "build": null,
+    "productType": null,
+    "hypervisorPresent": null,
+    "dockerDesktop": null
+  },
+  "windowsEngine": {
+    "available": $w_available,
+    "invoke": $w_invoke,
+    "endpoint": $(js "$w_endpoint"),
+    "serverVersion": $(js "$w_version"),
+    "defaultIsolation": $(js "$w_isolation"),
+    "ltsc": null,
+    "runnerContainers": $(jn "$w_runners"),
+    "reason": $(js "$w_reason")
+  },
+  "linuxEngine": {
+    "available": $l_available,
+    "kind": $(js "$l_kind"),
+    "distro": $(js "$(if [ "$platform" = wsl ]; then printf '%s' "${WSL_DISTRO_NAME:-}"; fi)"),
+    "invoke": $l_invoke,
+    "endpoint": $(js "$l_endpoint"),
+    "serverVersion": $(js "$l_version"),
+    "operatingSystem": $(js "$l_osname"),
+    "containers": $(jn "$l_total"),
+    "claudeContainers": $(jn "$l_mine"),
+    "repoPath": $(js "$root"),
+    "reason": $(js "$l_reason"),
+    "tried": [$l_tried]
+  },
+  "wsl": null,
+  "github": {
+    "gh": $gh,
+    "authenticated": $gh_auth
+  }
+}
+EOF
+cat "$cache"