How to use workrr trust

1. Certify your artifact

You need: a public GitHub repository, with your artifact in its own folder (the layout standard says where and what to name it). The certifier recognizes:

Step 1: add the workflow

Create .github/workflows/workrr.yml in your repo. Change path to your artifact's folder.

name: workrr-certify
on:
  push:
    branches: [main]   # your default branch: a certificate soon after each merge
    tags: ["v*"]       # and one per release tag, if you tag releases
  workflow_dispatch:

jobs:
  certify:
    permissions:
      contents: read
      id-token: write       # lets Sigstore sign with this run's identity
      attestations: write   # stores the certificate with your repo
    uses: workrr-trust/certify/.github/workflows/certify.yml@v0.1.5
    with:
      path: skills/my-skill

It certifies every push to your default branch (change main if yours is master), every v* release tag, and manual runs. Many repos never tag releases, so the branch trigger is what gets them a certificate.

Several artifacts in one repo? Add one job per artifact, each with its own path, or give each its own workflow file. Both work from @v0.1.5.

Always pin a release tag like @v0.1.5. The tag is part of the signer identity, and verifiers only accept released tags.

Step 2: push, then check the run

Commit and push. In your repo's Actions tab, the workrr-certify run has three jobs: resolve, test, certify. When it's green, the run summary shows workrr certificate issued with your artifact's digest and level.

The certificate is attached to the run as the workrr-certificate artifact (certificate.sigstore.json plus a readable statement.json). It's also stored in your repo's GitHub attestations, and recorded in the public Rekor log.

What you get

A certificate covers the exact bytes of the folder. Change anything and push, and the next run issues a new certificate for the new content.

2. Add a test suite (for Tested)

Put a workrr.json in the artifact folder, naming a command that exits 0 when the artifact behaves as intended:

{ "test": { "command": "node check.cjs" } }

The command runs from the artifact folder, on Ubuntu with Node 24, in a job that has no signing permission. Keep it deterministic and fast (10-minute limit). For a skill, a good test checks its frontmatter, its trigger description and the examples it ships. See the sample skill for a working one.

3. If it isn't certified

The certify job prints NOT CERTIFIED with one line per failure, and nothing is signed. Fix it and push again.

Scan rules (ruleset workrr-scan-v0.1)

warn findings are recorded in the certificate but don't block it. Test locally before pushing:

npx @workrr-trust/certify certify skills/my-skill --run-tests

4. Get listed in the public ledger

The ledger is the public index of workrr certificates. Once your repo is known to it, new certificates are picked up automatically every hour. To get known, either:

• add your owner/repo to sources.txt by pull request, or
• open a Submit a certificate issue with your repo and artifact digest.

Every submission is re-verified before it's indexed, and nothing from your repo is executed. Your certificate is valid either way. The ledger just makes it easy to find.

Show the badge

Once your repo is in the ledger, add the badge to your README. It shows your latest level and links to your certificates on the ledger:

[![workrr certified](https://trust.workrr.ai/badge/OWNER/REPO.svg)](https://trust.workrr.ai/ledger/?repo=OWNER/REPO)

Replace OWNER/REPO with your repo. For a repo with several artifacts, add ?path=skills/my-skill to the badge URL. It reads "not certified" until the ledger has a certificate from your repo. The badge points to the evidence; it isn't the evidence. Anyone can still verify the certificate itself.

5. Use your own policy (optional)

By default the baseline policy applies. To be stricter, commit a policy file and pass its path from the repo root:

{
  "name": "my-team-policy-v1",
  "maxTotalBytes": 1000000,
  "forbiddenExtensions": [".exe", ".dll", ".so", ".dylib", ".bin"],
  "requiredSkillFields": ["name", "description"],
  "allowedTools": ["Read", "Grep"],
  "requireLicense": true
}

    with:
      path: skills/my-skill
      policy: policies/my-team-policy.json

The certificate records the policy's name and a digest of its exact contents, so anyone can see which policy was applied. The name workrr-baseline-v0.1 is reserved for the built-in baseline policy: a custom policy must choose its own name (reusing workrr-baseline-v0.1 with any other digest fails certification and verification, and a non-baseline policy digest reports custom policy, not baseline rather than a baseline level).

6. Verify an artifact before you use it

You need the artifact folder (exactly as published) and its certificate file. Get the certificate from the ledger ("download" on its row), or from the publisher's run:

gh run download <run-id> --repo owner/repo -n workrr-certificate -D cert

Then verify with either implementation (pass --source owner/repo to require that the certificate's publisher repository matches):

# Node 22+
npx @workrr-trust/certify verify ./my-skill --bundle cert/certificate.sigstore.json --source owner/repo

# Go
go install github.com/workrr-trust/certify/go/cmd/workrr@latest
workrr verify ./my-skill --bundle cert/certificate.sigstore.json --source owner/repo

VERIFIED · Tested (silver) means the folder is byte-for-byte what was certified, the signature checks out, Rekor has the record, the signer is the official workrr certifier, the policy digest matches workrr-baseline-v0.1, and (when --source is passed) the publisher repository matches. Any other result means don't trust it. Exit codes: 0 verified, 1 not verified, 2 usage error.

7. Gate it in CI or before loading

Refuse any artifact that doesn't verify. For example, as a CI step that runs before a skill is added to your agents' skill directory:

- name: Only load workrr-certified skills
  run: |
    npx -y @workrr-trust/certify verify vendor/skills/csv-summary \
      --bundle vendor/certs/csv-summary.sigstore.json \
      --source workrr-trust/sample-skills

The step fails, and stops the pipeline, unless the skill verifies. Pin the verifier version so your gate doesn't change underneath you.

8. Help and enterprise

• Questions or bugs: open an issue. For security reports, see SECURITY.md.
• Private repositories and internal artifacts (certification in your own CI, a private registry, policy authoring, audit evidence): book an enterprise briefing or email info@workrr.ai.
• What's not in v0.1 yet: revocation checks, Reproduced certificates, and a signed trust policy. See the limits.