Use for publishing user packages to flox for use in Flox environments. Use for package distribution and sharing of builds defined in a flox environment.
Publishes built packages from Flox environments to Flox catalogs for distribution. Use when you've built a package with `flox build` and want to share binaries with others. Triggers on `flox publish` commands, requiring a git-tracked repo with clean state and authentication.
/plugin marketplace add flox/flox-agentic/plugin install flox@flox-agenticThis skill inherits all available tools. When active, it can use any tool Claude has access to.
flox publish # Publish all packages
flox publish my_package # Publish single package
flox publish -o myorg package # Publish to organization
flox publish -o myuser package # Publish to personal namespace
flox auth login # Authenticate before publishing
Publishing packages enables a clear separation between development and runtime/consumption:
Phase 1: Development Environment
# .flox/env/manifest.toml (in git with source code)
[install]
gcc.pkg-path = "gcc13"
make.pkg-path = "make"
python.pkg-path = "python311Full"
[build.myapp]
command = '''
python setup.py build
mkdir -p $out/bin
cp build/myapp $out/bin/
'''
version = "1.0.0"
Developers work in this environment, commit .flox/ to git alongside source code.
Phase 2: Build and Publish
# Build the package
flox build myapp
# Publish to catalog
flox publish -o myorg myapp
The published package contains BINARIES/ARTIFACTS (what's in $out/), NOT source code.
Phase 3: Runtime Environment
# Separate environment (can be pushed to FloxHub)
[install]
myapp.pkg-path = "myorg/myapp" # The published package
Consumers create runtime environments and install the published package. No build tools needed, no source code exposed.
Key insight: You don't install the published package back into the development environment - that would be circular. Published packages are installed into OTHER environments (different projects, production, etc.).
Before publishing:
[build] section or .flox/pkgs/[install]Run authentication before first publish:
flox auth login
# Publish single package
flox publish my_package
# Publish all packages
flox publish
# Publish to organization
flox publish -o myorg my_package
# Publish to personal namespace (for testing)
flox publish -o mypersonalhandle my_package
Personal catalogs: Only visible to you (good for testing)
alice/helloOrganization catalogs: Shared with team members (paid feature)
acme/toolFlox clones your repo to a temp location and performs a clean build to ensure reproducibility. Only packages that build successfully in this clean environment can be published.
This validation ensures:
flox search, flox show, flox installflox install <catalog>/<package>Users can then:
# Search for your package
flox search my_package
# See package details
flox show myorg/my_package
# Install the package
flox install myorg/my_package
Published packages contain:
$out/)runtime-packagesPublished packages do NOT contain:
$out/).flox/ directory itselfThis separation allows you to share built artifacts without exposing source code.
Developer workflow:
Create development environment with build tools:
mkdir myapp && cd myapp
flox init
flox install gcc make python311Full
Add source code and build definition to .flox/env/manifest.toml:
[build.myapp]
command = '''make && cp myapp $out/bin/'''
version = "1.0.0"
Commit to git (environment definition + source code):
git add .flox/ src/
git commit -m "Add development environment and source"
git push origin main
Build and publish package (binaries/artifacts):
flox build myapp
flox publish -o myorg myapp
Other developers:
git clone <repo> && cd myapp && flox activateConsumers:
flox init && flox install myorg/myappflox install myorg/myappuser/project from upstream/project).flox/ to fork with build definitionsgit push origin mainflox publish -o username package-nameflox install username/package-name[build.mytool]
version = "1.2.3" # Major.Minor.Patch
description = "My awesome tool"
[build.mytool]
version.command = "git describe --tags"
description = "My awesome tool"
[build.mytool]
version.file = "VERSION.txt"
description = "My awesome tool"
[build.rustapp]
version.command = "cargo metadata --no-deps --format-version 1 | jq -r '.packages[0].version'"
You can publish multiple variants of the same project:
[build.myapp]
command = '''
cargo build --release
mkdir -p $out/bin
cp target/release/myapp $out/bin/
'''
version = "1.0.0"
description = "Production build"
sandbox = "pure"
[build.myapp-debug]
command = '''
cargo build
mkdir -p $out/bin
cp target/debug/myapp $out/bin/myapp-debug
'''
version = "1.0.0"
description = "Debug build with symbols"
sandbox = "off"
Both can be published and users can choose which to install.
flox build myapp
./result-myapp/bin/myapp --version
flox install ./result-myapp
Publish to your personal namespace first:
flox publish -o myusername myapp
Then test installation:
flox install myusername/myapp
Once validated, republish to organization:
flox publish -o myorg myapp
Many repos use master not main - check with git branch
Run flox auth login before first publish
Commit and push ALL changes before flox publish:
git status # Check for uncommitted changes
git add .flox/
git commit -m "Add flox build configuration"
git push origin master
List only what package needs at runtime, not build deps:
[install]
gcc.pkg-path = "gcc"
make.pkg-path = "make"
[build.myapp]
command = '''make && cp myapp $out/bin/'''
runtime-packages = [] # No runtime deps needed
All files referenced in build must be tracked:
git add .flox/pkgs/*
git add src/
git commit -m "Add build files"
For Nix expression builds in .flox/pkgs/:
mkdir -p .flox/pkgs
cat > .flox/pkgs/hello.nix << 'EOF'
{ hello }:
hello.overrideAttrs (oldAttrs: {
patches = (oldAttrs.patches or []) ++ [ ./my.patch ];
})
EOF
git add .flox/pkgs/*
git commit -m "Add hello package"
git push
flox publish hello
You can publish non-code artifacts:
[build.nginx-config]
command = '''
mkdir -p $out/etc
cp nginx.conf $out/etc/
cp -r conf.d $out/etc/
'''
version = "1.0.0"
description = "Organization Nginx configuration"
[build.api-proto]
command = '''
mkdir -p $out/share/proto
cp proto/**/*.proto $out/share/proto/
'''
version = "2.1.0"
description = "API protocol definitions"
Teams install and reference via $FLOX_ENV/etc/ or $FLOX_ENV/share/.
name: Publish to Flox
on:
push:
tags:
- 'v*'
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install Flox
run: |
curl -fsSL https://downloads.flox.dev/by-env/stable/install | bash
- name: Authenticate
env:
FLOX_AUTH_TOKEN: ${{ secrets.FLOX_AUTH_TOKEN }}
run: flox auth login --token "$FLOX_AUTH_TOKEN"
- name: Publish package
run: flox publish -o myorg mypackage
publish:
stage: deploy
only:
- tags
script:
- curl -fsSL https://downloads.flox.dev/by-env/stable/install | bash
- flox auth login --token "$FLOX_AUTH_TOKEN"
- flox publish -o myorg mypackage
[build.cli]
description = "High-performance log shipper with filtering" # Good: specific, descriptive
# Avoid:
# description = "My tool" # Too vague
# description = "CLI" # Not descriptive enough
Only include what's actually needed at runtime:
[install]
# Build-time only
gcc.pkg-path = "gcc"
make.pkg-path = "make"
# Runtime dependency
libssl.pkg-path = "openssl"
[build.myapp]
runtime-packages = ["libssl"] # Only runtime deps
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.