skillnet

skillnet is a CLI for reconciling local AI skill directories into a checked-in mirror, editing mirrored skills, syncing selected mirror state back to live agent directories, and recording calibration data for multi-phase-plan.

The supported interface in 0.2.0 is the skillnet binary. This crate does not commit to a stable embeddable Rust API yet.

Install

cargo install skillnet

For a source checkout:

cargo install --path .

Nix Home Manager

Add the flake input and import the module:

inputs.skillnet.url = "git+ssh://git@codeberg.org/caniko/skillnet.git";

# In your Home Manager config:
imports = [ inputs.skillnet.hmModules.default ];
programs.skillnet.enable = true;

The module is exported as both hmModules.default and hmModules.skillnet. It installs skillnet on PATH, creates the runtime data directory, and exports skillnet_DATA_DIR and SKILLNET_DATA_DIR for the CLI.

SQLite is the default calibration backend. To use Postgres, select the backend and provide a connection URL:

programs.skillnet = {
  enable = true;
  package = inputs.skillnet.packages.${pkgs.system}.skillnet;

  database = {
    backend = "postgres";
    url = "postgres://user:password@db.example.com/skillnet";
  };
};

The Postgres backend requires a skillnet package built with the postgres feature. The module does not rewrite programs.skillnet.package; choose a package that matches the backend you enable.

The database.url value is written into the Nix store. For production secrets, prefer setting SKILLNET_DATABASE_URL through your usual secret mechanism, such as sops-nix, agenix, or a shell-sourced environment file.

Options:

• programs.skillnet.dataDir defaults to ${config.xdg.dataHome}/skillnet.
• programs.skillnet.database.backend selects sqlite or postgres and defaults to sqlite.
• programs.skillnet.database.path optionally sets the SQLite database path; when unset, calibration data lives at <dataDir>/multi-phase-plan/calibration.sqlite.
• programs.skillnet.database.url sets SKILLNET_DATABASE_URL and is required when programs.skillnet.database.backend = "postgres".
• programs.skillnet.package overrides the package. If pkgs.skillnet is not available in your package set, use inputs.skillnet.packages.${pkgs.system}.skillnet.
• programs.skillnet.extraConfig is reserved for future declarative config.

Storage backends

SQLite is the default calibration backend and needs no configuration:

[database]
backend = "sqlite"
path = "/home/alice/.local/share/skillnet/multi-phase-plan/calibration.sqlite"

The path key is optional. Without it, skillnet uses $skillnet_DATA_DIR/multi-phase-plan/calibration.sqlite, $SKILLNET_DATA_DIR/multi-phase-plan/calibration.sqlite, or $XDG_DATA_HOME/skillnet/multi-phase-plan/calibration.sqlite.

Postgres support is optional and requires a binary built with the postgres feature:

cargo install skillnet --features postgres

Select Postgres with an environment variable:

export SKILLNET_DATABASE_URL='postgres://skillnet@localhost/skillnet'
skillnet calibration migrate

Or with skillnet.toml:

[database]
backend = "postgres"
url = "postgres://skillnet@localhost/skillnet"

Or through the Home Manager module:

programs.skillnet = {
  enable = true;
  package = inputs.skillnet.packages.${pkgs.system}.skillnet;
  database = {
    backend = "postgres";
    url = "postgres://skillnet@localhost/skillnet";
  };
};

--database-url <URL> overrides both environment and config for one command. Plain URLs in programs.skillnet.database.url are written into the Nix store; use sops-nix, agenix, or another secret-backed environment mechanism for production credentials.

Quick Start

Inspect the configured scopes and current divergence:

skillnet status
skillnet scope list
skillnet scope sources

Pull live skills into the mirror and then inspect or regenerate catalog output:

skillnet sync pull --scope global
skillnet skill list --scope global
skillnet catalog generate

Calibration commands are available under the dedicated command group:

skillnet calibration analyze --format table
skillnet calibration proposals --pending

Development

Run the default test suite with:

cargo test --all-targets

Postgres parity tests run when SKILLNET_TEST_PG_URL points at a test database:

export SKILLNET_TEST_PG_URL='postgres://skillnet@localhost/skillnet_test'
cargo test-pg

Configuration Model

skillnet keeps the mirror separate from live agent directories:

• global/ stores the reconciled global skill mirror.
• projects/<name>/ stores reconciled per-project mirrors.
• Live global sources typically come from ~/.agents/skills, ~/.claude/skills, and ~/.codex/skills.
• Project scopes can add .agents/skills, .claude/skills, .codex/skills, root skills, plugin skill directories, and other configured paths.

Configuration lives in skillnet.toml. Catalog metadata lives in skillnet.catalog.toml.

Command Surface

The current top-level commands are:

• status
• completions
• sync
• skill
• scope
• project
• catalog
• calibration

Generate shell completions with:

skillnet completions bash
skillnet completions zsh
skillnet completions fish
skillnet completions elvish
skillnet completions powershell

Documentation

• Docs: https://docs.rs/skillnet
• Source: https://codeberg.org/caniko/skillnet

Release Validation

The release-prep flow validates the repository with:

simit init flake --check --diff
simit release trust check
simit init ci --platform forgejo --check --diff
nix flake check --keep-going --print-build-logs
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- --deny warnings
cargo test --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo package --list
cargo publish --dry-run

License

Licensed under either of:

• MIT (LICENSE-MIT)
• Apache-2.0 (LICENSE-APACHE)