Share a pack

A shared pack is a directory someone else can lint, install and exec. GitHub holds the files and the community catalog indexes them by pull request, with an npm package as a convenience install on top.

File	Required
`surface.json`	Yes
`policy.json`	Yes
`HARNESS.md`	Yes
`LICENSE`	Yes for a standalone repo
`README.md`	Yes for a standalone repo
Wrapped `bin`	Inside the pack directory, relative path

Keep credentials out of the pack, host-absolute paths out of the Skill and product brand names out of public gold packs.

Catalog#

Packs lists every pack you can install today, with its commands and what each one asks before it writes. hcpx search reads the same index (/api/v1/packs), and HCP_CATALOG_URL points it at a private one.

Terminal

hcpx search transit --json
hcpx init transit --template transit
hcpx install ./transit --json
hcpx activate transit --json
hcpx exec transit plan --json -- from=A to=B

Surface	Use
`/api/v1/packs?query=`	Search
`/api/v1/packs/{id}`	One entry

To add your own, scaffold it (--class public-read or gated-write), lint it and let hcpx share print the catalog row:

Terminal

hcpx init weather --class public-read
# edit the three files
hcpx lint ./weather --json
hcpx share ./weather --json

Paste the row into content/catalog/packs.json in a pull request. Reviewers check lint, the class, and that the Skill names every command.

Pack signing, provenance, integrity hashes and pack_id@version resolution belong to the HCP/2.0 registry, and a catalog pull request does not mint them. Until then you install from a directory or a scaffold the CLI writes, and a runtime may install any directory that lints.

npm package#

A pack directory can also be an npm package, by this convention:

Field	Value
`"hcp": { "pack": "." }`	Where `surface.json` lives inside the package
`dependencies["@harnesscontextprotocol/cli"]`	Installs the CLI (`hcpx`, also `hcp`)
`bin`	Optional wrap CLI (`transit`, `weather`, …). Never name it `hcpx` or `hcp`
`files`	The three protocol files plus wrap `bin/`

Terminal

hcpx install npm:@scope/hcp-pack-name --json
hcpx install npm:./path/to/pack --json

HCP's own packages stay a private preview on GitHub Packages by choice (access: restricted on @harnesscontextprotocol/sdk, @harnesscontextprotocol/cli and @harnesscontextprotocol/example), so they are not on the public npm registry.

Extract a gold pack into its own repository#

examples/standalone/transit in the SDK repo is the gold pack built to extract, with the demo binary next to the three files, an MIT licence and a vendor-neutral README, so the extract is a plain copy. Work through this list before gh repo create harnesscontextprotocol/hcp-example-transit, and keep the repository private until every item holds:

bun run verify:legal passes on the docs site.
The pack lints clean from a fresh clone: hcpx lint . --json.
wrap.bin is a path inside the repo (./bin/transit.mjs), not ../../bins/.
README shows install, activate, and one read exec.
No tokens, .env, or host paths.
Licence matches the SDK (MIT for executable examples).

Minimum to share#

Catalog#

npm package#

Extract a gold pack into its own repository#

Related#