Skip to content

For the complete documentation index, see llms.txt.

Key concepts

Use this glossary while setting up your hub or planning a deployment. How it works connects the terms into a complete workflow.

Your team writes shared instructions in a hub and packages them into plugins that users install:

TermDefinition
Instruction HubA Git repository containing the shared instructions your team maintains for AI agents. It holds authored assets, plugin definitions, and a hub.yaml configuration.
AssetOne unit of source content or configuration in the hub, stored under assets/.
PluginA named group of assets that a user installs.
MarketplaceThe catalog through which supported agents discover your released plugins.

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.

Plugin definitions refer to an asset by its kind and ID, such as skill:review-docs. A hub can contain these kinds of assets:

KindPurposeExample
skillA reusable procedure with a description of when to use itReview a documentation change
ruleGuidance that applies in a defined contextFollow the team’s API terminology
agentInstructions for a specialist roleInvestigate a failed documentation build
commandA named entry point for a taskPrepare release notes
hookAn action tied to an agent lifecycle eventRun a check when a session ends
mcpConfiguration for a Model Context Protocol serverConnect 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.

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: docs
name: Acme Docs
includes:
- skill:review-docs

Acme 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.

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.

The marketplace’s identity belongs to the hub and is separate from individual plugin IDs. Acme’s hub.yaml could contain:

org: Acme
marketplace:
id: acme-instruction-hub
name: Acme Instruction Hub
version: 0.1.0
stable_plugins: [pig, docs, dev]
targets: [claude, codex, cursor, gemini]
trace_ingestion:
enabled: false

The 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.

The pig toolchain compiles the hub into releases that agents install. The trace analyzer has its own releases:

TermDefinition
pigThe command-line tool that scaffolds, validates, scans, and compiles a hub.
TargetAn agent format the toolchain builds: claude, codex, cursor, or gemini.
Hub releaseThe versioned result of compiling the selected plugins for the selected targets.
Analyzer releaseA version of the deployed analysis service. Hub releases and analyzer releases update independently.
Automatic updatesBy default, the trace analyzer updates automatically to stable releases. You can pause updates or pin a release.

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.

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.

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.

When trace ingestion is enabled, each enrolled host collects records of agent sessions for analysis:

TermDefinition
HostAn enrolled agent environment on a workstation or other machine. Its identity lets PIG attribute traces and collection status to the right source.
Host runtimeThe collector, promptless-host-runtime, that the Claude, Codex, and Cursor versions of the pig plugin include when trace_ingestion.enabled is true.
EnrollmentThe browser approval that associates a host with a Promptless organization and analyzer deployment.
Host policyThe configuration that tells the collector which host types and collection settings are enabled.
SessionA period of work recorded by an agent.
TracePIG’s representation of a session, reconstructed from the agent’s native logs. It can include messages, tool activity, timestamps, and other source records.
Canonical traceA trace’s records organized into a common representation for analysis.

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.

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.

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.

The trace analyzer turns sessions into findings, and your team reviews the fixes:

TermDefinition
Trace analyzerThe 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 AnalyzerThe analysis component inside the trace analyzer. It examines completed or quiet sessions using the configured model provider and Instruction Hub context.
FindingAn instruction problem observed in session analysis. It includes an explanation, impact, confidence, and supporting evidence.
Evidence occurrenceThe connection between a finding and a particular session, including what happened there.
RemediationThe work to address a finding.
PromptlessThe service that manages enrollment credentials and deployment coordination, stores findings, and coordinates their GitHub issues and remediation state.

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.

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.

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 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.