Set up your Instruction Hub
Overview
Section titled “Overview”An Instruction Hub is a Git repository that holds your team’s shared instructions and the plugins that distribute them. Authors edit ordinary Markdown and configuration files, review changes in pull requests, and publish a version that colleagues install in their agents.
This guide creates an Acme hub with a documentation review skill and a bug investigation skill, then validates it as a first release. The hub works without trace analysis. If you already have instructions to consolidate, create the scaffold here, then follow Migrate existing instructions.
To hand this guide to a coding agent, copy this prompt. Set up PIG with a coding agent covers the whole setup.
Create or adopt our Instruction Hub. Followhttps://promptless.ai/docs/governance/get-started/set-up-your-instruction-hub.mdand phase 2 of https://promptless.ai/docs/governance/agent-setup-guide.md
Outcome: a hub that passes `pig validate` and `pig verify`, committed on alocal branch. Scope: hub source files only. Do not configure publishing orinstall plugins.
Inputs (discover these before you ask me):- Hub repository: [existing hub URL or path, or "create a new hub"]- Organization name and marketplace ID: [for example, Acme and acme-instruction-hub]- First skills: [skills to write, or existing instructions to import]
Ask me before you create a remote repository or push. Report the verifiedrelease ID, the files you changed, and anything left for me to do.Before you start
Section titled “Before you start”You need:
- Git and Python 3.11 or later.
- Permission to create a repository on GitHub or GitLab.
- A person to maintain the hub, and a reviewer for each instruction area.
The examples use the organization Acme, the marketplace ID acme-instruction-hub, and the plugin IDs pig, docs, and dev. Replace the organization and repository URL with yours.
Install the toolchain
Section titled “Install the toolchain”Only people who edit or validate hub source need the pig toolchain. Installing a published plugin doesn’t need it. These are macOS and Linux shell commands.
-
Create a dedicated virtual environment and activate it. On Windows, activate it with its
Scripts/Activate.ps1script.Terminal window python3 -m venv ~/.venvs/pigsource ~/.venvs/pig/bin/activate -
Install the toolchain from its public Git repository.
Terminal window python -m pip install "git+https://github.com/Promptless/pig-toolchain.git@main" -
Confirm the installation. The command prints the list of
pigcommands.Terminal window pig --help
Activate this environment again each time you return to authoring.
Create the hub
Section titled “Create the hub”-
Create the repository
Terminal window mkdir acme-instruction-hubcd acme-instruction-hubgit init -b mainpig init --hub . --org Acme \--marketplace-id acme-instruction-hub \--marketplace-name "Acme Instruction Hub" \--version 0.1.0--orgis required. Without--marketplace-idand--marketplace-name,pig initderives both from the organization name. The command writeshub.yaml, createsplugins/pig.yaml, and prepares the asset directories. Keep thepigplugin. The toolchain requires that literal ID and adds the hub’s update skill to its Claude and Codex versions. -
Write your first skills
A skill explains when to use a repeatable task, what to do, and what to return. Start with a small procedure that you can try against real work.
Create the directories:
Terminal window mkdir -p assets/skills/review-docs assets/skills/investigate-bugSave this as
assets/skills/review-docs/SKILL.md:assets/skills/review-docs/SKILL.md ---name: review-docsdescription: >-Use when reviewing a documentation draft or pull request for accuracy,missing steps, or clarity. Return findings with concrete corrections.---# Review documentation## ScopeReview the files or change set the user names. Otherwise, inspect staged,unstaged, and untracked documentation changes. Read the repository's localinstructions and identify the intended reader and the task they must complete.If no documentation is in scope, say so and stop.## Review1. Check factual claims, commands, configuration keys, and examples againstthe implementation or official documentation for the relevant version.Flag unsupported claims; do not make them sound more certain.2. Walk through the reader's task. Check prerequisite access, step order,expected results, and recovery from likely errors.3. Check whether the reader can find, understand, and use the information.Flag vague instructions, undefined terms, buried actions, and repetition.Keep technical terms the audience needs and drop stylistic preferences.4. Run the repository's documented checks and preview the affected pages.Inspect navigation, links, code blocks, and callouts. Do not executeexamples that change production data or infrastructure during a review.## Return findingsPut findings first, ordered by severity: critical issues block the task;important issues cause a wrong action or a material misunderstanding.Each finding needs a file:line location, the affected claim or passage,supporting evidence, the reader impact, and a concrete correction.State which checks ran and what remains unverified. If there are no findings,say so. Return the review without editing or publishing the draft.Save a second skill as
assets/skills/investigate-bug/SKILL.md:assets/skills/investigate-bug/SKILL.md ---name: investigate-bugdescription: >-Use when a bug report, error, or failed request needs a diagnosis.Reproduce the failure, trace the relevant code and logs, and reportthe supported cause and a proposed fix.---# Investigate a bug## ScopeStart with the reported failure and read the repository's local instructions.Keep production access read-only. Use the project's documented tooling forlogs, traces, and database queries, scoped to the affected request or session.Do not retry production jobs, change data, or deploy a fix without approval.## Investigate1. Record expected and actual behavior, the environment and release, thefailing input or request ID, and when the problem began. Ask for missingdetails only when they block the next useful check.2. Reproduce the smallest failing case locally with the existing test ordevelopment setup. Record the command and observed result. If localreproduction is unavailable, anchor the investigation to a specificfailed request and its logs; do not claim it was reproduced.3. Trace the failing operation through the code for the affected release.Correlate logs and stored state by request or session ID and timestamp.Compare a successful case when available. Check recent changes whentheir timing could explain the failure.4. State a candidate cause and the evidence that would confirm or disproveit. Run the smallest check that distinguishes it from other explanations.Separate the original failure from downstream errors; an error messageor a nearby deployment alone does not establish the cause.5. Identify the smallest fix and a regression test for the original failure.Keep diagnosis separate from implementation unless the user requested both.## ReportLead with the cause and its decisive evidence, or state that the cause remainsunconfirmed. Include the reproduction, affected behavior, relevant file:linelocations and log references, and the proposed fix and regression test.Separate observed facts from hypotheses. Name any remaining uncertainty andthe next check that would resolve it. Redact credentials and sensitive data.Keep reusable reference material and helper scripts beside a skill in
references/andscripts/. Use relative links inside the skill so those files remain usable after installation. Keep project-specific build commands and directory conventions in each project’s own instructions. -
Group skills into plugins
A plugin is the unit a teammate installs. Group instructions by the work people do, so a writer can install
docsand a developer can installdev, or both.Create
plugins/docs.yaml:plugins/docs.yaml id: docsname: Acme Docsowners:- docs-teamincludes:- skill:review-docsCreate
plugins/dev.yaml:plugins/dev.yaml id: devname: Acme Devowners:- engineeringincludes:- skill:investigate-bug- skill:review-docsThe
ownersfield records ownership; configure repository review rules separately if you want enforced approvals. Anincludesentry has the formkind:idand must name an asset that exists in the hub.Update
hub.yamlto publish all three plugins:hub.yaml org: Acmemarketplace:id: acme-instruction-hubname: Acme Instruction Hubversion: 0.1.0stable_plugins: [pig, docs, dev]targets: [claude, codex, gemini, cursor]trace_ingestion:enabled: falsemarketplace.ididentifies the catalog, and each plugin has its own literal ID. The compiler adds no organization prefix. Choose stable names, because renaming an installed plugin creates a different identity. If your team installs plugins from several hubs, give your own plugins explicit IDs such asacme-docsso the names stay distinct. The requiredpigID stays as it is.All generated plugins share
version. Publishing advances it when the output changes, so you don’t need to change it for each edit. See Publish and install plugins. -
Check the layout
Compare your hub with this layout:
hub.yaml # Marketplace, version, plugins, and targetsplugins/pig.yaml # Required shared PIG plugindocs.yaml # Documentation team's selectiondev.yaml # Development team's selectionassets/skills/review-docs/SKILL.md # Documentation accuracy and clarity reviewskills/investigate-bug/SKILL.md # Evidence-based bug diagnosisrules/ # Rules with target support metadataagents/ # Specialist agent definitionscommands/ # Agent commandshooks/ # Lifecycle actionsmcps/ # MCP server configurationSkills are the simplest starting point. The toolchain also supports rules, agents, commands, hooks, and MCP configurations. Support for these differs by agent. Check Supported agents before you add an instruction that depends on a particular agent feature.
-
Validate and save your work
Terminal window pig validate --hub .pig verify --hub .git add hub.yaml plugins assetsgit commit -m "Create Acme Instruction Hub"validatechecks the source configuration, references, and asset declarations.verifyalso compiles every stable plugin for every configured target in a temporary directory. It prints a verified release ID and leaves generated files out of your source checkout.If validation reports a missing asset, check both the directory name and the plugin’s
includesentry. If a target doesn’t support an asset, adapt its instructions to a portable skill or declare its target support explicitly. A successful build doesn’t prove that an agent follows the procedure. Test that after installation.
See also
Section titled “See also”- Publish and install plugins, to release the hub and install its plugins in your team’s agents
- Migrate existing instructions, to bring existing skills and agent configuration into the hub
- The pig CLI reference, for every
pigcommand and option - Deploy trace analysis and Enroll your hosts, when you want feedback from real agent sessions