Set up your Instruction Hub

You scaffold and manage an Instruction Hub with the pig toolchain. This guide walks you through creating one, configuring its manifest, and importing your existing skills and MCP configs. For the toolchain’s package identity and full command surface, see The pig CLI reference.

Scaffold a hub

1. Create and enter an empty Git repository for your hub.

2. Run pig init to write hub.yaml, the required pig package, and the asset and generated-output directories.

   pig init --org "YourOrg" \
     --plugin-id your-instruction-hub \
     --plugin-name "Your Instruction Hub"

3. Commit the scaffold so your hub starts from a clean, versioned baseline.

pig init sets plugin_version to 0.1.0 unless you pass --plugin-version. See The pig CLI reference for every flag.

Configure hub.yaml

hub.yaml is your hub’s root manifest. Its schema forbids unknown keys, so a typo or an unsupported key fails validation rather than being ignored.

Key	Required	Description
org	Yes	Your organization name.
plugin_id	Yes	A kebab-case identifier for the hub’s plugins.
plugin_name	Yes	A human-readable display name.
plugin_version	Yes	The hub’s plugin version, in SemVer form.
stable_packages	Yes	The packages to compile. At least one, all unique, and the list must include pig.
targets	No	The compile targets: any of claude, codex, gemini, and cursor. Defaults to all four.

Note

stable_packages must always contain pig. The pig package carries the managed update skill and the host runtime that the toolchain injects at compile time.

Repo layout

After you scaffold and start authoring, a hub looks like this:

hub.yaml                        # root manifest
hub.repo-context.json           # inventory of context files (AGENTS.md, CLAUDE.md, GEMINI.md)
packages/<id>.yaml              # one file per package
assets/
  skills/<id>/SKILL.md          # skill assets (with optional references/, scripts/, asset.yaml)
  commands/<id>.md              # command assets
  mcps/<id>.json                # MCP configs
  # pig init also scaffolds assets/rules, assets/agents, and assets/hooks
.github/workflows/              # hand-authored thin caller workflows for PR checks and publishing
dist/<target>/<package>/        # toolchain-generated, committed plugin packages
.claude-plugin/marketplace.json # toolchain-generated marketplace manifests (Claude, Codex, Cursor)

Only dist/ and the marketplace manifests are toolchain-generated. You author the manifest, packages, assets, and the thin .github/workflows/ caller workflows.

Import existing instructions

If you already have skills and MCP configs, pig scan brings them into the hub instead of recreating them by hand:

pig scan --source /path/to/existing/repo

pig scan imports skills from .agents/skills and MCP configs, inventories your AGENTS.md, CLAUDE.md, and GEMINI.md context files into hub.repo-context.json, and adds references for the imported assets to the pig package. Review the result, then move the imported assets into the packages that should own them.

Validate your hub

Before you publish, check that the hub is well formed:

• pig validate checks the configuration, packages, asset support modes, references, and MCP configs, and confirms there are no symlinks or literal secrets.
• pig verify runs the same validation and then fully compiles the hub in a temporary directory, so you see a real build without changing your working tree.

pig validate
pig verify

Once both pass, you are ready to publish and install plugins. For the full command surface, see The pig CLI reference.