Key concepts

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

Instruction Hub

An Instruction Hub is a Git repository containing the shared instructions your team maintains for AI agents. It holds authored assets, plugin definitions, and a hub.yaml configuration. Your team reviews changes in pull requests before publishing them.

A hub is the source of truth for shared guidance. 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

An asset is one unit of source content or configuration in the hub. Assets live under assets/ and use references such as skill:review-docs in plugin definitions.

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; the compiler does not make an unavailable tool or host feature exist. See Supported agents.

Plugins

A plugin is a named group of assets that a user installs. Its source definition lives in plugins/<id>.yaml; 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 have different audiences but share the same authored procedure.

The ID is the plugin’s literal identity. The toolchain does not automatically prefix docs with your organization or marketplace ID. Choose IDs deliberately, especially if users install plugins from several hubs.

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. Other plugins such as docs and dev do not receive those managed collection hooks.

Marketplace

A marketplace is the catalog through which supported agents discover your released plugins. Its identity belongs to the hub and is separate from individual plugin IDs.

Acme’s configuration 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

pig is the command-line tool that scaffolds, validates, scans, and compiles a hub. Its Python package is promptless-instruction-hub; the same CLI is also available under that longer command name.

Authors run it locally, and CI runs it when checking and publishing changes. It is not a server. pig verify checks a build in a temporary directory; pig build writes generated output. Publishing is performed by the CI integration, not by a pig publish command. See the CLI reference.

Targets and releases

A target is an agent format the toolchain builds: claude, codex, cursor, or gemini. A hub release is the versioned result of compiling the selected plugins for the selected targets.

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.

An analyzer release versions the deployed analysis service separately from the hub’s instructions. Updating one does not automatically update the other.

Hosts and the host runtime

A host is an enrolled agent environment on a workstation or other machine. Its identity lets PIG attribute traces and collection status to the right source.

The host runtime, promptless-host-runtime, is the collector included in Claude and Codex versions of the pig plugin when trace_ingestion.enabled is true. Generated lifecycle hooks start collection work without blocking the agent session.

Native trace sources are Claude Code, Claude Desktop, and Codex. Plugin-distribution support for Cursor or Gemini does not mean PIG collects their native traces.

Enrollment and policy

Enrollment is the browser approval that associates a host with a Promptless organization and analyzer deployment. A signed-in organization member approves the request. The host receives its own credential, which it uses for authenticated requests to the analyzer.

The host policy tells the collector which host types and collection settings are enabled. Installing a plugin, enabling collection in hub.yaml, and enrolling a host are separate steps. See Enroll your hosts.

Traces and sessions

A session is a period of work recorded by an agent. A trace is PIG’s representation of that session, reconstructed from the agent’s native logs. It can include messages, tool activity, timestamps, and other source records.

Raw uploads preserve the original records. The canonical trace organizes those records into a common representation for analysis. PostgreSQL records ingestion and analysis state; your trace bucket holds raw chunks and trace objects. See Trace object and sources.

The worker and Friction Analyzer

The trace analyzer is the customer-deployed pig-trace-analyzer service. It accepts authenticated uploads, stores trace data, runs analysis, and coordinates results with Promptless.

The Friction Analyzer is the analysis component inside that service. It examines completed or quiet sessions using the configured model provider and instruction-hub context. There is no separate Friction Analyzer installation.

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

A finding describes an instruction problem observed in session analysis. It includes an explanation, impact, confidence, and supporting evidence. An evidence occurrence connects the finding to a particular session and what happened there.

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

Remediation is the work to address a finding. 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.

A finding may need a change to a tool, integration, or external system instead of a hub edit. See Remediate findings.

Promptless

Promptless manages enrollment credentials and deployment coordination, stores findings, and coordinates their GitHub issues and remediation state.

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

Automatic updates

The trace analyzer updates automatically to stable releases by default. You can pause updates or pin a release. 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.