Concepts & glossary
skillsvault has a small, load-bearing vocabulary. These terms are used precisely throughout the docs and the codebase; this page is the canonical definition for each. It mirrors the repo's CONTEXT.md glossary.
One sentence
skillsvault publishes the skills an organisation approves, distributes them to every developer's harness, and enforces the right version at invocation time — with an immutable audit trail.
Core objects
Skill
An Agent Skill as defined by the open agentskills.io specification: a folder containing a required SKILL.md (YAML frontmatter with name + description, plus instructions), optionally bundling scripts/, references/, and assets/. Agents load skills by progressive disclosure (discovery → activation → execution). The format is an open standard, originally authored by Anthropic, and is portable across any skills-compatible agent by design — skillsvault does not invent the format and does not make skills portable; the standard already does. See Authoring & publishing.
Harness
An agentic client/runtime that can load and execute Agent Skills (Claude Code, Codex, Cursor, and others). "Cross-harness" means a skill stored in skillsvault can be consumed by more than one such client. Portability is a property of the open standard, not of skillsvault. The set of harnesses skillsvault can distribute to vs. enforce within differs — see Harness coverage.
Registry
The store of record for skills: versioned, content-addressed (deduplicated), and governed. It differs from a git host because it backs the control plane, not just storage. Skill content is keyed by content_hash, so versions are immutable.
skillsvault-compliant skill
A skill carrying valid skillsvault declared metadata — namespaced identity, version, targets:, intent: — in an skillsvault.json manifest, so the deterministic matcher and policy gate can operate on it. Compliance is the precondition for deterministic governance; non-compliant skills under a managed namespace fall back to namespace-policy halts.
The planes
Control plane
skillsvault's cloud layer — the console and APIs where your organisation authors skills and policies and reviews the audit trail. It is the source of truth, and it is never on the skill-invocation path: it distributes decisions, it doesn't make them at run time.
Data plane
The client side: the skillsvault CLI on each developer machine. It pulls approved skills, holds the signed bundle locally, and runs the gate — evaluating in-process, with no network and no model.
Enforcement scope (cooperative)
Enforcement is cooperative, not adversarial. It depends on (a) the CLI/gate being installed and (b) the harness exposing a hook that can veto skill execution. It prevents the accidental run of a stale or banned skill — the real-world failure mode. It does not stop a user who deliberately uninstalls the gate or sideloads a folder. Cross-harness veto is gated per-harness by whether that harness has a blocking hook (Claude Code does today).
Governance primitives
Skill identity
The primary key is the namespaced name namespace/skill-name (lowercased, matching ^[a-z0-9][a-z0-9-]*/[a-z0-9][a-z0-9-]*$), ideally backed by an embedded manifest. A skill whose name falls under a managed namespace but lacks a valid current manifest is treated as non-compliant (warn/halt) — this catches sideloaded or pre-skillsvault folders by their missing proof of currency.
Policy
A deterministic, governance-authored rule (e.g. namespace:acme → halt, with a reason). Policies are the blocking gate; they must be explainable and appealable. A policy has a matcher_type, a match_value, an action (allow / warn / halt), an optional reason, and a status (draft / active / archived). See Policies.
Matcher
How a skill is mapped to a policy. Priority order, fastest → slowest, first/most-specific considered first:
| Tier | matcher_type | Matches when |
|---|---|---|
| 1 | manifest_id | the invoked skill's embedded manifest id equals the value |
| 2 | namespace | the skill's namespace equals the value |
| 3 | declared_metadata | the skill's targets contain the value (e.g. target:teamleader) |
| 4 | llm_suggested | suggestion only — never auto-blocks; a human ratifies it into a real policy |
There is intentionally no regex and no LLM on the evaluation path. The LLM judge runs at publish time and only suggests manifest_id / declared_metadata policies for a human to ratify.
Bundle
The signed, versioned snapshot of your org's approved skills and active policies that skillsvault sync downloads and the gate reads locally — the manifest of skill → {version, status}, the active policies, the managed namespaces, and the defaults. It is the only thing the gate needs to decide. See the runtime gate.
Audit log
The immutable record: who ran which skill, when, on which machine/harness, the decision (allowed / warned / blocked), and the matched policy. Stored insert-only. It is the highest-value deterministic artifact for compliance buyers and never samples. See Audit log.
Governed seat
The billing-metered unit: a distinct user with an active harness_connection, derived from the fleet rather than self-reported. Plan gates (audit retention, namespace count, SSO) key off the org plan. See Plans & entitlements.