[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M79NS3J7EQSSAFDDPY5VPKVG":3,"skill-same:01M79NS3J7EQSSAFDDPY5VPKVG":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":26,"commitSha":27,"skillDirectory":28,"forksCount":14,"repositoryHtmlUrl":29,"repositoryHomepageUrl":6,"ownerHtmlUrl":30,"ownerBlogUrl":6,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M79NS3J7EQSSAFDDPY5VPKVG","flox-environments",null,"Create reproducible, cross-platform (macOS\u002FLinux) development environments with Flox, a declarative Nix-based environment manager. Use when setting up project toolchains, installing system-level dependencies (compilers, databases, native libs), pinning exact package versions for a team, onboarding developers, running local services (PostgreSQL, Redis, Kafka), or solving 'works on my machine' problems — including agent\u002Fvibe-coding setups that need project-scoped tools without sudo. Also use when the user mentions .flox\u002F, manifest.toml, flox activate, or FloxHub.","JunMystery\u002FAgent-Guidance","JunMystery","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F161468934?v=4","01M79MTMV8F0BY8NK1A92RA8A0","Jun","01M79MTMWCFBKPHN5B25E6V20B",0,"MIT","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fflox-environments\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: flox-environments\ndescription: \"Create reproducible, cross-platform (macOS\u002FLinux) development environments with Flox, a declarative Nix-based environment manager. Use when setting up project toolchains, installing system-level dependencies (compilers, databases, native libs), pinning exact package versions for a team, onboarding developers, running local services (PostgreSQL, Redis, Kafka), or solving 'works on my machine' problems — including agent\u002Fvibe-coding setups that need project-scoped tools without sudo. Also use when the user mentions .flox\u002F, manifest.toml, flox activate, or FloxHub.\"\nmetadata:\n  origin: Flox\n---\n\n# Flox Environments\n\nFlox creates reproducible development environments defined in a single TOML manifest. Every developer on the team gets identical packages, tools, and configuration — across macOS and Linux — without containers or VMs. Built on Nix with access to over 150,000 packages.\n\n## When to Activate\n\nUse this skill when the user has an environment management problem — even if they haven't mentioned Flox. Flox is the right tool when:\n\n- The project needs **system-level packages** (compilers, databases, CLI tools) alongside language-specific dependencies\n- **Reproducibility matters** — the setup should work identically on a teammate's machine, in CI, or on a fresh laptop\n- The user needs **multiple tools to coexist** — e.g., Python 3.11 + PostgreSQL 16 + Redis + Node.js in one environment\n- **Cross-platform support** is needed (macOS and Linux from the same config)\n- **AI agents need to install tools** — Flox lets agents add packages to a project-scoped environment without sudo, system pollution, or sandbox restrictions\n\nIf the user just needs a single language runtime with no system dependencies, standard tooling (nvm, pyenv, rustup alone) may suffice. If they need full OS-level isolation, containers might be more appropriate. Flox sits in the sweet spot: declarative, reproducible environments without container overhead.\n\n**Prerequisite:** Flox must be installed first — see [flox.dev\u002Fdocs](https:\u002F\u002Fflox.dev\u002Fdocs\u002Finstall-flox\u002Finstall\u002F) for macOS, Linux, and Docker.\n\n## Core Concepts\n\nFlox environments are defined in `.flox\u002Fenv\u002Fmanifest.toml` and activated with `flox activate`. The manifest declares packages, environment variables, setup hooks, and shell configuration — everything needed to reproduce the environment anywhere.\n\n**Key paths:**\n- `.flox\u002Fenv\u002Fmanifest.toml` — Environment definition (commit this)\n- `$FLOX_ENV` — Runtime path to installed packages (like `\u002Fusr` — contains `bin\u002F`, `lib\u002F`, `include\u002F`)\n- `$FLOX_ENV_CACHE` — Persistent local storage for caches, venvs, data (survives rebuilds)\n- `$FLOX_ENV_PROJECT` — Project root directory (where `.flox\u002F` lives)\n\n## Essential Commands\n\n```bash\nflox init                       # Create new environment\nflox search \u003Cpackage> [--all]   # Search for packages\nflox show \u003Cpackage>             # Show available versions\nflox install \u003Cpackage>          # Add a package\nflox list                       # List installed packages\nflox activate                   # Enter environment\nflox activate -- \u003Ccmd>          # Run a command in the environment without a subshell\nflox edit                       # Edit manifest interactively\n```\n\n## Manifest Structure\n\n```toml\n# .flox\u002Fenv\u002Fmanifest.toml\n\n[install]\n# Packages to install — the core of the environment\nripgrep.pkg-path = \"ripgrep\"\njq.pkg-path = \"jq\"\n\n[vars]\n# Static environment variables\nDATABASE_URL = \"postgres:\u002F\u002Flocalhost:5432\u002Fmyapp\"\n\n[hook]\n# Non-interactive setup scripts (run every activation)\non-activate = \"\"\"\n  echo \"Environment ready\"\n\"\"\"\n\n[profile]\n# Shell functions and aliases (available in interactive shell)\ncommon = \"\"\"\n  alias dev=\"npm run dev\"\n\"\"\"\n\n[options]\n# Supported platforms\nsystems = [\"x86_64-linux\", \"aarch64-linux\", \"x86_64-darwin\", \"aarch64-darwin\"]\n```\n\n## Package Installation Patterns\n\n### Basic Installation\n\n```toml\n[install]\nnodejs.pkg-path = \"nodejs\"\npython.pkg-path = \"python311\"\nrustup.pkg-path = \"rustup\"\n```\n\n### Version Pinning\n\n```toml\n[install]\nnodejs.pkg-path = \"nodejs\"\nnodejs.version = \"^20.0\"          # Semver range: latest 20.x\n\npostgres.pkg-path = \"postgresql\"\npostgres.version = \"16.2\"         # Exact version\n```\n\n### Platform-Specific Packages\n\n```toml\n[install]\n# Linux-only tools\nvalgrind.pkg-path = \"valgrind\"\nvalgrind.systems = [\"x86_64-linux\", \"aarch64-linux\"]\n\n# macOS frameworks\nSecurity.pkg-path = \"darwin.apple_sdk.frameworks.Security\"\nSecurity.systems = [\"x86_64-darwin\", \"aarch64-darwin\"]\n\n# GNU tools on macOS (where BSD defaults differ)\ncoreutils.pkg-path = \"coreutils\"\ncoreutils.systems = [\"x86_64-darwin\", \"aarch64-darwin\"]\n```\n\n### Resolving Package Conflicts\n\nWhen two packages install the same binary, use `priority` (lower number wins):\n\n```toml\n[install]\ngcc.pkg-path = \"gcc12\"\ngcc.priority = 3\n\nclang.pkg-path = \"clang_18\"\nclang.priority = 5               # gcc wins file conflicts\n```\n\nUse `pkg-group` to group packages that should resolve versions together:\n\n```toml\n[install]\npython.pkg-path = \"python311\"\npython.pkg-group = \"python-stack\"\n\npip.pkg-path = \"python311Packages.pip\"\npip.pkg-group = \"python-stack\"    # Resolves together with python\n```\n\n## Language-Specific Recipes\n\n### Python with uv\n\n```toml\n[install]\npython.pkg-path = \"python311\"\nuv.pkg-path = \"uv\"\n\n[vars]\nUV_CACHE_DIR = \"$FLOX_ENV_CACHE\u002Fuv-cache\"\nPIP_CACHE_DIR = \"$FLOX_ENV_CACHE\u002Fpip-cache\"\n\n[hook]\non-activate = \"\"\"\n  venv=\"$FLOX_ENV_CACHE\u002Fvenv\"\n  if [ ! -d \"$venv\" ]; then\n    uv venv \"$venv\" --python python3\n  fi\n  if [ -f \"$venv\u002Fbin\u002Factivate\" ]; then\n    source \"$venv\u002Fbin\u002Factivate\"\n  fi\n\n  if [ -f requirements.txt ] && [ ! -f \"$FLOX_ENV_CACHE\u002F.deps_installed\" ]; then\n    uv pip install --python \"$venv\u002Fbin\u002Fpython\" -r requirements.txt --quiet\n    touch \"$FLOX_ENV_CACHE\u002F.deps_installed\"\n  fi\n\"\"\"\n```\n\n### Node.js\n\n```toml\n[install]\nnodejs.pkg-path = \"nodejs\"\nnodejs.version = \"^20.0\"\n\n[hook]\non-activate = \"\"\"\n  if [ -f package.json ] && [ ! -d node_modules ]; then\n    npm install --silent\n  fi\n\"\"\"\n```\n\n### Rust\n\n```toml\n[install]\nrustup.pkg-path = \"rustup\"\npkg-config.pkg-path = \"pkg-config\"\nopenssl.pkg-path = \"openssl\"\n\n[vars]\nRUSTUP_HOME = \"$FLOX_ENV_CACHE\u002Frustup\"\nCARGO_HOME = \"$FLOX_ENV_CACHE\u002Fcargo\"\n\n[profile]\ncommon = \"\"\"\n  export PATH=\"$CARGO_HOME\u002Fbin:$PATH\"\n\"\"\"\n```\n\n### Go\n\n```toml\n[install]\ngo.pkg-path = \"go\"\ngopls.pkg-path = \"gopls\"\ndelve.pkg-path = \"delve\"\n\n[vars]\nGOPATH = \"$FLOX_ENV_CACHE\u002Fgo\"\nGOBIN = \"$FLOX_ENV_CACHE\u002Fgo\u002Fbin\"\n\n[profile]\ncommon = \"\"\"\n  export PATH=\"$GOBIN:$PATH\"\n\"\"\"\n```\n\n### C\u002FC++\n\n```toml\n[install]\ngcc.pkg-path = \"gcc13\"\ngcc.pkg-group = \"compilers\"\n\n# IMPORTANT: gcc alone doesn't expose libstdc++ headers — you need gcc-unwrapped\ngcc-unwrapped.pkg-path = \"gcc-unwrapped\"\ngcc-unwrapped.pkg-group = \"libraries\"\n\ncmake.pkg-path = \"cmake\"\ncmake.pkg-group = \"build\"\n\ngnumake.pkg-path = \"gnumake\"\ngnumake.pkg-group = \"build\"\n\ngdb.pkg-path = \"gdb\"\ngdb.systems = [\"x86_64-linux\", \"aarch64-linux\"]\n```\n\n## Hooks and Profile\n\n### Hooks — Non-Interactive Setup\n\nHooks run on every activation. Keep them fast and idempotent. Rule of thumb: **if it should happen automatically, put it in `[hook]`; if the user should be able to type it, put it in `[profile]`.**\n\n```toml\n[hook]\non-activate = \"\"\"\n  setup_database() {\n    if [ ! -d \"$FLOX_ENV_CACHE\u002Fpgdata\" ]; then\n      initdb -D \"$FLOX_ENV_CACHE\u002Fpgdata\" --no-locale --encoding=UTF8\n    fi\n  }\n  setup_database\n\"\"\"\n```\n\n### Profile — Interactive Shell Configuration\n\nProfile code is available in the user's shell session.\n\n```toml\n[profile]\ncommon = \"\"\"\n  dev() { npm run dev; }\n  test() { npm run test -- \"$@\"; }\n\"\"\"\n```\n\n## Anti-Patterns\n\n### Absolute Paths\n\n```toml\n# BAD — breaks on other machines\n[vars]\nPROJECT_DIR = \"\u002Fhome\u002Falice\u002Fprojects\u002Fmyapp\"\n\n# GOOD — use Flox environment variables\n[vars]\nPROJECT_DIR = \"$FLOX_ENV_PROJECT\"\n```\n\n### Using exit in Hooks\n\n```toml\n# BAD — kills the shell\n[hook]\non-activate = \"\"\"\n  if [ ! -f config.json ]; then\n    echo \"Missing config\"\n    exit 1\n  fi\n\"\"\"\n\n# GOOD — return from hook, don't exit\n[hook]\non-activate = \"\"\"\n  if [ ! -f config.json ]; then\n    echo \"Missing config — run setup first\"\n    return 1\n  fi\n\"\"\"\n```\n\n### Storing Secrets in Manifest\n\n```toml\n# BAD — manifest is committed to git\n[vars]\nAPI_KEY = \"\u003Cset-at-runtime>\"\n\n# GOOD — reference external config or pass at runtime\n# Use: API_KEY=\"\u003Cyour-api-key>\" flox activate\n[vars]\nAPI_KEY = \"${API_KEY:-}\"\n```\n\n### Slow Hooks Without Idempotency Guards\n\n```toml\n# BAD — reinstalls every activation\n[hook]\non-activate = \"\"\"\n  pip install -r requirements.txt\n\"\"\"\n\n# GOOD — skip if already installed\n[hook]\non-activate = \"\"\"\n  if [ ! -f \"$FLOX_ENV_CACHE\u002F.deps_installed\" ]; then\n    uv pip install -r requirements.txt --quiet\n    touch \"$FLOX_ENV_CACHE\u002F.deps_installed\"\n  fi\n\"\"\"\n```\n\n### Putting User Commands in Hooks\n\n```toml\n# BAD — hook functions aren't available in the interactive shell\n[hook]\non-activate = \"\"\"\n  deploy() { kubectl apply -f k8s\u002F; }\n\"\"\"\n\n# GOOD — use [profile] for user-invokable functions\n[profile]\ncommon = \"\"\"\n  deploy() { kubectl apply -f k8s\u002F; }\n\"\"\"\n```\n\n## Full-Stack Example\n\nA complete environment for a Python API with PostgreSQL:\n\n```toml\n[install]\npython.pkg-path = \"python311\"\nuv.pkg-path = \"uv\"\npostgresql.pkg-path = \"postgresql_16\"\nredis.pkg-path = \"redis\"\njq.pkg-path = \"jq\"\ncurl.pkg-path = \"curl\"\n\n[vars]\nUV_CACHE_DIR = \"$FLOX_ENV_CACHE\u002Fuv-cache\"\nDATABASE_URL = \"postgres:\u002F\u002Flocalhost:5432\u002Fmyapp\"\nREDIS_URL = \"redis:\u002F\u002Flocalhost:6379\"\n\n[hook]\non-activate = \"\"\"\n  if [ ! -d \"$FLOX_ENV_CACHE\u002Fpgdata\" ]; then\n    initdb -D \"$FLOX_ENV_CACHE\u002Fpgdata\" --no-locale --encoding=UTF8\n  fi\n\n  venv=\"$FLOX_ENV_CACHE\u002Fvenv\"\n  if [ ! -d \"$venv\" ]; then\n    uv venv \"$venv\" --python python3\n  fi\n  if [ -f \"$venv\u002Fbin\u002Factivate\" ]; then\n    source \"$venv\u002Fbin\u002Factivate\"\n  fi\n\n  if [ -f requirements.txt ] && [ ! -f \"$FLOX_ENV_CACHE\u002F.deps_installed\" ]; then\n    uv pip install --python \"$venv\u002Fbin\u002Fpython\" -r requirements.txt --quiet\n    touch \"$FLOX_ENV_CACHE\u002F.deps_installed\"\n  fi\n\"\"\"\n\n[profile]\ncommon = \"\"\"\n  serve() { uvicorn app.main:app --reload --host 0.0.0.0 --port 8000; }\n  migrate() { alembic upgrade head; }\n\"\"\"\n\n[services]\npostgres.command = \"postgres -D $FLOX_ENV_CACHE\u002Fpgdata -k $FLOX_ENV_CACHE\"\nredis.command = \"redis-server --port 6379 --daemonize no\"\n\n[options]\nsystems = [\"x86_64-linux\", \"aarch64-linux\", \"x86_64-darwin\", \"aarch64-darwin\"]\n```\n\nActivate with services: `flox activate --start-services`\n\n## Environment Sharing\n\nFlox environments are git-native. Commit the `.flox\u002F` directory and every collaborator gets the same environment:\n\n```bash\ngit add .flox\u002F\ngit commit -m \"Add Flox environment\"\n# Teammates just run:\ngit clone \u003Crepo> && cd \u003Crepo> && flox activate\n```\n\nFor reusable base environments across projects, push to FloxHub:\n\n```bash\nflox push                         # Push environment to FloxHub\nflox activate -r owner\u002Fenv-name   # Activate remote environment anywhere\n```\n\nCompose environments with `[include]`:\n\n```toml\n[include]\nbase.floxhub = \"myorg\u002Fpython-base\"\n\n[install]\n# Project-specific additions on top of base\nfastapi.pkg-path = \"python311Packages.fastapi\"\n```\n\n## AI-Assisted and Vibe Coding\n\nFlox is ideal for AI-assisted development and vibe coding workflows. When an AI agent needs a tool that isn't available in the current environment — a compiler, a database, a linter, a CLI utility — it can add it to the project's Flox manifest without requiring sudo access, polluting system packages, or hitting sandbox restrictions.\n\n**Why this matters for agents:**\n- **No sudo required** — `flox install` works entirely in user space, so agents can add packages without elevated permissions\n- **Project-scoped** — packages are installed into the project environment only, not globally, so different projects can have different versions without conflict\n- **Sandbox-friendly** — agents running in sandboxed or restricted environments can still install the tools they need through Flox\n- **Reversible** — every change is captured in `manifest.toml`, so unwanted packages can be removed cleanly with no system residue\n- **Reproducible** — when an agent sets up an environment, that exact setup is committed to git and works for everyone\n\n**Agent workflow pattern:**\n\n```bash\n# Agent discovers it needs a tool (e.g., jq for JSON processing)\nflox search jq                    # Verify the package exists\nflox install jq                   # Install into project environment\n\n# Or for more control, edit the manifest directly\ntmp_manifest=\"$(mktemp)\"\nflox list -c > \"$tmp_manifest\"\n# Add the package to [install] section, then apply\nflox edit -f \"$tmp_manifest\"\n\n# Run a command with the tool available\nflox activate -- jq '.results[]' data.json\n```\n\nThis makes Flox a natural fit for any workflow where Claude Code or other AI agents need to bootstrap project tooling on the fly.\n\n## Debugging\n\n```bash\nflox list -c                      # Show raw manifest\nflox activate -- which python     # Check which binary resolves\nflox activate -- env | grep FLOX  # See Flox environment variables\nflox search \u003Cpackage> --all       # Broader package search (case-sensitive)\n```\n\n**Common issues:**\n- **Package not found:** Search is case-sensitive — try `flox search --all`\n- **File conflicts between packages:** Add `priority` to the package that should win\n- **Hook failures:** Use `return` not `exit`; guard with `${FLOX_ENV_CACHE:-}`\n- **Stale dependencies:** Delete the `$FLOX_ENV_CACHE\u002F.deps_installed` flag file\n\n## Related Skills\n\nThe following skills are available as part of the [Flox Claude Code plugin](https:\u002F\u002Fgithub.com\u002Fflox\u002Fflox-skills) for deeper integration:\n\n- **flox** — Environments, services and databases, builds and packaging, containers, FloxHub publishing, environment composition and sharing, and CUDA\u002FGPU development\n- **floxify** — Onboard an existing repo to Flox by detecting its runtimes, services, and build tools\n- **flox-debug** — Diagnose catalog resolution problems when a package won't resolve to the expected version\n\nLearn more and install at [flox.dev\u002Fdocs](https:\u002F\u002Fflox.dev\u002Fdocs\u002Finstall-flox\u002Finstall\u002F)\n","# Flox Environments\n\nFlox creates reproducible development environments defined in a single TOML manifest. Every developer on the team gets identical packages, tools, and configuration — across macOS and Linux — without containers or VMs. Built on Nix with access to over 150,000 packages.\n\n## When to Activate\n\nUse this skill when the user has an environment management problem — even if they haven't mentioned Flox. Flox is the right tool when:\n\n- The project needs **system-level packages** (compilers, databases, CLI tools) alongside language-specific dependencies\n- **Reproducibility matters** — the setup should work identically on a teammate's machine, in CI, or on a fresh laptop\n- The user needs **multiple tools to coexist** — e.g., Python 3.11 + PostgreSQL 16 + Redis + Node.js in one environment\n- **Cross-platform support** is needed (macOS and Linux from the same config)\n- **AI agents need to install tools** — Flox lets agents add packages to a project-scoped environment without sudo, system pollution, or sandbox restrictions\n\nIf the user just needs a single language runtime with no system dependencies, standard tooling (nvm, pyenv, rustup alone) may suffice. If they need full OS-level isolation, containers might be more appropriate. Flox sits in the sweet spot: declarative, reproducible environments without container overhead.\n\n**Prerequisite:** Flox must be installed first — see [flox.dev\u002Fdocs](https:\u002F\u002Fflox.dev\u002Fdocs\u002Finstall-flox\u002Finstall\u002F) for macOS, Linux, and Docker.\n\n## Core Concepts\n\nFlox environments are defined in `.flox\u002Fenv\u002Fmanifest.toml` and activated with `flox activate`. The manifest declares packages, environment variables, setup hooks, and shell configuration — everything needed to reproduce the environment anywhere.\n\n**Key paths:**\n- `.flox\u002Fenv\u002Fmanifest.toml` — Environment definition (commit this)\n- `$FLOX_ENV` — Runtime path to installed packages (like `\u002Fusr` — contains `bin\u002F`, `lib\u002F`, `include\u002F`)\n- `$FLOX_ENV_CACHE` — Persistent local storage for caches, venvs, data (survives rebuilds)\n- `$FLOX_ENV_PROJECT` — Project root directory (where `.flox\u002F` lives)\n\n## Essential Commands\n\n```bash\nflox init                       # Create new environment\nflox search \u003Cpackage> [--all]   # Search for packages\nflox show \u003Cpackage>             # Show available versions\nflox install \u003Cpackage>          # Add a package\nflox list                       # List installed packages\nflox activate                   # Enter environment\nflox activate -- \u003Ccmd>          # Run a command in the environment without a subshell\nflox edit                       # Edit manifest interactively\n```\n\n## Manifest Structure\n\n```toml\n# .flox\u002Fenv\u002Fmanifest.toml\n\n[install]\n# Packages to install — the core of the environment\nripgrep.pkg-path = \"ripgrep\"\njq.pkg-path = \"jq\"\n\n[vars]\n# Static environment variables\nDATABASE_URL = \"postgres:\u002F\u002Flocalhost:5432\u002Fmyapp\"\n\n[hook]\n# Non-interactive setup scripts (run every activation)\non-activate = \"\"\"\n  echo \"Environment ready\"\n\"\"\"\n\n[profile]\n# Shell functions and aliases (available in interactive shell)\ncommon = \"\"\"\n  alias dev=\"npm run dev\"\n\"\"\"\n\n[options]\n# Supported platforms\nsystems = [\"x86_64-linux\", \"aarch64-linux\", \"x86_64-darwin\", \"aarch64-darwin\"]\n```\n\n## Package Installation Patterns\n\n### Basic Installation\n\n```toml\n[install]\nnodejs.pkg-path = \"nodejs\"\npython.pkg-path = \"python311\"\nrustup.pkg-path = \"rustup\"\n```\n\n### Version Pinning\n\n```toml\n[install]\nnodejs.pkg-path = \"nodejs\"\nnodejs.version = \"^20.0\"          # Semver range: latest 20.x\n\npostgres.pkg-path = \"postgresql\"\npostgres.version = \"16.2\"         # Exact version\n```\n\n### Platform-Specific Packages\n\n```toml\n[install]\n# Linux-only tools\nvalgrind.pkg-path = \"valgrind\"\nvalgrind.systems = [\"x86_64-linux\", \"aarch64-linux\"]\n\n# macOS frameworks\nSecurity.pkg-path = \"darwin.apple_sdk.frameworks.Security\"\nSecurity.systems = [\"x86_64-darwin\", \"aarch64-darwin\"]\n\n# GNU tools on macOS (where BSD defaults differ)\ncoreutils.pkg-path = \"coreutils\"\ncoreutils.systems = [\"x86_64-darwin\", \"aarch64-darwin\"]\n```\n\n### Resolving Package Conflicts\n\nWhen two packages install the same binary, use `priority` (lower number wins):\n\n```toml\n[install]\ngcc.pkg-path = \"gcc12\"\ngcc.priority = 3\n\nclang.pkg-path = \"clang_18\"\nclang.priority = 5               # gcc wins file conflicts\n```\n\nUse `pkg-group` to group packages that should resolve versions together:\n\n```toml\n[install]\npython.pkg-path = \"python311\"\npython.pkg-group = \"python-stack\"\n\npip.pkg-path = \"python311Packages.pip\"\npip.pkg-group = \"python-stack\"    # Resolves together with python\n```\n\n## Language-Specific Recipes\n\n### Python with uv\n\n```toml\n[install]\npython.pkg-path = \"python311\"\nuv.pkg-path = \"uv\"\n\n[vars]\nUV_CACHE_DIR = \"$FLOX_ENV_CACHE\u002Fuv-cache\"\nPIP_CACHE_DIR = \"$FLOX_ENV_CACHE\u002Fpip-cache\"\n\n[hook]\non-activate = \"\"\"\n  venv=\"$FLOX_ENV_CACHE\u002Fvenv\"\n  if [ ! -d \"$venv\" ]; then\n    uv venv \"$venv\" --python python3\n  fi\n  if [ -f \"$venv\u002Fbin\u002Factivate\" ]; then\n    source \"$venv\u002Fbin\u002Factivate\"\n  fi\n\n  if [ -f requirements.txt ] && [ ! -f \"$FLOX_ENV_CACHE\u002F.deps_installed\" ]; then\n    uv pip install --python \"$venv\u002Fbin\u002Fpython\" -r requirements.txt --quiet\n    touch \"$FLOX_ENV_CACHE\u002F.deps_installed\"\n  fi\n\"\"\"\n```\n\n### Node.js\n\n```toml\n[install]\nnodejs.pkg-path = \"nodejs\"\nnodejs.version = \"^20.0\"\n\n[hook]\non-activate = \"\"\"\n  if [ -f package.json ] && [ ! -d node_modules ]; then\n    npm install --silent\n  fi\n\"\"\"\n```\n\n### Rust\n\n```toml\n[install]\nrustup.pkg-path = \"rustup\"\npkg-config.pkg-path = \"pkg-config\"\nopenssl.pkg-path = \"openssl\"\n\n[vars]\nRUSTUP_HOME = \"$FLOX_ENV_CACHE\u002Frustup\"\nCARGO_HOME = \"$FLOX_ENV_CACHE\u002Fcargo\"\n\n[profile]\ncommon = \"\"\"\n  export PATH=\"$CARGO_HOME\u002Fbin:$PATH\"\n\"\"\"\n```\n\n### Go\n\n```toml\n[install]\ngo.pkg-path = \"go\"\ngopls.pkg-path = \"gopls\"\ndelve.pkg-path = \"delve\"\n\n[vars]\nGOPATH = \"$FLOX_ENV_CACHE\u002Fgo\"\nGOBIN = \"$FLOX_ENV_CACHE\u002Fgo\u002Fbin\"\n\n[profile]\ncommon = \"\"\"\n  export PATH=\"$GOBIN:$PATH\"\n\"\"\"\n```\n\n### C\u002FC++\n\n```toml\n[install]\ngcc.pkg-path = \"gcc13\"\ngcc.pkg-group = \"compilers\"\n\n# IMPORTANT: gcc alone doesn't expose libstdc++ headers — you need gcc-unwrapped\ngcc-unwrapped.pkg-path = \"gcc-unwrapped\"\ngcc-unwrapped.pkg-group = \"libraries\"\n\ncmake.pkg-path = \"cmake\"\ncmake.pkg-group = \"build\"\n\ngnumake.pkg-path = \"gnumake\"\ngnumake.pkg-group = \"build\"\n\ngdb.pkg-path = \"gdb\"\ngdb.systems = [\"x86_64-linux\", \"aarch64-linux\"]\n```\n\n## Hooks and Profile\n\n### Hooks — Non-Interactive Setup\n\nHooks run on every activation. Keep them fast and idempotent. Rule of thumb: **if it should happen automatically, put it in `[hook]`; if the user should be able to type it, put it in `[profile]`.**\n\n```toml\n[hook]\non-activate = \"\"\"\n  setup_database() {\n    if [ ! -d \"$FLOX_ENV_CACHE\u002Fpgdata\" ]; then\n      initdb -D \"$FLOX_ENV_CACHE\u002Fpgdata\" --no-locale --encoding=UTF8\n    fi\n  }\n  setup_database\n\"\"\"\n```\n\n### Profile — Interactive Shell Configuration\n\nProfile code is available in the user's shell session.\n\n```toml\n[profile]\ncommon = \"\"\"\n  dev() { npm run dev; }\n  test() { npm run test -- \"$@\"; }\n\"\"\"\n```\n\n## Anti-Patterns\n\n### Absolute Paths\n\n```toml\n# BAD — breaks on other machines\n[vars]\nPROJECT_DIR = \"\u002Fhome\u002Falice\u002Fprojects\u002Fmyapp\"\n\n# GOOD — use Flox environment variables\n[vars]\nPROJECT_DIR = \"$FLOX_ENV_PROJECT\"\n```\n\n### Using exit in Hooks\n\n```toml\n# BAD — kills the shell\n[hook]\non-activate = \"\"\"\n  if [ ! -f config.json ]; then\n    echo \"Missing config\"\n    exit 1\n  fi\n\"\"\"\n\n# GOOD — return from hook, don't exit\n[hook]\non-activate = \"\"\"\n  if [ ! -f config.json ]; then\n    echo \"Missing config — run setup first\"\n    return 1\n  fi\n\"\"\"\n```\n\n### Storing Secrets in Manifest\n\n```toml\n# BAD — manifest is committed to git\n[vars]\nAPI_KEY = \"\u003Cset-at-runtime>\"\n\n# GOOD — reference external config or pass at runtime\n# Use: API_KEY=\"\u003Cyour-api-key>\" flox activate\n[vars]\nAPI_KEY = \"${API_KEY:-}\"\n```\n\n### Slow Hooks Without Idempotency Guards\n\n```toml\n# BAD — reinstalls every activation\n[hook]\non-activate = \"\"\"\n  pip install -r requirements.txt\n\"\"\"\n\n# GOOD — skip if already installed\n[hook]\non-activate = \"\"\"\n  if [ ! -f \"$FLOX_ENV_CACHE\u002F.deps_installed\" ]; then\n    uv pip install -r requirements.txt --quiet\n    touch \"$FLOX_ENV_CACHE\u002F.deps_installed\"\n  fi\n\"\"\"\n```\n\n### Putting User Commands in Hooks\n\n```toml\n# BAD — hook functions aren't available in the interactive shell\n[hook]\non-activate = \"\"\"\n  deploy() { kubectl apply -f k8s\u002F; }\n\"\"\"\n\n# GOOD — use [profile] for user-invokable functions\n[profile]\ncommon = \"\"\"\n  deploy() { kubectl apply -f k8s\u002F; }\n\"\"\"\n```\n\n## Full-Stack Example\n\nA complete environment for a Python API with PostgreSQL:\n\n```toml\n[install]\npython.pkg-path = \"python311\"\nuv.pkg-path = \"uv\"\npostgresql.pkg-path = \"postgresql_16\"\nredis.pkg-path = \"redis\"\njq.pkg-path = \"jq\"\ncurl.pkg-path = \"curl\"\n\n[vars]\nUV_CACHE_DIR = \"$FLOX_ENV_CACHE\u002Fuv-cache\"\nDATABASE_URL = \"postgres:\u002F\u002Flocalhost:5432\u002Fmyapp\"\nREDIS_URL = \"redis:\u002F\u002Flocalhost:6379\"\n\n[hook]\non-activate = \"\"\"\n  if [ ! -d \"$FLOX_ENV_CACHE\u002Fpgdata\" ]; then\n    initdb -D \"$FLOX_ENV_CACHE\u002Fpgdata\" --no-locale --encoding=UTF8\n  fi\n\n  venv=\"$FLOX_ENV_CACHE\u002Fvenv\"\n  if [ ! -d \"$venv\" ]; then\n    uv venv \"$venv\" --python python3\n  fi\n  if [ -f \"$venv\u002Fbin\u002Factivate\" ]; then\n    source \"$venv\u002Fbin\u002Factivate\"\n  fi\n\n  if [ -f requirements.txt ] && [ ! -f \"$FLOX_ENV_CACHE\u002F.deps_installed\" ]; then\n    uv pip install --python \"$venv\u002Fbin\u002Fpython\" -r requirements.txt --quiet\n    touch \"$FLOX_ENV_CACHE\u002F.deps_installed\"\n  fi\n\"\"\"\n\n[profile]\ncommon = \"\"\"\n  serve() { uvicorn app.main:app --reload --host 0.0.0.0 --port 8000; }\n  migrate() { alembic upgrade head; }\n\"\"\"\n\n[services]\npostgres.command = \"postgres -D $FLOX_ENV_CACHE\u002Fpgdata -k $FLOX_ENV_CACHE\"\nredis.command = \"redis-server --port 6379 --daemonize no\"\n\n[options]\nsystems = [\"x86_64-linux\", \"aarch64-linux\", \"x86_64-darwin\", \"aarch64-darwin\"]\n```\n\nActivate with services: `flox activate --start-services`\n\n## Environment Sharing\n\nFlox environments are git-native. Commit the `.flox\u002F` directory and every collaborator gets the same environment:\n\n```bash\ngit add .flox\u002F\ngit commit -m \"Add Flox environment\"\n# Teammates just run:\ngit clone \u003Crepo> && cd \u003Crepo> && flox activate\n```\n\nFor reusable base environments across projects, push to FloxHub:\n\n```bash\nflox push                         # Push environment to FloxHub\nflox activate -r owner\u002Fenv-name   # Activate remote environment anywhere\n```\n\nCompose environments with `[include]`:\n\n```toml\n[include]\nbase.floxhub = \"myorg\u002Fpython-base\"\n\n[install]\n# Project-specific additions on top of base\nfastapi.pkg-path = \"python311Packages.fastapi\"\n```\n\n## AI-Assisted and Vibe Coding\n\nFlox is ideal for AI-assisted development and vibe coding workflows. When an AI agent needs a tool that isn't available in the current environment — a compiler, a database, a linter, a CLI utility — it can add it to the project's Flox manifest without requiring sudo access, polluting system packages, or hitting sandbox restrictions.\n\n**Why this matters for agents:**\n- **No sudo required** — `flox install` works entirely in user space, so agents can add packages without elevated permissions\n- **Project-scoped** — packages are installed into the project environment only, not globally, so different projects can have different versions without conflict\n- **Sandbox-friendly** — agents running in sandboxed or restricted environments can still install the tools they need through Flox\n- **Reversible** — every change is captured in `manifest.toml`, so unwanted packages can be removed cleanly with no system residue\n- **Reproducible** — when an agent sets up an environment, that exact setup is committed to git and works for everyone\n\n**Agent workflow pattern:**\n\n```bash\n# Agent discovers it needs a tool (e.g., jq for JSON processing)\nflox search jq                    # Verify the package exists\nflox install jq                   # Install into project environment\n\n# Or for more control, edit the manifest directly\ntmp_manifest=\"$(mktemp)\"\nflox list -c > \"$tmp_manifest\"\n# Add the package to [install] section, then apply\nflox edit -f \"$tmp_manifest\"\n\n# Run a command with the tool available\nflox activate -- jq '.results[]' data.json\n```\n\nThis makes Flox a natural fit for any workflow where Claude Code or other AI agents need to bootstrap project tooling on the fly.\n\n## Debugging\n\n```bash\nflox list -c                      # Show raw manifest\nflox activate -- which python     # Check which binary resolves\nflox activate -- env | grep FLOX  # See Flox environment variables\nflox search \u003Cpackage> --all       # Broader package search (case-sensitive)\n```\n\n**Common issues:**\n- **Package not found:** Search is case-sensitive — try `flox search --all`\n- **File conflicts between packages:** Add `priority` to the package that should win\n- **Hook failures:** Use `return` not `exit`; guard with `${FLOX_ENV_CACHE:-}`\n- **Stale dependencies:** Delete the `$FLOX_ENV_CACHE\u002F.deps_installed` flag file\n\n## Related Skills\n\nThe following skills are available as part of the [Flox Claude Code plugin](https:\u002F\u002Fgithub.com\u002Fflox\u002Fflox-skills) for deeper integration:\n\n- **flox** — Environments, services and databases, builds and packaging, containers, FloxHub publishing, environment composition and sharing, and CUDA\u002FGPU development\n- **floxify** — Onboard an existing repo to Flox by detecting its runtimes, services, and build tools\n- **flox-debug** — Diagnose catalog resolution problems when a package won't resolve to the expected version\n\nLearn more and install at [flox.dev\u002Fdocs](https:\u002F\u002Fflox.dev\u002Fdocs\u002Finstall-flox\u002Finstall\u002F)\n",{"name":5,"metadata":24,"description":7},{"origin":25},"Flox","main","5d0a87185c0e172c3901e2a6e5916b6d544b8b94","skills\u002Fflox-environments","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance","https:\u002F\u002Fgithub.com\u002FJunMystery","AI is the typist, I am the architect. Building efficient, secure, and user-centric products through disciplined AI prompt engineering.","2026-11-13 17:41:25",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add JunMystery\u002FAgent-Guidance --skill flox-environments",{"tool":39,"command":40},"bunx","bunx skills add JunMystery\u002FAgent-Guidance --skill flox-environments",{"tool":42,"command":43},"pnpm","pnpm dlx skills add JunMystery\u002FAgent-Guidance --skill flox-environments","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fflox-environments\u002FSKILL.md",true,[],[48,54,60,66,72,78],{"skillNo":49,"name":50,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":51,"categories":52,"keywords":53,"publishedAt":19},"01M79QR1E309VJ6CTQKB32AWWA","zero-trust-architecture-cheat-sheet","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fzero-trust-architecture-cheat-sheet\u002FSKILL.md",[],[],{"skillNo":55,"name":56,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":19},"01M79QQV7GHYR02DYGN41S23WN","xss-filter-evasion-cheat-sheet","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fxss-filter-evasion-cheat-sheet\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":19},"01M79QQNSN7YB8XB61FFSCS3WH","xs-leaks-cheat-sheet","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fxs-leaks-cheat-sheet\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":19},"01M79QQHZZJKFDY9132G5A65C2","xpath-injection-prevention-cheat-sheet","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fxpath-injection-prevention-cheat-sheet\u002FSKILL.md",[],[],{"skillNo":73,"name":74,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M79QQB9ZSD3DJG8658EHQXR1","xml-security-cheat-sheet","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fxml-security-cheat-sheet\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M79QQ60WKV7PFMXWT9CW8PM6","xml-external-entity-prevention-cheat-sheet","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fxml-external-entity-prevention-cheat-sheet\u002FSKILL.md",[],[]]