> ## Documentation Index
> Fetch the complete documentation index at: https://flox.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Package a skill repository

> Turn a GitHub repository of agent skills into a pinned agent plugin package, build it with Flox, and install it into an environment.

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](https://flox.dev/docs/ai-agents/quickstart.md).
* 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:

```bash theme={null}
git init
```

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:

```bash theme={null}
flox agent import juliusbrussee/caveman
```

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:

```console theme={null}
caveman: new plugin at 3dc497a7f858 (22 skills)
  written to .flox/pkgs/agent-plugin-caveman
```

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:

| Flag | Use it to |
| - | - |
| `--plugin PATH[=NAME]` | Treat a folder as a plugin, and optionally name it |
| `--path-ignore GLOB` | Skip matching paths, such as test fixtures |
| `--no-auto-discovery` | Import only the `--plugin` folders |
| `--dependency ATTR` | Name a Nixpkgs package a script's interpreter comes from |

See the [`flox agent import`](https://flox.dev/docs/ai-agents/reference/flox-agent-import) reference for how discovery works.

## Build and check the package

Track the new files, then build the plugin:

```bash theme={null}
git add .flox
flox build agent-plugin-caveman
```

The build checks the plugin as it assembles it and ends with:

```console theme={null}
⚡︎ Built output: ./result-agent-plugin-caveman
```

Check the built plugin against the Agent Plugins specification:

```bash theme={null}
flox agent check-plugin result-agent-plugin-caveman/share/agent-plugins/caveman
```

Scan it for security issues:

```bash theme={null}
flox agent audit ./result-agent-plugin-caveman
```

See [Audit an agent plugin](https://flox.dev/docs/ai-agents/guides/audit-a-plugin.md) for how to read the score.

## Install it into your environment

Publish the package to your catalog, then install it from there:

```bash theme={null}
flox publish agent-plugin-caveman
flox install <your-handle>/agent-plugin-caveman
```

`flox publish` needs the repository pushed to a remote, with the commit you publish on its branch.
See [`flox publish`](https://flox.dev/docs/man/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`:

```bash theme={null}
flox agent import juliusbrussee/caveman --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](https://github.com/agent-stacks/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.

## Related

* [`flox agent import`](https://flox.dev/docs/ai-agents/reference/flox-agent-import) reference
* [`flox agent check-plugin`](https://flox.dev/docs/ai-agents/reference/flox-agent-check-plugin) reference


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.