skillpack

A reference implementation of the compiled skill package — a third distribution model for AI-agent skills. An owned artifact: signed, carrying its own license terms, and selectively opaque (readable interface, protected substance). This repo demonstrates the format end to end and shows it interoperating with Imbue vet through vet's own documented extension point.

This is a demonstration of a format, not a product — and not a fork of vet. It bundles no vet code and redistributes none of vet's content. See AGPL & clean-room.

The gap

A coding-agent "skill" whose value is judgment — review heuristics, decision procedures, worked examples — has exactly two ways to reach a user today:

1. Naked source. Ship the method as plain text (a SKILL.md, a guides.toml). Publish it and you lose control of it — it can be copied, forked, or silently lifted.
2. Hosted API. Hide the method behind an endpoint. Now the user rents, owns nothing, and depends on your uptime.

Software has had a third model for decades — the owned artifact: a thing you buy, install, sign, license, and carry between machines. Agent-consumable knowledge never got one. skillpack is a concrete proposal for that third option.

Why vet is the worked example

vet is the cleanest specimen of the gap, and the most honest one to build against: it is a genuinely open, well-loved tool whose entire value is prompt-engineered judgment — a calibrated corpus of code-review guides plus a precision filter. Today that judgment ships as readable Python anyone can copy. vet also already cut the interface/substance seam we need: its issue-code names and guides.toml override schema are the public interface; the guide bodies are the substance. We render a compiled pack straight into that seam.

vet itself should stay open — its community guides, trust, and no-data-collection stance are the point. This repo uses vet as an anatomy lesson and an interop target, not as an argument to close anything. The compiled format is for a different author: the security vendor, regulated-industry team, or domain expert whose review method is the saleable product and who therefore cannot ship it as naked source.

Install

pip install -e ".[dev]"# or: pip install -e .

Quickstart

# 1. Author makes a signing key (provenance) and compiles the example pack.
skillpack keygen --out author.key
skillpack pack examples/secure-review-pack --key author.key --created 2026-06-13 \
--out secure-review.skillpack --custodial-out custodial-keys.json
# 2. Anyone can inspect the OPEN surface — no license, no keys. Discovery and audit still work.
skillpack inspect secure-review.skillpack
# 3. A license holder opens protected substance. The bundled-key class opens on its own; the# custodial class needs the key the author released.
skillpack open secure-review.skillpack insecure_code --accept-license
skillpack open secure-review.skillpack hardcoded_secret --accept-license \
--custodial-keys custodial-keys.json
# 4. Render the pack into vet's guides.toml and let vet consume it.
mkdir -p .vet
skillpack emit-vet-guides secure-review.skillpack --accept-license \
--custodial-keys custodial-keys.json > .vet/guides.toml

See adapters/vet.md for the interop walkthrough.

The three design properties, in code

• Threat-tunable gate — protection is a declared parameter, not a uniform promise. Each class picks a tier: signed (cleartext, integrity-protected), bundled-key (sealed, key rides along — honest obfuscation), or custodial (sealed, key withheld). See policy.py.
• Key-custody spectrum — none → bundled → platform → author. Enforcement strength is bounded by key-custody strength — necessary, not sufficient (runtime integrity, attestation, and output controls matter too). The bundled-key tier is labeled obfuscation in the source, not security. See load.py.
• Representation by class — a package carries the same unit as both a gated verbatim representation and an open, lossy derived representation (a keyword index — no verbatim lines), so an agent can route over a guide it isn't licensed to reproduce. See _derived_representation in pack.py.

These three knobs are set by the author, by hand, per unit, and are kept independent — tests/test_decoupling.py enforces that the access policy and the representation choice never determine key-release.

A lock, not a vault

The honest limits, conceded up front (they are the whole credibility of the idea):

• It cannot prevent capture at first authorized use. A licensed consumer that opens a guide has the cleartext. emit-vet-guides writes that cleartext into guides.toml, because that is the only thing vet can consume — and from there it enters a model prompt in the clear. The protection does its work at the boundary — tamper-evidence, optional provenance pinning (--expect-key), and license acceptance — not after.
• Enforcement strength is bounded by key custody. The bundled-key tier is obfuscation; a determined reader with the file recovers the key. Only custodial custody makes the seal more than a speed bump — and even then, runtime integrity and output controls bound it further.
• For content that must enter the model context, the derived representation buys nothing. Representation-by-class helps only where routing can happen on a lossy view; if the verbatim text has to reach the model to be useful, you are back to relying on the seal and the license.

A lock is routinely defeated and is ubiquitous anyway — because it deters the opportunistic and makes the boundary unambiguous. (The reference loader's access record is in-process and demo-grade; a durable, signed audit trail is future work — see Known limitations.) That is the design claim here. Nothing stronger.

Verifying provenance

A bare signature proves a package is unmodified, not who wrote it — the signer's key travels inside the artifact. To verify authorship, pin the author's key (obtained out of band) with --expect-key:

skillpack inspect pack.skillpack --expect-key <author-public-key-hex>

Without --expect-key the loader reports integrity OK (self-signed); with a matching key it reports provenance VERIFIED. The same flag works on open and emit-vet-guides.

AGPL & clean-room

vet is licensed AGPL-3.0. This project is deliberately arm's-length from it:

• No vet code is imported, vendored, linked, or modified.
• No vet content is redistributed. The adapter emits the guides.tomlschema that vet documents publicly, and references vet's public issue-code names. Addressing a documented data interface is interoperation, not a derivative work.
• All example content in examples/secure-review-pack/ is original, authored here.

skillpack's own code is Apache-2.0 (see LICENSE and NOTICE).

Known limitations

This is a v0.1 reference implementation of a format, and it is deliberate about what it does not yet do:

• Provenance is opt-in, not assumed. A signature alone is self-certifying; authorship is only established when a verifier pins the key (--expect-key). There is no key directory, web of trust, or transparency log here.
• Attribution is durable, not non-repudiable. Each open is timestamped and bound to the artifact digest, and --log (or write_access_log()) persists an append-only JSONL record of what was opened, when, and from which signed package. What it still lacks is a binding to the opener's verified identity (and per-license watermarking, described in the paper) — those need an external identity system.
• Key handling is demo-grade. Signing and custodial keys are written as plaintext hex/JSON (mode 0600). Whoever holds a custodial key can decrypt — that is what custody means — so production use wants a KMS/HSM or an agent that never writes raw keys to disk.
• Canonicalization is JSON sort-keys (JCS-adjacent), not full JCS/RFC 8785. Duplicate keys and floats are rejected, but a hardened format would adopt a standard canonical scheme.
• bundled-key is obfuscation by construction — the key ships with the artifact. It marks a boundary; it does not keep a determined holder out.
• Representation-by-class only helps where routing can act on the lossy view. When the verbatim text must reach the model to be useful, the derived view buys nothing.

Tests

pytest

The paper

This format is defined and motivated in the whitepaper Compiled Skill Packages: a distribution format for protected expert knowledge in agentic systems (preprint, 2026). Preprint link:added on publication.

Status

Reference implementation, v0.1 — built to make the format concrete and to test it against a real consumer. Interfaces will change. Issues and design critique welcome.