Tutorial

Scan your first skill

About ten minutes, no network access needed. By the end you have a capability manifest for a skill directory, a diff between two versions, and an attestation record written to disk.

You need Node.js 20+ and npm.

git clone https://github.com/RavaniRoshan/skillproof.git
cd skillproof
npm install

1. Build the CLI

npm run build

The package is not published to npm yet, so commands run against the built entry point. Everything below uses node packages/cli/dist/index.js; the npx skillproof form does not work until the package is published.

2. Scan a skill directory

node packages/cli/dist/index.js scan ./my-skill base.json

scan takes two positional arguments: the skill directory and the output path. There is no --out flag.

The manifest it writes has one section per capability class — network, exec, filesystem, secrets, agents, mcp — plus a hygiene block for invisible Unicode tags and external URLs.

Status: findings are placeholders

The v0.1 scanner walks markdown files and matches substrings such as curl or token. When it matches, it records a placeholder value rather than the real one, and it does not yet read frontmatter, scripts or MCP configs. Use it to exercise the pipeline, not to audit a skill you intend to install.

3. Diff two versions

Local

node packages/cli/dist/index.js diff base.json head.json

GitHub Actions

- name: Fail on new capabilities
  run: |
    npm ci
    npm run build
    node packages/cli/dist/index.js scan ./skill head.json
    # base.json is the manifest already on record for this skill
    node packages/cli/dist/index.js diff base.json head.json

A removed capability is an improvement and exits 0. A newly added capability class prints under "New capabilities detected" and exits 2 — that is the signal to wire into CI, so skill updates become reviewable like dependency updates. See ledger for the GitHub Action that consumes it.

Status: changed values do not fail yet

A capability whose value changed is listed as added but does not set the exit code, so it will not fail a gate. Only wholly new capability classes block.

4. Attest and verify

node packages/cli/dist/index.js attest base.json
node packages/cli/dist/index.js verify github:org/repo@sha256:9f3e…

attest writes an append-only JSONL record. verify is intended to check a signature and print the manifest without needing permission from anyone.

Status: not signed yet

attest performs no Sigstore signing in v0.1, and verify returns success without checking anything. Treat a green verify as a placeholder until signing lands.

Where to go next

Core concepts

The model behind manifests and diffs — read this before wiring anything into CI.

Explanation

CLI reference

Every command, argument and exit code, including the parts that are still placeholders.

Reference

Evaluations

Catch the skill that quietly stopped working when a new model shipped.

Planned · v0.2

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.

Open in Claude CodeOpen in Cursor Read the agent instructions