Proof, from first scan to install gate.
SkillProof turns a skill directory into a capability record, then diffs it every time the skill changes. These five pages take you from a single local scan to gating installs in CI.
For your agent
Onboard your agent
Paste this prompt into your coding agent. It points at the agent instructions rather than repeating them, so it cannot go stale here.
You are working in the SkillProof repository (github.com/RavaniRoshan/skillproof). Read AGENTS.md before you touch anything: it carries the build and test commands, the conventions, the two invariants that must not be weakened (content addressing beats names; evidence never guarantees safety), and a status section that names every v0.1 stub next to the file that causes it. Then run npm install, npm run build and npx vitest run, and confirm the baseline is green before you change anything.Start here
Getting started
Build the CLI, scan a skill directory and diff two versions. The shortest path to a first manifest.
Core concepts
Why the diff matters more than the manifest, and why records are keyed by content hash instead of name.
CLI reference
Every command, argument and exit code, including what each one does and does not do today.
Evaluations
Baseline-versus-treated runs across pinned models, so a model bump cannot silently degrade a skill.
Ledger
The append-only, content-addressed log of attestations, and how consumers read it without permission.
Read this before you trust a command
v0.1 is a working scaffold. The command surface, the schemas and the read API contract are real; the scanner's findings are placeholders and signing is not wired up yet. Each page states its own status, and the roadmap tracks what is still missing.
Documentation FAQs
Node.js 20 or newer and npm. The CLI is not published to npm yet, so build it from a checkout and invoke the built entry point with node.
Run npm run build at the repository root, then node packages/cli/dist/index.js followed by the command. The published-sounding npx skillproof form does not work, because the package has never been published.
Exit code 2 is the signal for a newly added capability class, which is what a CI gate should fail on. Removed capabilities exit 0, because a smaller surface is an improvement.
Not today. A capability whose value changed is reported in the added list but does not set exit code 2, so it will not fail a gate. That gap is tracked in AGENTS.md and PLAN.md.
Markdown files only, walked recursively. Scripts, hooks and MCP configs are in scope for the design but are not parsed by the v0.1 scanner, so treat the manifest as incomplete by construction.
Wherever you point the second argument. scan takes the skill directory and the output path as two positional arguments — there is no --out flag.
The design is a git repository of append-only JSONL files under ledger/attestations/YYYY/MM/. That directory is not in the repository yet; attest currently writes into your working directory instead.
Not meaningfully yet. verify returns success without checking a signature, so it currently proves nothing. Until signing lands, treat a green verify as a placeholder.
Because it is not a hash yet. computeHash concatenates the file contents instead of digesting them, so the value is unbounded in size. This is a known v0.1 gap, not intended behaviour.
Change it in the Zod schema first, regenerate the OpenAPI contract, then teach the scanner to emit it and add a fixture. The schema is the single source of truth, so never start in the generated files.