Chain Hub Docs

Quickstart

Install from npm, initialize your hub, then link all supported IDEs.

$ npm install -g chain-hub $ chain init $ chain setup $ chain list

By default your hub lives at ~/chain-hub (visible in your home folder). You can override this with CHAIN_HOME when needed.

CLI and hub updates

The chain command is installed from the chain-hub npm package. Update the CLI by running the same global install as for a fresh setup:

$ npm install -g chain-hub $ chain --version

After upgrading the CLI, run chain init so CHAIN_HOME/core/ matches the bundled core in that release. Run chain setup again if release notes mention IDE symlink changes. For skills installed from the registry or GitHub bundles, use chain update.

Choose hub location

Users can pick their own hub location while keeping a safe default. Resolution order is:

--chain-home <path> (per-command override)
CHAIN_HOME environment variable
chain config set chain_home <path> (persisted user config)
default ~/chain-hub

$ chain --chain-home ~/.chain-sandbox init $ CHAIN_HOME=~/alt-chain-home chain status $ chain config set chain_home ~/my-chain-home $ chain config get chain_home

Install content types

Chain Hub supports four main content types. Skills can be installed via CLI; workflows, rules, and agents are installed by placing files in your CHAIN_HOME folders.

$ chain add github:owner/repo $ chain new my-skill $ chain setup $ chain validate

Skills: install with chain add <slug-or-github-source> or scaffold with chain new <slug> (registers the slug under personal in skills-registry.yaml). Stored in CHAIN_HOME/skills/.
Workflows: add workflow markdown files under CHAIN_HOME/workflows/, then run chain setup to sync IDE links.
Rules: add rule files under CHAIN_HOME/rules/, then run chain setup so editors pick up updates.
Agents: add agent definitions under CHAIN_HOME/agents/, then run chain setup to link into supported IDE locations.

Copying a skill folder by hand (Finder, file manager, or git) only drops files under skills/<slug>/. The hub also needs that <slug> in skills-registry.yaml under the right list — typically personal: for your own skills, or core: when mirroring bundled skills that also appear under CHAIN_HOME/core/skills/. chain_hub: is for skills installed with chain add from the registry. Prefer chain add / chain new so the registry stays in sync.

After adding or updating any content type, use chain validate to catch structure or schema issues before committing or sharing.

Core concepts

One source of truth: all user data belongs in CHAIN_HOME.
Protected core: chain init copies bundled content to CHAIN_HOME/core/.
Your content: create and maintain skills/, agents/, workflows/, rules/ at hub root.
IDE sync: chain setup symlinks from hub into editor-specific locations.
Registry lists: core (bundled skills under skills/), chain_hub (registry installs), personal (yours / GitHub / manual), plus optional packs, community, cli_packages.

Tip: treat editor folders as mirrors. Edit and back up CHAIN_HOME, not the linked targets.

Command overview

Command	What it does
`chain init`	Installs/refreshes protected core assets in `CHAIN_HOME`.
`chain setup`	Creates or repairs editor symlinks.
`chain status`	Shows per-IDE symlink health.
`chain list`	Lists installed skills and source labels.
`chain add <slug>`	Installs from registry or GitHub source.
`chain update`	Refreshes registry and GitHub-bundle skills from their sources.
`chain new <slug>`	Scaffolds a new skill.
`chain validate`	Validates skills and workflows.
`chain config get\|set\|unset chain_home`	Shows or manages persisted default hub path.

Full detail lives in the CLI docs: cli/README.md.

Develop and test locally

Use this when you work from a git clone of Chain Hub (not the published npm install). You need Bun installed.

Marketing site (apps/web) — landing page and this documentation:

$ cd apps/web $ bun install $ bun run dev $ bun run build $ bun run preview

bun run dev starts the Astro dev server; open the URL printed in the terminal (often http://localhost:4321). bun run build emits apps/web/dist/; bun run preview serves that production build locally.

CLI (cli) — same checks as CI:

$ cd cli $ bun install $ bun test $ bun run build $ bun run pack:check

Run the CLI from source with bun run chain.ts (see cli/README.md). To avoid touching your real hub, point at a throwaway directory:

$ cd cli $ CHAIN_HOME=/tmp/chain-hub-dev bun run chain.ts init $ CHAIN_HOME=/tmp/chain-hub-dev bun run chain.ts validate

Test before `npm publish`

For maintainers releasing the chain-hub package: run the same gates as CI, then verify the tarball installs and runs like end users will.

Unit tests and package layout — from cli/: bun test and bun run pack:check (syncs bundled core/ into the package, builds dist/chain.js, and asserts the files npm will ship).
Package smoke test — installs the packed tarball into a temp directory and runs node …/dist/chain.js init and validate with an isolated CHAIN_HOME. Uses npm and Node (not Bun) to mirror real installs:

$ cd cli $ bun run smoke:package

Dry-run publish — runs lifecycle hooks (including prepack) without uploading; use from cli/:

$ cd cli $ npm publish --dry-run

Optional manual check: npm pack in cli/, then npm install -g ./chain-hub-<version>.tgz in a throwaway environment and run chain init / chain validate.

Troubleshooting

chain runs the wrong binary? Check aliases first.

$ which -a chain $ type chain

If you see an old alias (for example bun run …/Code/chain/cli/chain.ts after renaming or moving the monorepo), update CHAIN_HUB_REPO / the alias target to your current clone (see cli/README.md), remove the stale line from your shell profile, then run unalias chain and open a new terminal.

npm publish fails with 403 + 2FA? Enable npm 2FA or use a granular access token with publish rights.

Docs