Glossary
This page fixes the meaning of every term the rest of the documentation uses. It is grouped by theme rather than alphabetically, so a first-time reader can follow the model from the top; an alphabetical index at the end jumps straight to a single term.
A definition never leans on jargon it has not itself defined. Where a word has more than one common meaning, both are stated and the one this project uses is marked.
Product and mental model
Section titled “Product and mental model”harness
Section titled “harness”Everything that shapes how an AI coding assistant behaves on a repository — its skills, sub-agents, guardrails, context files, plugins, and the external tools it expects. Left to each developer, a team’s harness drifts: no two machines end up configured the same way. agent-rigger exists to make the harness shared, versioned, and reproducible.
agent-rigger
Section titled “agent-rigger”The command-line tool this documentation describes — a “harness package manager” for teams. It
shares, installs, and updates a team’s harness across everyone’s machine from a single source of
truth. It ships as two binaries, agent-rigger and the shorter rigger.
A team’s chosen harness — the standardised selection of artifacts a team agrees to share. In
practice a rig is expressed through a catalog: the packs, entries, and scopes it
declares. Running rigger applies that selection so every member ends up with the same harness.
assistant
Section titled “assistant”An AI coding assistant that agent-rigger targets. Three are recognised: claude (Claude Code),
opencode, and copilot (reserved — no adapter yet, so selecting it fails with a clear error).
The same source artifact is translated to each one’s native format by an adapter.
adapter
Section titled “adapter”The module that translates one canonical artifact into the exact shape a given assistant expects — where the file goes, what format it takes. Adding support for a new assistant means adding an adapter, not rewriting the artifacts.
canonical form
Section titled “canonical form”The single authored shape each artifact exists in before any assistant sees it — the one source an adapter renders into an assistant’s native format at install. Because only this form is authored and versioned, an artifact is never written twice for two assistants. See one source, many assistants.
delegate-first
Section titled “delegate-first”The rule that when an assistant can install an artifact through its own native mechanism, agent-rigger delegates to it rather than copying files by hand. It only does the manual work for what no assistant handles natively.
preset
Section titled “preset”A starting rig an organisation embeds so a fresh machine begins from the team’s defaults instead of an empty setup. A preset can also encode constraints — for example, that git access must go over HTTPS rather than SSH.
Artifacts and natures
Section titled “Artifacts and natures”artifact
Section titled “artifact”The unit agent-rigger installs — one distributable piece of harness configuration. Every artifact has exactly one nature. Dependencies between artifacts are declared in the catalog, never inside the artifact files themselves.
nature
Section titled “nature”The kind of an artifact. There are eight natures, each installed differently: skill, agent, guardrail, context, plugin, mcp, tool, and hook.
A reusable capability packaged in the cross-vendor SKILL.md format (see
agentskills.io). Installed once into the managed store and exposed to
each assistant through a symlink.
agent (sub-agent)
Section titled “agent (sub-agent)”A Claude Code sub-agent definition — a specialised assistant the main one can hand a task to, stored as a Markdown file. Distributed like a skill: a managed store plus a symlink.
Do not confuse agent with AGENTS.md. The agent nature is a sub-agent; AGENTS.md is a
plain instructions file and belongs to the context nature. Same-looking word, unrelated
things.
guardrail
Section titled “guardrail”An enforcement rule that hard-blocks an action. On Claude Code it is a permissions.deny entry in
settings.json; on opencode it is a permission key in opencode.json. Guardrails are the one
thing no assistant plugin can carry on its own, which is why the tool manages them directly.
context
Section titled “context”Advisory instructions or rules that guide the assistant without forcing anything. Its canonical
form is the AGENTS.md file (see agents.md). Because Claude Code reads CLAUDE.md
rather than AGENTS.md, the tool wires the two together — see AGENTS.md bridge.
plugin
Section titled “plugin”An assistant plugin bundling hooks and commands. agent-rigger installs a plugin by delegating to the assistant’s own plugin mechanism (delegate-first).
A declared MCP server for an assistant — see MCP. The server’s config is stored as-is; any secret in it is written as an environment reference, never a literal value.
A third-party command-line program the harness expects to be present (for example gh, glab,
terraform). A tool entry lists how to install it per package manager and a check command to detect it.
Presence checking works today; performing the install itself is not yet delivered.
A command an assistant runs automatically at a lifecycle moment — before a tool call, when a prompt
is submitted, and so on. A hook entry names the event it fires on and a matcher for which
action triggers it. Claude Code defines nine hook events: PreToolUse, PostToolUse,
UserPromptSubmit, Stop, SubagentStop, SessionStart, SessionEnd, Notification,
PreCompact.
AGENTS.md bridge
Section titled “AGENTS.md bridge”The managed block agent-rigger writes into CLAUDE.md so it imports @AGENTS.md. Claude Code does
not read AGENTS.md directly; the bridge lets one context source reach Claude, opencode, and
Copilot alike.
requires
Section titled “requires”The field on a catalog entry that lists other entries which must be installed first. Installing an artifact pulls in the full chain of what it requires.
Catalog
Section titled “Catalog”catalog
Section titled “catalog”The data layer that describes which artifacts exist, what they require, and how they group into packs. It lives in its own git repository and is the only source of artifact content — the tool binary carries none. It is fetched remotely at a given ref.
catalog.json
Section titled “catalog.json”The single file at the root of a catalog, shaped as { meta, entries }. A note on wording: in
the wider ecosystem “manifest” sometimes means this catalog file. In this project “manifest” means
something else (see manifest) — the catalog file is always called catalog.json.
catalog entry
Section titled “catalog entry”One record in catalog.json. It is either an artifact (a single installable thing with a nature)
or a pack (a bundle of other entries). Both kinds share an id, the assistants they target
(targets), and the scopes they support (scopes).
A named catalog entry that groups several artifacts under one id, so a team installs a coherent set in one step (for example a spec-workflow pack bundling its sub-agents and its skill).
The header of a catalog: { name, required, recommended }. name identifies the catalog;
required and recommended are lists of entry ids — see required and
recommended.
catalog source
Section titled “catalog source”One configured name-and-URL pairing in the tool’s config — the thing catalog add registers and
catalog remove deletes. A source points at a catalog (the data layer it fetches);
several sources together produce the effective catalog.
effective catalog
Section titled “effective catalog”The union of every configured catalog’s entries, seen as one. Because two catalogs may reuse the same id, entries in the effective catalog are named with a qualified id.
qualified id
Section titled “qualified id”An artifact id prefixed with its catalog name to keep it unambiguous across catalogs:
<catalog>/<nature>:<name> (for example team/skill:spec-workflow). The bare id on its own is
<nature>:<name> (for example tool:glab).
required
Section titled “required”The word carries three distinct meanings — keep them apart.
meta.required— the catalog author’s floor: entry ids the catalog puts into the install transaction by default.level: "required"on an entry — an importance hint (versus"recommended"), used mostly for tools.secrets[].requiredon an mcp secret — a fail-closed gate: if the secret is never resolved, the install stops rather than proceeding.
recommended
Section titled “recommended”meta.recommended lists entry ids offered pre-selected but easy to opt out of, versus
required’s imposed floor. As an entry level, "recommended" marks an artifact as
helpful rather than strictly needed.
Installation and local state
Section titled “Installation and local state”ad-hoc install
Section titled “ad-hoc install”Installing straight from a git URL or a local path, with no catalog add step in between — a
one-off pull from a source the config does not track. The install is recorded in the
manifest under a derived prefix, but with no
catalog source registered, update has nothing to resolve it against. See
install from a URL or local path.
derived prefix (provenance prefix)
Section titled “derived prefix (provenance prefix)”The catalog-name stand-in an ad-hoc install synthesises from its source (gh-…
for GitHub, glab-… for GitLab, <host>-… otherwise, local-… for a path) and stores in the
manifest as provenance. It plays the catalog-name part of a qualified id so
remove and check can name the artifact, without being a configured
catalog source.
manifest
Section titled “manifest”The local record of what is installed on this machine — the file state.json under
~/.config/agent-rigger/. Each entry keeps the artifact’s id, nature, ref and sha, scope,
install time, the files it wrote, and its applied payload. It is the source of
truth for what is installed here. (This is the project’s meaning of “manifest”; the catalog file
is catalog.json.)
applied payload
Section titled “applied payload”The exact, reversible record of what an install changed — the deny rules it added, the AGENTS.md
content it wrote, the hook it registered. remove replays it in reverse to undo the install offline
and precisely; check verifies it is still in place.
The managed local copy of an installed artifact — the one physical copy each assistant reaches
instead of duplicating it. A skill’s store is a directory under
~/.config/agent-rigger/skills/<name>/ and an agent’s is a single Markdown file under
~/.config/agent-rigger/agents/<name>.md, each exposed through a symlink. Hook scripts
also live in a store — the shared directory ~/.config/agent-rigger/hooks/, into which every hook
script is copied (not symlinked) and from which settings.json runs it.
symlink
Section titled “symlink”A filesystem link that lets an assistant’s own directory point at the single copy in the
store instead of duplicating it. For a skill, ~/.claude/skills/<name> (Claude, user
scope), <cwd>/.claude/skills/<name> (project scope), or ~/.config/opencode/skills/<name>
(opencode) links back to the store. If a symlink cannot be created, a plain copy is made instead.
Where an artifact is installed. user scope is machine-wide (under your home directory, e.g.
~/.claude/); project scope is limited to the current repository (e.g. .claude/, and
AGENTS.md at the repo root). Each artifact declares which scopes it supports; install picks one
with --scope user or --scope project.
plan (dry-run)
Section titled “plan (dry-run)”The preview of exactly what an install or removal would change before anything is written — the files touched, rules merged, blocks added. Nothing is applied until you confirm, so you always see the change first, in the spirit of a Terraform plan.
backup (.bak)
Section titled “backup (.bak)”A byte copy of a file taken before the tool overwrites it, saved alongside it with a
.bak-<timestamp>-<token> suffix (the .bak-* family — never a bare .bak). It is the safety net
that makes a change reversible, so the tool never removes a recent one.
idempotence
Section titled “idempotence”Running the same install twice leaves the same result as running it once — re-applying an already-present artifact changes nothing rather than duplicating it.
adoption
Section titled “adoption”Recording an artifact that is already correctly in place into the manifest so the tool starts tracking it, without reinstalling or overwriting anything. Used by doctor when it finds a conforming artifact the manifest does not yet know about.
run-lock
Section titled “run-lock”A lock the tool holds while it writes, so two runs cannot edit the same configuration file at once. A leftover lock from a crashed run can be inspected and, with confirmation, broken by doctor.
Trust and security
Section titled “Trust and security”untrusted content
Section titled “untrusted content”Everything a remote catalog carries — artifact files, catalog.json, and the check command
strings. It is treated as hostile by default: scanned before it touches disk, never executed before
you confirm, and any symlink inside it is rejected.
scan / scanner
Section titled “scan / scanner”The security check run over fetched content before it is copied into the store, delegated to external tools (gitleaks for secrets, trivy for misconfigurations). Critical findings block the install. The honest limit: it catches leaked secrets and misconfigurations, not a deliberately obfuscated malicious script.
finding
Section titled “finding”A single issue reported by a scan or by doctor. A security finding may block an install; a doctor finding describes something off in the local state and may or may not carry a repair.
fail-closed / fail-open
Section titled “fail-closed / fail-open”Two opposite postures when in doubt. Fail-closed refuses — it blocks the install on a finding, rejects a suspicious symlink. Fail-open lets the action through with a warning. The default is fail-closed on findings; two deliberate exceptions let the install proceed with a warning instead of blocking: both scanners missing (see warn-only), and exactly one scanner missing, where the warning names the absent tool.
warn-only
Section titled “warn-only”The degraded mode used when no scanner tool is installed on the host. Content cannot be scanned, so rather than blocking every install the tool proceeds and warns — a deliberate fail-open, because the scanners are optional dependencies.
consent
Section titled “consent”Explicit, per-item permission the tool asks for before an act that could destroy data or widen what
the assistant is allowed to do.
Two separate mechanisms carry the name. Running a catalog check command is memoized: granted
execution consent is recorded in a ledger (~/.config/agent-rigger/consent.json) keyed by the pair
of the entry id and the exact command, so an unchanged command under the same id is never re-prompted
(changing either the command or the id always re-prompts). Destructive
doctor repairs (deleting a .bak, removing a store, breaking a lock) are the opposite:
they are confirmed per item on every run, never memoized, and never covered by a blanket --yes.
–force
Section titled “–force”The flag that overrides a blocking security finding and installs anyway. It bypasses a fail-closed gate, so it is a deliberate, explicit choice.
Versions and provenance
Section titled “Versions and provenance”provenance
Section titled “provenance”Where an installed artifact came from — the catalog’s name plus the ref and sha it was
fetched at. Every installed artifact is fetched; none is built into the binary.
The version an artifact is fetched at — a git tag, resolved to an exact commit sha. The manifest stores both.
A human-facing git version label, following semver (for example v0.1.3). A ref is
normally a tag.
The exact git commit an artifact was fetched from, resolved from its ref. It pins the content precisely and lets the tool detect drift even when a tag is later moved.
semver
Section titled “semver”Semantic versioning — the MAJOR.MINOR.PATCH scheme catalog releases follow, so a version number
signals the kind of change since the last one.
shallow clone
Section titled “shallow clone”Fetching only the commit needed rather than a repository’s whole history, to keep catalog fetches fast.
A gap between what the manifest records, what is actually on disk, and what the remote holds — the
harness having quietly diverged from its declared state. check and doctor surface it.
Secrets and MCP
Section titled “Secrets and MCP”MCP (Model Context Protocol)
Section titled “MCP (Model Context Protocol)”A protocol for connecting an assistant to external servers that give it extra capabilities. An mcp artifact declares such a server for an assistant.
secret by environment reference (${VAR})
Section titled “secret by environment reference (${VAR})”The rule that a catalog never stores a secret value. Where a secret is needed, the config holds an
environment-variable reference in the exact form ${VAR_NAME} — a literal value is rejected when
the catalog is parsed. The reference is resolved to the real value only at install time, on your
machine.
–secret-env
Section titled “–secret-env”The install flag that tells the tool which environment variable actually holds a declared secret, mapping the catalog’s reference to a real variable on your machine — so the secret value stays out of the catalog and out of any file the tool writes.
Standards and formats
Section titled “Standards and formats”agentskills.io
Section titled “agentskills.io”The cross-vendor standard (Agentic AI Foundation / Linux Foundation) for the SKILL.md format: a
frontmatter name, a required description, and optional fields. It is the native
skill format for opencode and Copilot; Claude Code keys a skill by its folder name.
agents.md
Section titled “agents.md”The cross-agent convention (Linux Foundation) for the AGENTS.md instructions file — free-form
Markdown, no required frontmatter. The canonical form of the context nature.
frontmatter
Section titled “frontmatter”The small metadata block at the top of a Markdown file, between --- fences. In a SKILL.md it
carries the skill’s name, description, and other declared fields.
CLI and environment
Section titled “CLI and environment”RIGGER_HOME
Section titled “RIGGER_HOME”An environment variable that overrides the home directory the tool uses for every user-scope path.
It takes priority over HOME, and is the single seam used to run the tool against an isolated
directory (for example when trying it in a sandbox).
sandbox
Section titled “sandbox”The throwaway environment set up by scripts/sandbox (shipped in the repository) so you can run
real rigger commands without touching your real config or your real projects: a disposable
RIGGER_HOME plus a disposable project directory, both under /tmp, wiped clean
with rigger_reset and torn down with rigger_exit. See
try it in a sandbox.
TTY / non-interactive
Section titled “TTY / non-interactive”A TTY is an interactive terminal where the tool can prompt you. Non-interactive means there is
none — a CI job or a script — where the tool cannot ask questions and instead relies on flags like
--yes, and skips (and reports) any act that would need a confirmation it cannot obtain.
The flag that pre-approves the safe confirmations of a run so it can proceed without prompting, for use in scripts and CI. It never covers a destructive act (see consent).
exit code
Section titled “exit code”The numeric status a command returns so a script can react. Every command returns one of five
codes: 0 (success or a deliberate no-op), 1 (runtime or environment failure), 2 (the command
was wrong), 3 (check or doctor found something), and 130 (interrupted with Ctrl+C). See
exit codes for the authoritative contract.
NO_COLOR
Section titled “NO_COLOR”The standard environment variable that disables coloured output. The tool colours output only on a
real terminal with NO_COLOR unset.
doctor
Section titled “doctor”The diagnostic command. It reads the local state and reports what is off, grouped into six finding
classes: untracked (an artifact on disk the manifest does not track), manifest (a manifest
entry that no longer matches reality), dangling (a link whose target is gone), phantom (a store
directory nothing references), lock (a leftover run-lock), and hygiene (aged
temporary files or backups). With --fix it repairs the safe ones; anything destructive asks for
consent first.
Alphabetical index
Section titled “Alphabetical index”- adapter
- ad-hoc install
- adoption
- agent (sub-agent)
- agent-rigger
- agents.md
- agentskills.io
- AGENTS.md bridge
- applied payload
- artifact
- assistant
- backup (.bak)
- canonical form
- catalog
- catalog entry
- catalog source
- catalog.json
- consent
- context
- delegate-first
- derived prefix (provenance prefix)
- doctor
- drift
- effective catalog
- exit code
- fail-closed / fail-open
- finding
- –force
- frontmatter
- guardrail
- harness
- hook
- idempotence
- manifest
- MCP (Model Context Protocol)
- mcp (nature)
- meta
- nature
- NO_COLOR
- pack
- plan (dry-run)
- plugin
- preset
- provenance
- qualified id
- recommended
- ref
- required
- requires
- rig
- RIGGER_HOME
- run-lock
- sandbox
- scan / scanner
- scope
- secret by environment reference
- –secret-env
- semver
- sha
- shallow clone
- skill
- store
- symlink
- tag
- tool
- TTY / non-interactive
- untrusted content
- warn-only
- –yes