Skip to main content

​
Synopsis

​
Description

Reads a skill repository, finds the plugins in it, and writes one package definition per plugin, pinned to a single commit. <path|url> is an owner/repo shorthand, a GitHub URL, or a local git clone. Only GitHub is supported. A local clone is imported at its committed HEAD, and its origin remote must point at GitHub; uncommitted changes are never imported. Import:
  1. Clones the repository and pins the commit.
  2. Finds every plugin and its skills.
  3. Computes the hash of the source the build will fetch.
  4. Validates each plugin with the check-plugin rules. A plugin with errors is not written; the others are.
  5. Writes agent-plugin-<name>/default.json and agent-plugin-<name>/default.nix under the packages folder, and prints a summary.
  6. Writes what the packages need to build beside them: the builder in the lib folder, and the flox-agent that ran the import as its own package.
The summary is new plugin on a first import. On a re-import it is unchanged at <rev>, regenerated at <rev>, or <old> -> <new> with the skills added and removed. There is no separate update command; re-importing is how a package moves to a newer commit. default.json records the source, the skills, the flags given, and every warning. default.nix is the same in every package, apart from a block between its BEGIN custom and END custom markers that a re-import keeps. A package written before default.json holds source.json instead; import still reads it, and moves it to default.json on its next write.

​
Finding plugins

Import tries these in order, and the first that matches declares the repository’s plugins:
  1. Agent Plugins manifests (plugin.json).
  2. A marketplace listing, such as .claude-plugin/marketplace.json.
  3. Claude plugin manifests (.claude-plugin/plugin.json).
  4. The whole repository as one plugin.
The later cases still run for folders nothing has claimed, and a plugin they find there is added beside the declared ones. The last case runs only when nothing else matched. Within each plugin, import searches for SKILL.md files and records anything it does not package as a warning.

​
Options

Every option except --yes and --replay is recorded in default.json. --pkgs-dir and --lib-dir are recorded only when given, relative to the root. --replay can be combined only with --pkgs-dir and --yes. A packages folder under .flox needs that .flox to be a Flox environment, and one anywhere else needs a flake.nix beside it. When it is missing, import offers to create it; --yes creates it without asking, and a run without a terminal fails instead. --out was removed. Passing it is a usage error that names --pkgs-dir instead. A package folder belongs to the repository that wrote it. Import refuses to overwrite a package recorded from a different repository.

​
Exit status

​
Examples

Import a repository into the current environment:
Import a folder of skills that discovery misses, under a chosen name:
Update a package, repeating the flags it was first imported with:
Import into an agent-pkgs checkout:

​
See also