From c0b87d630ef2d2ef6c4cc0595a0397be8e5b8362 Mon Sep 17 00:00:00 2001
From: Mike Landau <mikeland86@gmail.com>
Date: Wed, 22 Apr 2026 12:20:51 -0700
Subject: [PATCH] Add agent skill for devbox

Packages devbox usage guidance as a SKILL.md so AI coding agents
(Claude Code, Cursor, Copilot, etc.) have structured, production-ready
reference material for authoring devbox.json, managing Nix packages,
writing scripts/services, and generating Dockerfiles or devcontainers.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 skills/devbox/SKILL.md                        | 126 ++++++++++++++++
 skills/devbox/references/devbox-json.md       | 134 ++++++++++++++++++
 .../devbox/references/global-and-templates.md |  91 ++++++++++++
 skills/devbox/references/packages.md          |  94 ++++++++++++
 skills/devbox/references/scripts-services.md  | 107 ++++++++++++++
 5 files changed, 552 insertions(+)
 create mode 100644 skills/devbox/SKILL.md
 create mode 100644 skills/devbox/references/devbox-json.md
 create mode 100644 skills/devbox/references/global-and-templates.md
 create mode 100644 skills/devbox/references/packages.md
 create mode 100644 skills/devbox/references/scripts-services.md

diff --git a/skills/devbox/SKILL.md b/skills/devbox/SKILL.md
new file mode 100644
index 00000000000..41ed9a4e41a
--- /dev/null
+++ b/skills/devbox/SKILL.md
@@ -0,0 +1,126 @@
+---
+name: devbox
+description: Devbox expert guidance. Use when creating isolated development environments, managing project dependencies with Nix packages, authoring devbox.json, writing scripts or services, or generating Dockerfiles and devcontainers from a devbox project.
+metadata:
+  docs:
+    - "https://www.jetify.com/devbox/docs"
+    - "https://github.com/jetify-com/devbox"
+  pathPatterns:
+    - 'devbox.json'
+    - 'devbox.lock'
+    - '.devbox/**'
+  bashPatterns:
+    - '^\s*devbox(?:\s|$)'
+---
+
+# Devbox Skill
+
+[Devbox](https://github.com/jetify-com/devbox) creates isolated, reproducible development environments powered by Nix. You declare packages and scripts in a `devbox.json`; Devbox materializes a shell where everyone on the team gets the exact same tool versions without polluting the host machine. Use `devbox <command> -h` for full flag details on any command.
+
+## Quick Start
+
+```bash
+curl -fsSL https://get.jetify.com/devbox | bash   # install devbox
+devbox init                                        # create devbox.json in cwd
+devbox add go@1.22 nodejs@20                       # add packages (name@version)
+devbox shell                                       # enter the isolated shell
+devbox run <script>                                # run a script from devbox.json
+```
+
+Packages resolve against the Nix package registry. Browse versions at [nixhub.io](https://www.nixhub.io).
+
+## The `devbox.json` File
+
+The project's source of truth. Minimum viable file:
+
+```json
+{
+  "packages": ["go@1.22", "nodejs@20"],
+  "shell": {
+    "init_hook": ["echo 'Welcome'"],
+    "scripts": {
+      "test": "go test ./...",
+      "build": ["go build ./...", "echo done"]
+    }
+  },
+  "env": {
+    "GOENV": "off",
+    "PATH": "$PWD/bin:$PATH"
+  }
+}
+```
+
+- `packages`: array of `name@version` strings, or an object with per-package `platforms` / `excluded_platforms` / `outputs` / `patch` settings.
+- `shell.init_hook`: commands run every time the environment starts (both `devbox shell` and `devbox run`). Keep it fast — it runs often.
+- `shell.scripts`: named commands invoked with `devbox run <name>`. A value can be a string or an array of strings executed in order.
+- `env`: extra env vars. Only `$PATH` and `$PWD` are expanded; no other variable expansion or command substitution.
+- `include`: plugin references (e.g. `"plugin:nginx"`, `"path:./mydir"`, `"github:owner/repo"`).
+
+See `references/devbox-json.md` for the full schema.
+
+## Decision Tree
+
+Use this to route to the correct sub-topic:
+
+- **Add or remove a package** → `devbox add <pkg>@<ver>` / `devbox rm <pkg>`. See `references/packages.md`.
+- **Enter an isolated shell** → `devbox shell`. Add `--pure` for a shell that inherits almost nothing from the host.
+- **Run a task** → `devbox run <script>`. Pass arguments after `--` (e.g. `devbox run -- cowsay -d hi`). See `references/scripts-services.md`.
+- **Install all packages in CI** → `devbox install` (no shell). Pair with `actions/cache` keyed on `devbox.lock`.
+- **Update packages** → `devbox update` (all) or `devbox update <pkg>` (one). Use `--no-install` to update the lockfile only.
+- **Find a package** → `devbox search <pkg>`.
+- **Inspect installed packages** → `devbox list` / `devbox info <pkg>`.
+- **Long-running services (dbs, workers)** → `devbox services start|stop|ls|attach`. See `references/scripts-services.md`.
+- **Global tools (available everywhere)** → `devbox global add|rm|list`. See `references/global-and-templates.md`.
+- **Bootstrap from a template** → `devbox create --template <name>` (use `--show-all` to list templates).
+- **Generate Dockerfile / devcontainer / direnv** → `devbox generate dockerfile|devcontainer|direnv|alias|readme`.
+- **Load env into the host shell** → `eval "$(devbox shellenv)"`, or `devbox generate direnv` for automatic loading.
+- **Secrets (Jetify Cloud)** → `devbox secrets init|set|list|download|upload`.
+- **Multiple envs (dev/prod/preview)** → `--environment <name>` flag.
+- **Multi-project repos** → `--all-projects` on `run` and `update`; `--sync-lock` on `update`.
+
+## Critical: Lockfile Hygiene
+
+`devbox.lock` pins exact Nix store paths for every package. **Always commit it.** Without it, teammates and CI will get different versions.
+
+- `devbox install --tidy-lockfile` repairs missing store paths.
+- `devbox update --sync-lock` reconciles lockfiles across multiple projects in one repo.
+- Do not hand-edit `devbox.lock`.
+
+## Integrating with the Host Shell
+
+`devbox shell` spawns a subshell, which is noisy for daily work. Two better options:
+
+1. **direnv**: `devbox generate direnv` writes a `.envrc` so entering the directory auto-loads the environment. Requires `direnv` installed on the host.
+2. **shellenv**: `eval "$(devbox shellenv)"` inline-loads the environment into the current shell. Useful in CI or one-off scripts.
+
+## CI/CD
+
+Typical GitHub Actions pattern:
+
+```yaml
+- uses: jetify-com/devbox-install-action@v0.13.0
+  with:
+    enable-cache: 'true'
+- run: devbox run test
+```
+
+Without the action, use `devbox install` + cache `~/.nix-*` and `.devbox/` keyed on `devbox.lock`. Avoid `devbox shell` in CI — use `devbox run <cmd>` (non-interactive) or `eval "$(devbox shellenv)"` instead.
+
+## Anti-Patterns
+
+- **Running devbox without a lockfile committed.** Defeats reproducibility. Commit `devbox.lock` alongside `devbox.json`.
+- **Using unversioned packages in production configs** (e.g. `"go"` instead of `"go@1.22"`). The resolver will pick whatever `@latest` resolves to the day you first install it; `devbox update` is the only way to bump it. Pin versions.
+- **Shell substitution in `env` values.** Only `$PATH` / `$PWD` expand. Put dynamic logic in `init_hook` instead.
+- **Heavy work in `init_hook`.** It runs on *every* `devbox run`, not just shell entry. Keep it to env mutations; move builds to scripts.
+- **`devbox shell` inside scripts or CI.** Blocks on an interactive prompt. Use `devbox run` or `devbox shellenv` instead.
+- **Editing `devbox.lock` by hand.** Let `devbox update`, `devbox install --tidy-lockfile`, or `devbox add` regenerate it.
+- **Forgetting `--` before flags to the target command.** `devbox run cowsay -d hi` tries to parse `-d` as a devbox flag. Use `devbox run -- cowsay -d hi`.
+- **Mixing `devbox` and `devbox global`.** `global` manages a separate config at `devbox global path` — project installs never leak into it, and vice versa.
+
+## Common Recipes
+
+- **New Go project**: `devbox init && devbox add go@latest && devbox shell`
+- **Dockerize**: `devbox generate dockerfile` produces a `Dockerfile` that replicates the shell.
+- **Reproduce in a devcontainer**: `devbox generate devcontainer` writes `.devcontainer/` for VS Code.
+- **Share a global toolset**: `devbox global push` (to Jetify Cloud or a git repo); teammates run `devbox global pull`.
+- **Run Postgres for local dev**: `devbox add postgresql` then `devbox services up postgresql`.
diff --git a/skills/devbox/references/devbox-json.md b/skills/devbox/references/devbox-json.md
new file mode 100644
index 00000000000..1dfd249a2ac
--- /dev/null
+++ b/skills/devbox/references/devbox-json.md
@@ -0,0 +1,134 @@
+# `devbox.json` Reference
+
+Full schema is at `.schema/devbox.schema.json` in the devbox repo. This is the practical subset.
+
+## Top-level fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `$schema` | string | Schema version URL. Optional. |
+| `name` | string | Project name. Optional. |
+| `description` | string | Human-readable description. Optional. |
+| `packages` | array \| object | Packages to install. See below. |
+| `env` | object | Extra env vars. Only `$PATH` / `$PWD` expand. |
+| `shell.init_hook` | string \| array<string> | Runs on every shell/run entry. |
+| `shell.scripts` | object | Named commands; value is string or array<string>. |
+| `include` | array<string> | Plugin includes. See below. |
+| `env_from` | string | Inherit env from another devbox project path. |
+
+## `packages` — two forms
+
+**Array form** (simple, most common):
+
+```json
+"packages": ["go@1.22", "nodejs@20", "postgresql@15"]
+```
+
+**Object form** (per-package metadata):
+
+```json
+"packages": {
+  "go":         "1.22",
+  "postgresql": { "version": "15", "excluded_platforms": ["aarch64-darwin"] },
+  "ffmpeg":     { "version": "latest", "outputs": ["bin", "lib"], "patch": "always" }
+}
+```
+
+Per-package options:
+
+- `version`: semver or `latest`.
+- `platforms`: only install on these platforms (allowlist).
+- `excluded_platforms`: skip on these platforms (denylist). Cannot be combined with `platforms`.
+- `outputs`: Nix outputs to install (most packages need only the default). Useful for libraries.
+- `patch`: `auto` (default), `always`, or `never`. Controls glibc patching on Linux.
+- `glibc_patch`: boolean shorthand for forcing glibc patching.
+- `allow_insecure`: mark a CVE-flagged package as allowed. Pair with `devbox add --allow-insecure`.
+- `disable_plugin`: skip any built-in plugin registered for this package.
+
+Platform values: `i686-linux`, `aarch64-linux`, `aarch64-darwin`, `x86_64-darwin`, `x86_64-linux`, `armv7l-linux`.
+
+## `env` — environment variables
+
+```json
+"env": {
+  "GOENV":        "off",
+  "PATH":         "$PWD/bin:$PATH",
+  "DATABASE_URL": "postgres://localhost/dev"
+}
+```
+
+Only `$PATH` and `$PWD` are expanded. **No command substitution, no other variable expansion.** Put dynamic logic in `init_hook` instead.
+
+## `shell` — scripts and hooks
+
+```json
+"shell": {
+  "init_hook": [
+    "unset GOROOT GOTOOLCHAIN",
+    "export PROJECT_ROOT=$PWD"
+  ],
+  "scripts": {
+    "test":  "go test ./...",
+    "build": ["go mod tidy", "go build -o bin/app ./cmd/app"],
+    "dev":   "air"
+  }
+}
+```
+
+- `init_hook` runs on every `devbox shell` AND every `devbox run`. Keep it cheap.
+- Script values can be a single string or an array of strings executed sequentially, stopping on first non-zero exit.
+- Invoke with `devbox run <name>`. Arguments after `--` are passed to the final command.
+
+## `include` — plugins
+
+```json
+"include": [
+  "plugin:nginx",
+  "path:./plugins/my-plugin",
+  "github:jetify-com/devbox-plugins#path/to/plugin"
+]
+```
+
+- `plugin:<name>` — built-in plugin shipped with devbox (see `pkg` directory in the devbox repo).
+- `path:<dir>` — local plugin directory containing a `plugin.json`.
+- `github:owner/repo[#path]` — plugin from a GitHub repo.
+
+Plugins can contribute packages, env vars, services, and files. See `.schema/devbox-plugin.schema.json` for the plugin schema.
+
+## `env_from`
+
+```json
+"env_from": "../shared-env"
+```
+
+Inherits env and packages from another devbox project on disk. Useful for monorepos with a shared base environment.
+
+## Full example
+
+```json
+{
+  "$schema":     "https://raw.githubusercontent.com/jetify-com/devbox/0.17.2/.schema/devbox.schema.json",
+  "name":        "my-api",
+  "description": "Backend service",
+  "packages": [
+    "go@1.22",
+    "postgresql@15",
+    "redis@7"
+  ],
+  "env": {
+    "CGO_ENABLED": "0",
+    "PATH":        "$PWD/bin:$PATH"
+  },
+  "shell": {
+    "init_hook": [
+      "test -d bin || mkdir bin"
+    ],
+    "scripts": {
+      "build": "go build -o bin/api ./cmd/api",
+      "test":  "go test -race ./...",
+      "dev":   ["devbox services up -b", "air"]
+    }
+  },
+  "include": ["plugin:postgresql", "plugin:redis"]
+}
+```
diff --git a/skills/devbox/references/global-and-templates.md b/skills/devbox/references/global-and-templates.md
new file mode 100644
index 00000000000..cc0de5ce7f3
--- /dev/null
+++ b/skills/devbox/references/global-and-templates.md
@@ -0,0 +1,91 @@
+# Global Packages, Templates, and Generators
+
+## `devbox global` — machine-wide tools
+
+`devbox global` manages a separate config (kept at `$(devbox global path)`) that's always on your PATH, independent of any project. Mirror of the per-project commands:
+
+```bash
+devbox global add jq ripgrep fzf        # add tools
+devbox global list                      # show installed
+devbox global rm jq
+devbox global install                   # reinstall from config
+devbox global update                    # update all
+devbox global path                      # print config directory
+```
+
+To make it live in your shell, add one of:
+
+```bash
+eval "$(devbox global shellenv)"        # in ~/.zshrc or ~/.bashrc
+```
+
+### Sharing a global config
+
+```bash
+devbox global push                      # push to Jetify Cloud
+devbox global push git@github.com:me/dotfiles-devbox.git   # or your own git repo
+devbox global pull <url-or-file>        # pull on another machine
+```
+
+Useful for keeping the same CLI toolkit across laptops.
+
+**Global and project configs never mix.** A project's `devbox.json` doesn't see global packages unless you explicitly run `eval "$(devbox global shellenv)"` in your shell first.
+
+## `devbox create` — templates
+
+```bash
+devbox create --show-all                        # list templates
+devbox create my-proj --template go             # scaffold into ./my-proj
+devbox create . --template python               # scaffold into cwd
+```
+
+Templates are starter `devbox.json` + supporting files for common stacks (go, python, node, rust, etc.). Use when starting fresh.
+
+## `devbox generate` — supporting files
+
+```bash
+devbox generate readme          # regenerate the project README from devbox.json
+devbox generate dockerfile      # Dockerfile that replicates the shell
+devbox generate devcontainer    # .devcontainer/ for VS Code
+devbox generate direnv          # .envrc for direnv auto-loading
+devbox generate alias           # shell aliases for scripts
+```
+
+### `generate dockerfile`
+
+Produces a `Dockerfile` that installs Nix, runs `devbox install`, and sets the entrypoint. The resulting image reproduces the dev shell. Pair with `.dockerignore` to avoid shipping `.devbox/` build artifacts.
+
+### `generate devcontainer`
+
+Writes `.devcontainer/devcontainer.json` and `.devcontainer/Dockerfile`. VS Code's Remote-Containers will pick it up and build an identical environment inside Docker.
+
+### `generate direnv`
+
+Writes a `.envrc` at the project root that runs `use devbox`. After `direnv allow`, the devbox environment activates automatically when you `cd` into the directory and deactivates when you leave. The recommended daily-use setup.
+
+### `generate readme`
+
+Regenerates the auto-generated README section (the `<!-- gen-readme start -->` block) from the current `devbox.json` — scripts, packages, env, init hook. Run after changing `devbox.json` to keep docs fresh.
+
+## Secrets
+
+`devbox secrets` integrates with Jetify Cloud for encrypted secret storage per environment:
+
+```bash
+devbox secrets init                     # link project to a Jetify secrets store
+devbox secrets set API_KEY=sk-...       # store a secret
+devbox secrets list --environment prod  # list for an environment
+devbox secrets download .env.local      # materialize to a file
+devbox secrets upload .env              # bulk import from a .env file
+devbox secrets remove API_KEY
+```
+
+Environments (`dev` / `prod` / `preview`) scope secrets separately. Pass `--environment <name>` on `run`, `shell`, and `secrets` commands.
+
+## Auth
+
+```bash
+devbox auth login         # log in to Jetify Cloud (needed for secrets, global push)
+devbox auth logout
+devbox auth whoami
+```
diff --git a/skills/devbox/references/packages.md b/skills/devbox/references/packages.md
new file mode 100644
index 00000000000..ecf9b0a8d98
--- /dev/null
+++ b/skills/devbox/references/packages.md
@@ -0,0 +1,94 @@
+# Package Management
+
+## Finding a package
+
+```bash
+devbox search <name>          # searches the Nix registry
+devbox search nodejs
+devbox info nodejs@20         # details on a specific version
+```
+
+[nixhub.io](https://www.nixhub.io) is the web UI for the same registry — useful for browsing available versions.
+
+## Adding packages
+
+```bash
+devbox add go@1.22                          # pinned version
+devbox add nodejs@latest                    # track latest
+devbox add postgresql --platform=x86_64-linux,aarch64-linux   # allowlist
+devbox add ffmpeg --exclude-platform=aarch64-darwin            # denylist
+devbox add bun --outputs=bin,lib            # select Nix outputs
+devbox add openssl@1.1 --allow-insecure openssl-1.1.1w         # unblock CVE-flagged pkg
+devbox add go --disable-plugin              # skip built-in plugin
+```
+
+Always pin a version in committed configs. `@latest` is fine for one-offs and global tools but makes project builds non-reproducible until `devbox update` runs.
+
+## Removing packages
+
+```bash
+devbox rm <name>              # single package
+devbox rm go nodejs           # multiple
+```
+
+This updates `devbox.json` and `devbox.lock`. Re-run `devbox install` on other machines to remove the store paths.
+
+## Updating packages
+
+```bash
+devbox update                       # update all packages
+devbox update go                    # update one
+devbox update --no-install          # update lockfile only, skip download
+devbox update --all-projects        # recurse into every devbox project in cwd
+devbox update --sync-lock           # reconcile lockfiles across multiple projects
+```
+
+`devbox update` also migrates legacy non-versioned packages (e.g. `"go"`) to `@latest` form, resolving to the current version in the process.
+
+## Installing (materializing the lockfile)
+
+```bash
+devbox install                   # install everything in devbox.lock, no shell
+devbox install --tidy-lockfile   # repair missing store paths
+```
+
+Use `devbox install` in CI and Dockerfiles. It's the non-interactive equivalent of entering a shell.
+
+## Versioning semantics
+
+- `go@1.22` — pins to the highest `1.22.x` available.
+- `go@1.22.5` — pins exactly.
+- `go@latest` — tracks whatever is latest when `devbox update` runs.
+- Unversioned (`go`) — legacy form; still works but migrates to `@latest` on next update.
+
+Versions are resolved against Nixhub, which aggregates snapshots of nixpkgs over time, so older versions remain reachable long after they leave `nixpkgs-unstable`.
+
+## Platform-specific packages
+
+Two mutually exclusive keys control where a package installs:
+
+- `platforms`: allowlist.
+- `excluded_platforms`: denylist.
+
+```json
+"packages": {
+  "podman":      { "version": "latest", "platforms": ["x86_64-linux", "aarch64-linux"] },
+  "docker-mac":  { "version": "latest", "platforms": ["aarch64-darwin", "x86_64-darwin"] }
+}
+```
+
+Useful when different OSes need different tools to achieve the same capability.
+
+## `runx` packages
+
+Devbox supports `runx:<github-owner>/<repo>[@version]` to pull prebuilt release binaries from GitHub releases. Useful for tools not in nixpkgs (e.g. `runx:golangci/golangci-lint@latest`). They install on demand and run without a full Nix build.
+
+## Insecure packages
+
+If Nix marks a package as insecure (e.g. an old OpenSSL), add it with:
+
+```bash
+devbox add openssl@1.1 --allow-insecure openssl-1.1.1w
+```
+
+The allowlist goes into `devbox.json` as `allow_insecure`. Pin the exact attribute name shown in the error message.
diff --git a/skills/devbox/references/scripts-services.md b/skills/devbox/references/scripts-services.md
new file mode 100644
index 00000000000..864ddb0d4e1
--- /dev/null
+++ b/skills/devbox/references/scripts-services.md
@@ -0,0 +1,107 @@
+# Scripts, Services, and Shell Hooks
+
+## Scripts via `devbox run`
+
+Scripts live under `shell.scripts` in `devbox.json`:
+
+```json
+"shell": {
+  "scripts": {
+    "test":  "go test ./...",
+    "build": ["go mod tidy", "go build -o bin/app ./cmd/app"],
+    "dev":   "air"
+  }
+}
+```
+
+Run them with:
+
+```bash
+devbox run test
+devbox run -- build --verbose     # args after -- are forwarded
+devbox run --list                 # list scripts
+devbox run --all-projects test    # recurse
+devbox run --pure test            # isolated env (drops host vars)
+devbox run --env KEY=val test     # ad-hoc env vars
+devbox run --env-file ./.env test
+```
+
+If the name isn't in `scripts`, `devbox run` interprets it as an arbitrary command in the devbox environment.
+
+### Gotchas
+
+- **Pass flags to the underlying command with `--`.** Otherwise devbox parses them itself.
+- **Arrays stop on first failure** (non-zero exit) — same as `set -e`. If you need to continue past failures, combine with `||` inside the string.
+- **`init_hook` runs before every script** — including inside CI. Keep it lightweight.
+
+## Services
+
+`devbox services` orchestrates long-running processes (databases, workers) via [process-compose](https://github.com/F1bonacc1/process-compose).
+
+```bash
+devbox services ls                 # list services
+devbox services start postgresql   # start one
+devbox services start              # start all
+devbox services up                 # start with process-compose UI
+devbox services up -b              # background
+devbox services restart redis
+devbox services stop               # stop all
+devbox services attach             # attach to the running process-compose
+devbox services pcport             # print process-compose port
+```
+
+Services come from two sources:
+
+1. **Plugins** — e.g. `"include": ["plugin:postgresql"]` registers a `postgresql` service with sensible defaults (data dir under `.devbox/virtenv/postgresql/`, port config, etc.).
+2. **Custom** — drop a `process-compose.yaml` in the project root to define your own services.
+
+Override plugin env vars with `--env`, `--env-file`, or the project's `env` block.
+
+### Typical dev loop
+
+```bash
+devbox services up -b             # boot Postgres + Redis in background
+devbox run dev                    # run the app against them
+devbox services stop              # tear down when done
+```
+
+## Shell init hook
+
+`shell.init_hook` runs every time the environment starts — both `devbox shell` and every `devbox run`.
+
+```json
+"shell": {
+  "init_hook": [
+    "test -z $FISH_VERSION && unset GOROOT GOTOOLCHAIN",
+    "export PROJECT_ROOT=$PWD"
+  ]
+}
+```
+
+Good uses:
+
+- Unset host env vars that would poison the build (e.g. stale `GOROOT`).
+- Export computed values that can't live in the static `env` block.
+- Create local directories or install tool binaries that are cheap to check.
+
+Avoid:
+
+- Expensive work — it runs on every invocation.
+- Long network calls — they'll slow every `devbox run` in CI.
+- Interactive prompts — breaks non-interactive use.
+
+## `devbox shellenv`
+
+Prints shell commands that load the devbox environment into the *current* shell without spawning a subshell:
+
+```bash
+eval "$(devbox shellenv)"
+```
+
+Useful for:
+
+- Scripts that need devbox packages without `devbox run` wrapping.
+- Shell configs (`.zshrc`) that want a project's devbox env loaded at startup.
+- CI when you want the devbox env active for several steps.
+
+The nicer wrapper is `devbox generate direnv`, which produces a `.envrc` so direnv loads the env automatically on `cd`.