Key concepts
Use this glossary while setting up your hub or planning a deployment. How it works connects the terms into a complete workflow.
Hub content
Section titled “Hub content”Your team writes shared instructions in a hub and packages them into plugins that users install:
| Term | Definition |
|---|---|
| Instruction Hub | A Git repository containing the shared instructions your team maintains for AI agents. It holds authored assets, plugin definitions, and a hub.yaml configuration. |
| Asset | One unit of source content or configuration in the hub, stored under assets/. |
| Plugin | A named group of assets that a user installs. |
| Marketplace | The catalog through which supported agents discover your released plugins. |
Instruction Hub
Section titled “Instruction Hub”A hub is the source of truth for shared guidance. Your team reviews changes in pull requests before publishing them. Keep project context in each repository’s AGENTS.md or CLAUDE.md, and move reusable procedures into shared assets.
For example, Acme’s hub contains one documentation-review skill used by both its writers and developers.
Assets
Section titled “Assets”Plugin definitions refer to an asset by its kind and ID, such as skill:review-docs. A hub can contain these kinds of assets:
| Kind | Purpose | Example |
|---|---|---|
skill | A reusable procedure with a description of when to use it | Review a documentation change |
rule | Guidance that applies in a defined context | Follow the team’s API terminology |
agent | Instructions for a specialist role | Investigate a failed documentation build |
command | A named entry point for a task | Prepare release notes |
hook | An action tied to an agent lifecycle event | Run a check when a session ends |
mcp | Configuration for a Model Context Protocol server | Connect to a documentation search service |
A skill normally contains SKILL.md and can include supporting references, templates, or scripts. Asset metadata describes target support. Native formats and supported conversions vary by agent, and a compiled asset can use only the tools and host features the target agent provides. See Supported agents.
Plugins
Section titled “Plugins”A plugin’s source definition lives in plugins/<id>.yaml, and its compiled output lives in dist/<target>/<id>/. For example, plugins/docs.yaml can select the documentation skill:
id: docsname: Acme Docsincludes: - skill:review-docsAcme can also include that asset in plugins/dev.yaml. The two plugins serve different audiences and share the same authored procedure.
The ID is the plugin’s literal identity: the toolchain uses docs exactly as written, without adding your organization or marketplace ID. Choose IDs deliberately, especially if users install plugins from several hubs.
The required pig plugin
Section titled “The required pig plugin”Every hub includes a plugin with the exact ID pig, listed in stable_plugins. It can contain shared instruction assets, including those added by pig scan.
The toolchain adds the managed update-instruction-hub skill to this plugin for Claude and Codex. When trace ingestion is enabled, this same plugin receives the managed enrollment hooks and collection runtime. Plugins such as docs and dev don’t receive those managed hooks or the collection runtime.
Marketplace
Section titled “Marketplace”The marketplace’s identity belongs to the hub and is separate from individual plugin IDs. Acme’s hub.yaml could contain:
org: Acmemarketplace: id: acme-instruction-hub name: Acme Instruction Hubversion: 0.1.0stable_plugins: [pig, docs, dev]targets: [claude, codex, cursor, gemini]trace_ingestion: enabled: falseThe example assumes matching definitions for all three plugins. The generated catalog and installation process depend on the agent; Gemini uses extensions. See Publish and install plugins.
Builds, releases, and updates
Section titled “Builds, releases, and updates”The pig toolchain compiles the hub into releases that agents install. The trace analyzer has its own releases:
| Term | Definition |
|---|---|
pig | The command-line tool that scaffolds, validates, scans, and compiles a hub. |
| Target | An agent format the toolchain builds: claude, codex, cursor, or gemini. |
| Hub release | The versioned result of compiling the selected plugins for the selected targets. |
| Analyzer release | A version of the deployed analysis service. Hub releases and analyzer releases update independently. |
| Automatic updates | By default, the trace analyzer updates automatically to stable releases. You can pause updates or pin a release. |
The pig toolchain
Section titled “The pig toolchain”The pig Python package is promptless-instruction-hub, and the same CLI is also available under that longer command name.
Authors run pig locally, and CI runs it when checking and publishing changes. pig verify checks a build in a temporary directory, and pig build writes generated output. The CI integration publishes releases. See the CLI reference.
Targets and releases
Section titled “Targets and releases”version in hub.yaml is the hub’s semantic version. The release pipeline writes release metadata to hub.release.json and the stable pointer to hub.stable.json.
A published release and an installed plugin are different states. Users must install or refresh the plugin before an agent can load the new content.
Automatic updates
Section titled “Automatic updates”Updates coordinate the analyzer, database migrations, and dedicated PIG resources within the permissions your platform team grants. Shared clusters and networking remain under your team’s control. See Manage updates and recovery.
Hosts and trace collection
Section titled “Hosts and trace collection”When trace ingestion is enabled, each enrolled host collects records of agent sessions for analysis:
| Term | Definition |
|---|---|
| Host | An enrolled agent environment on a workstation or other machine. Its identity lets PIG attribute traces and collection status to the right source. |
| Host runtime | The collector, promptless-host-runtime, that the Claude, Codex, and Cursor versions of the pig plugin include when trace_ingestion.enabled is true. |
| Enrollment | The browser approval that associates a host with a Promptless organization and analyzer deployment. |
| Host policy | The configuration that tells the collector which host types and collection settings are enabled. |
| Session | A period of work recorded by an agent. |
| Trace | PIG’s representation of a session, reconstructed from the agent’s native logs. It can include messages, tool activity, timestamps, and other source records. |
| Canonical trace | A trace’s records organized into a common representation for analysis. |
Hosts and the host runtime
Section titled “Hosts and the host runtime”Generated lifecycle hooks start collection work without blocking the agent session.
Native trace sources are Claude Code, Claude Desktop, Codex, and Cursor. Cursor collection needs analyzer 0.3.3 or later. PIG distributes plugins to Gemini but doesn’t collect Gemini’s native traces.
Enrollment and policy
Section titled “Enrollment and policy”A signed-in organization member approves each enrollment request. The host receives its own credential, which it uses for authenticated requests to the analyzer.
Installing a plugin, enabling collection in hub.yaml, and enrolling a host are separate steps. See Enroll your hosts.
Traces and sessions
Section titled “Traces and sessions”Raw uploads preserve a trace’s original records. PostgreSQL records ingestion and analysis state, and your trace bucket holds raw chunks and trace objects. See Trace object and sources.
Analysis and remediation
Section titled “Analysis and remediation”The trace analyzer turns sessions into findings, and your team reviews the fixes:
| Term | Definition |
|---|---|
| Trace analyzer | The customer-deployed pig-trace-analyzer service, also called the worker. It accepts authenticated uploads, stores trace data, runs analysis, and coordinates results with Promptless. |
| Friction Analyzer | The analysis component inside the trace analyzer. It examines completed or quiet sessions using the configured model provider and Instruction Hub context. |
| Finding | An instruction problem observed in session analysis. It includes an explanation, impact, confidence, and supporting evidence. |
| Evidence occurrence | The connection between a finding and a particular session, including what happened there. |
| Remediation | The work to address a finding. |
| Promptless | The service that manages enrollment credentials and deployment coordination, stores findings, and coordinates their GitHub issues and remediation state. |
The worker and Friction Analyzer
Section titled “The worker and Friction Analyzer”The Friction Analyzer runs inside the trace analyzer, so you deploy only the trace analyzer.
The service requires PostgreSQL and native object storage (S3, Azure Blob Storage, or Google Cloud Storage). Analysis also requires model configuration and a verified GitHub hub repository with a main branch. See Plan your deployment.
Findings and evidence
Section titled “Findings and evidence”Multiple sessions can support the same finding. Evidence helps a reviewer distinguish a recurring instruction problem from an isolated mistake. A session may complete analysis without producing a finding. See Understand findings.
Remediation
Section titled “Remediation”When an instruction change is appropriate, PIG can prepare a pull request against your hub. Your team reviews the proposed fix and uses its normal checks and merge controls before publishing it.
Some findings need a change to a tool, integration, or external system outside the hub. See Remediate findings.
Promptless
Section titled “Promptless”Promptless trace-status records exclude raw transcripts. Findings are a separate data flow and can describe session details. Analysis also sends session-derived input to your configured model provider. See Trust and data model.