Skip to main content
Many skill collections live in GitHub repositories rather than in the catalog. flox agent import reads such a repository, finds its plugins and skills, and writes a package pinned to one commit into your environment. This guide imports a repository, builds the package with flox build, checks it, and installs it.

​
Prerequisites

  • An environment with flox/flox-agent installed, as in the quickstart.
  • Logged in to FloxHub with flox auth login, which installing and publishing need.
  • The environment’s folder is a git repository, because flox build reads only files git tracks:
Run the commands below in a shell where your environment is active, so flox agent is available.

​
Import the repository

Pass the repository as owner/repo, a GitHub URL, or a local clone whose origin is on GitHub:
Import pins the current commit, finds every plugin in the repository, and validates each one. It prints a warning for anything it packages with a deviation and for anything it leaves out, then a summary per plugin:
Each plugin becomes a folder under .flox/pkgs holding two files:
  • default.json records the pinned source, the skills, and the import that produced them, including its warnings.
  • default.nix reads default.json and is the same in every package.
Import also writes what the packages need to build: the builder in .flox/agent-lib/ and the flox-agent that ran the import in .flox/pkgs/flox-agent/. Import only reads from GitHub. Repositories hosted elsewhere are rejected.

​
Choose what gets imported

Most repositories need no flags. When discovery finds the wrong thing, these flags adjust it, and import records them in default.json so a later re-import repeats them: See the flox agent import reference for how discovery works.

​
Build and check the package

Track the new files, then build the plugin:
The build checks the plugin as it assembles it and ends with:
Check the built plugin against the Agent Plugins specification:
Scan it for security issues:
See Audit an agent plugin for how to read the score.

​
Install it into your environment

Publish the package to your catalog, then install it from there:
flox publish needs the repository pushed to a remote, with the commit you publish on its branch. See flox publish for what it checks. flox agent list now shows the plugin, and the next flox agent launch loads it.

​
Update the package

Run the same import again to move to the repository’s latest commit. To repeat the flags recorded the first time, use --replay:
The summary says unchanged, regenerated, or the old and new commit, with the skills added and removed. Build and publish again to ship the new version. The agent plugin packages in the agent-stacks catalog are made the same way, in the agent-pkgs repository. To have a plugin published there, open a pull request to agent-pkgs with the generated folder. Packages there are re-imported automatically when their upstream moves.