Publishing Competencies

What you'll accomplish: Package and publish a competency to a registry for others to install.

Package workflow

There is no local package sign or package keygen command — the registry signs the package at publish time, using the identity of the authenticated publisher. You never generate or hold a local signing key.

1. Scaffold the package

hoziron-cli package init --type competency claims-intake

This creates:

claims-intake/
├── MANIFEST.toml    (package metadata)
├── COMPETENCY.md  (competency definition)
└── payload/         (additional files: knowledge docs, etc.)

2. Write the MANIFEST.toml

[package]
type = "competency"
name = "claims-intake"
version = "1.0.0"
description = "First Notice of Loss processing for property and auto claims"
license = "MIT"
min_platform_version = "0.5.0"

[package.author]
name = "Your Company"
email = "platform@company.com"

[package.metadata]
keywords = ["insurance", "claims", "fnol"]
categories = ["insurance/claims"]
regions = ["us", "uk"]

[dependencies]
document-ocr = "^1.0"
postgresql-connector = "^2.0"
email-skill = "^1.2"

3. Build the archive

hoziron-cli package build ./claims-intake/

Produces a deterministic .hpkg archive (reproducible builds — same input always produces byte-identical output).

4. Lint for compliance

hoziron-cli package lint ./claims-intake/

Checks: valid name, version, description, license, dependency constraints, and category taxonomy.

5. Publish to registry

hoziron-cli package publish ./claims-intake/ --notes "Initial release: FNOL intake for auto claims"

--notes is required — a short human-readable summary of what changed, like a GitHub Release note. Omit it and you'll be prompted interactively, unless --json is set, in which case it must be supplied on the command line. publish runs the full pipeline itself (lint → build → upload); it does not require you to have already run package build separately. The registry signs the package (Ed25519, over the MANIFEST.toml content and a SHA-256 Merkle root of the payload directory) at upload time, using the authenticated publisher's identity — there is no local package sign or package keygen command and no local signing key to manage.

Publish target resolution:

  1. Explicit --registry <name> flag
  2. Scope-based routing (if package name has @scope/ prefix)
  3. default_publish_registry config field

If you're publishing a fork of another package, pass --derived-from-registry, --derived-from-name, and --derived-from-version together to record the lineage — the origin's content hash is looked up live from that registry, not taken on trust from the flags alone.

Verification

Others can verify your package:

hoziron-cli package verify ./claims-intake/ --provenance

Without --provenance, this checks only that the local SHA-256 content hash matches what's recorded in MANIFEST.toml. With --provenance, it also contacts the registry to verify the registry's signature and display the authenticated publisher identity. To see a package's full version history and any fork lineage:

hoziron-cli package provenance claims-intake

Next steps

Related: