skillproof

The open trust manifest for AI-agent skills. Zero dependencies.

A skill you download is code + instructions that will run inside your agent — and about 1 in 4 community skills carries a vulnerability. The ecosystem's answer is "verify, then install, then constrain." But trust dies at every boundary: a skill verified in one catalog arrives in your harness as an unlabeled blob.

skillproof is a small, signed sidecar (skill.proof.json) that travels with a skill and attests four things a consumer needs before trusting it:

• provenance — who authored or derived it, from what (incl. the attested episodes a learned skill was distilled from);
• capabilities — the least-privilege scope it may exercise (action + resource);
• verification — which gates it passed, the reproducible evidence, and the resulting trust tier (T1–T4);
• integrity — a content hash + detached signature, checkable offline; any edit voids the proof.

skillproof attest ./my-skill --sign ed25519 --key key.pem   # bind provenance + caps + sign
skillproof verify ./my-skill                                # run static + conformance gates, derive tier
skillproof gate   ./my-skill --min-tier T3                  # verify-then-install, in one line (exit 2 to block)

A format and a verifier, not a runtime. skillproof doesn't replace your harness's approval gate or sandbox — it produces the portable attestation your gate consumes. It runs the checks it can prove with zero dependencies (static scan + capability conformance) and standardizes the evidence envelope for the gates that need an LLM or a sandbox.

And after a run, skillproof audit confirms the skill behaved inside its envelope — every side-effect was approved and within the declared capabilities (the resource-precision check static analysis can't do):

skillproof audit ./my-skill run-log.jsonl   # exit 2 if any effect was out-of-scope or unapproved

Enforce it in Claude Code

Wire skillproof hook as a skill-load gate so the harness enforces verify-then-install. Fail-safe (any error exits 0, never wedges a session) and advisory by default — set SKILLPROOF_ENFORCE=1 to actually block:

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Skill", "hooks": [ { "type": "command", "command": "skillproof hook" } ] }
    ]
  }
}

See SPEC.md for the format and vision.md for the why.

Part of an open, dependency-free family of agent-infrastructure formats (capgrant, provenant, truecall, skillbridge, constraintguard, …).

Status: v0.2 — attest / verify / gate / tier / audit / hook. G1 (static scan) + G4 (capability conformance) run zero-dep; the biconditional audit does the runtime side-effect check; the Claude Code hook enforces verify-then-install. HMAC + ed25519 signing. 23 passing tests, zero runtime dependencies. Run them: npm test.

License

MIT © Abhi Das