Skip to content

dot-skill/skillerr

BranchesTags

Repository files navigation

Open .skill Protocol

Skillerr .skill mark

The cryptographic trust standard for AI skills.

Package a skill once as a sealed .skill: content-addressed, cryptographically signed, and independently verifiable before anyone runs it. A Sigstore-grade trust ladder carries a skill from local development to a publicly anchored proof of authorship, on a neutral foundation built to outlast any single tool, host, or marketplace.

Create, inspect, sign, and run portable .skill packages for AI agents, the integrity and provenance layer on top of your SKILL.md.

npm i -g skillerr

Site: skillerr.com · Format: .skill (sealed ZIP) · Reference CLI: skillerr (skill) · Repo: dot-skill/skillerr

npm License: MIT Node.js Protocol Tests

Contributing: see CONTRIBUTING.md for the DCO/PR checklist, or jump straight to a scoped task in docs/GOOD-FIRST-ISSUES.md.

Cryptographic foundation

A skill is only as trustworthy as your ability to verify it. .skill gives every skill a verifiable identity, provable authorship, and independently checkable provenance, the same guarantees the software supply chain now expects, applied to AI skills.

  • Identity, content-addressed. Every skill has a content-derived skill_id and SHA-256 package_digest/manifest_digest. Change one byte after sealing and the identity changes; tampering is detectable by math, not trust.
  • Authorship, cryptographically signed. Seal with a configured Ed25519 issuer key (verified_issuer), or bind the seal to an OIDC identity with Sigstore Fulcio keyless signing (skill mint --keyless). Attestations use the standard DSSE envelope, the same primitives cosign and npm provenance rely on.
  • Provenance, publicly anchored. Anchor the sealed digest to the public Sigstore Rekor transparency log (skill mint --transparency). Inclusion is verified against the log's signed tree head offline by default (--online re-checks live), and every verified anchor prints a search.sigstore.dev link so a third party can confirm it without trusting this tool's word.
  • Assurance you can't fake. skill inspect --trust --claims / skill verify-trust --claims split every field into verified (crypto-checked) and self_reported (asserted), two separate arrays, so a self-reported claim can never be shown as verified. A seal proves who issued a package and that it hasn't changed, never that a skill is correct, safe, or good. See What is verifiable.

The trust ladder

Rung How it's sealed What a verifier gets
Development Public dev HMAC key (default, zero setup) Local iteration only. Forgeable by design, labeled development everywhere it appears, never production trust.
Verified issuer Configured Ed25519 key (skill keygen + --signer-key) Cryptographic proof of authorship and integrity, once a verifier pins your key in their trust store.
Publicly anchored Rekor transparency log (--transparency) and/or Fulcio keyless OIDC (--keyless) A public, independently-checkable record, anyone can confirm the entry on Sigstore's own infrastructure.

Anchoring is orthogonal to trust state and always additive, an anchored package can still be development or self_reported; the anchor never replaces the seal. Inclusion is not endorsement: logging a package proves auditability, not goodness. See docs/TRUST-MODEL.md.

Built to be verified today, and owned tomorrow

The primitives that make a .skill verifiable are, by design, a foundation a future ownership layer could build on: on-chain provenance, programmable royalties for skill authors, decentralized skill marketplaces. This is deliberate architecture, not a promise of features:

  • Content-addressed identity. A skill already has a unique, tamper-evident id and digest, the same reference primitive on-chain assets use to point at off-chain content.
  • Cryptographic authorship. Skills are already signed by Ed25519 issuer keys and, optionally, bound to an OIDC identity via Sigstore Fulcio, key-based identity that maps cleanly onto wallet-based identity.
  • Pluggable anchors. PermanenceAnchor is an open extension point. The wire format already reserves kind: "ledger" as a valid anchor kind alongside the shipped transparency_log/keyless_identity/registry kinds; no ledger-anchoring implementation exists yet, it's a tracked roadmap item, addable without breaking a single existing package.
  • A neutral core. Economics live above the protocol, never inside it. The spec has no marketplace, no token, and no commerce code, so any ownership or settlement layer could build on the verifiable foundation without the standard picking winners.

What this is not, today: skillerr does not mint tokens, issue NFTs, or move value. "Minting" a .skill creates a cryptographic attestation, not a financial instrument. On-chain ownership is a roadmap extension point, not a shipped feature, and it will always be optional, never required to author, verify, or run a skill. Nothing here is investment advice or a claim of future value. See docs/CRYPTO-FOUNDATION.md for the full breakdown.

Where skillerr fits

The Agent Skills ecosystem has three layers. skillerr owns the third, and is complementary to the other two, not a competitor to either:

Layer What it does Who does it
Authoring Defines the SKILL.md format itself: frontmatter, body, scripts//references/assets/ The Agent Skills spec
Distribution Installers and directories that get a skill onto your machine vercel-labs/skills (npx skills add owner/repo), skills.sh
Trust / integrity Seals, signs, records provenance, and lets you inspect a skill before you run it skillerr

The concrete gap this closes: npx skills add owner/repo installs unverified instructions and executable scripts from any repo, with no integrity or provenance check built in. skillerr adds the missing step: inspect and verify a skill before you run it, not after.

Agent Skills / SKILL.md is the open authoring format. .skill is a sealed, signed package of one. .skill doesn't replace your SKILL.md, skill ingest reads a standard Agent Skills folder and wraps it in a typed contract, an integrity seal, and provenance, so the same skill keeps working everywhere Agent Skills are supported, and gains inspect-before-run trust on top.

Distribution tools install a skill; skillerr lets you verify one, its integrity, issuer, and provenance, before you run it.

No telemetry, no tracking. skillerr makes no network calls unless you explicitly ask it to (--transparency, --keyless, --online, all opt-in). Nothing about what skills you create, ingest, or run is ever reported anywhere.

Convert your SKILL.md in one line

Already have a SKILL.md or a skill-creator folder? .skill isn't a competing format — it's the integrity layer on top. One command upgrades it, and it never claims completeness it can't back up. Paste this to your agent — it names every command literally, nothing to guess:

Run these exact commands in your terminal, in order:

1. npm i -g skillerr          (skip if `skill --version` already works)
2. export SKILL_HOST=cursor   (replace "cursor" with your actual tool name —
                                claude-code, codex, ollama, etc.)
3. skill ingest ./SKILL.md    (adjust the path if your SKILL.md lives elsewhere)

Then show me the output path and exactly what's still missing before it can be
a release. Don't invent contract fields to make it look more complete than it is.

See docs/FAQ.md.

What a sealed .skill gives you that a bare SKILL.md can't

Bare SKILL.md Sealed .skill
Structure Freeform prose Typed contract: intent, triggers, inputs/outputs, ordered steps, capabilities, permissions, verification
Integrity None Content-addressed skill_id + SHA-256 package_digest/manifest_digest — any edit after packing is detectable
Trust before run None Inspect seal/issuer/digests without executing (skill inspect --trust); untrusted/development/self_reported/verified_issuer states, never blurred together
Quality evidence None Native eval/benchmark loop + an optional sealed score receipt (skill eval, skill score) — see docs/EVAL.md
Handoff Copy the chat Continuity draft — a real AI↔AI handoff object, partial-OK, privacy-scrubbed
Authenticity path None Optional public transparency-log anchoring (skill mint --transparency, built on the official sigstore/Rekor stack) plus a local transparency log (skill registry) — never a required dependency, see docs/TRANSPARENCY.md

Markdown remains a lossy adapter only — not the protocol. Full comparison: docs/WHY.md.

Install once

npm i -g skillerr

Node ≥ 20. One-shot: npx -y skillerr --help. After that, you do not drive a CLI checklist — you point your AI at skillerr.

Talk to your AI

Paste prompts like these into Cursor, ChatGPT, Claude, Codex, or any agent that can run shell tools. The two prompts above (convert / create) spell out the install + SKILL_HOST steps explicitly since they're usually the first thing you paste. The prompts below assume you already ran those two steps once in this environment — if skill --version fails, run npm i -g skillerr and export SKILL_HOST=<your-tool-name> first.

New to the vocabulary the prompts use? "Journey" is the redacted record of what you and the agent did; "checkpoint" is a partial, in-progress save (continuity draft); "release-complete" means every required contract field is filled in and human-reviewed, not just "looks done." The output either way is a sealed .skill file, not a chat export.

Create a skill from this chat

Run these exact commands in your terminal, in order:

1. npm i -g skillerr          (skip if `skill --version` already works)
2. export SKILL_HOST=cursor   (replace "cursor" with your actual tool name —
                                claude-code, codex, ollama, etc.)

Then, from this conversation, create a portable .skill: redacted journey, exact
sections I approved (secrets only as {{refs}}), then either checkpoint for
handoff or compile --approve --mint when release-complete. Do not invent filler.
Show me status and the output path.

Starting from a blank page instead of a chat you want to seal? Point your agent at examples/skillerr-authoring/SKILL.md — it's the interview → contract → review → mint front door, written so an agent can follow it without hand-writing the contract JSON.

Inspect before you trust or run

I have a file at ./file.skill. Inspect TrustView (digests, seals) without executing.
Validate integrity, then dry-run. Summarize what it does and any trust warnings.
Do not execute for real unless I explicitly ask.

Extract multiple skills from a journey

Using skillerr, run agent-guide then extract from ./journey.json into ./extraction.
For each candidate I select, open its own workspace, fill missing contract fields,
and only compile a release when complete — otherwise checkpoint. Prefer exact text.

Load a continuity handoff

Load ./handoff.skill as continuity context. Summarize intent, scrubbed journey,
open gaps, and pinned knowledge. Resume the work; do not mint a fake release.

Hand off mid-work to another agent

Checkpoint the current .skill workspace as a continuity draft (partial OK).
Tell me the output path and what the next agent should load.

More copy-paste prompts: examples/prompts.md. Agent contract: docs/AGENT.md.

What your agent will do

Commands below are what the agent runs — not a human homework list.

Goal What the agent runs
Create workspace skill init → journey → propose → status
Convert an existing SKILL.md skill ingest <path>
Mid-work handoff skill checkpoint
Release when complete skill compile -m "…" --approve --mint
Production issuer identity skill keygen → skill mint --signer-key … for verified_issuer trust
Publicly anchor authorship skill mint --transparency (Rekor) and/or --keyless (Fulcio OIDC)
Trust before run skill inspect --trust --claims → validate → verify-trust --claims → run (dry-run)
Resume handoff skill load ./file.skill

Creation requires a declared agent host (SKILL_HOST=cursor|ollama|claude|…). Humans review and approve releases. Declared host/model fields are self-reported provenance, not cryptographic proof of authorship.

What good looks like

  • Inspect first — digests and seals without executing (skill inspect --trust)
  • Validate structure and hash integrity
  • Dry-run before execute
  • Continuity drafts may be incomplete; release compile refuses incomplete contracts (compile_refused)
  • Real cryptographic identity in production: skill keygen + --signer-key mints with a configured Ed25519 issuer key as verified_issuer — the bundled zero-setup key (used when no --signer-key is given) is for trying the CLI, not for shipping. See Key Ceremony

See docs/SECURITY.md.

Continuity draft Release skill
Purpose AI↔AI work handoff Reusable sealed procedure
Incomplete? Allowed (lists gaps) compile_refused
Mint? No Yes

Agent hosts and provenance

Set SKILL_HOST to the agent recording the skill, any string, self-reported unless a configured issuer key plus real agent-runtime evidence bind it as verified_issuer (see What is verifiable). Commonly seen values, not an exhaustive or gated list:

SKILL_HOST Notes
cursor, claude-code, codex IDE / coding-agent hosts
ollama, lmstudio, llama.cpp Local/offline model runtimes
custom (or any other name) Anything else, human/cli/shell/manual are the only denylisted values

Exporting a sealed .skill back into an agent's own skill directory (.claude/skills/, .cursor/skills/, .agents/skills/, …) is on the roadmap, not shipped yet, skill to-skill-md today produces a single lossy markdown file, not an installable folder.

What’s in a .skill

example.skill
├── skill.json         # manifest, digests, profile, completeness
├── workflow.json      # runnable steps
├── knowledge/         # pinned decisions / rules
├── prompts/           # versioned prompt templates
├── resources/         # bundled scripts, reference material
├── artifacts/         # generated outputs
├── assets/icon.*      # optional per-skill icon (format mark otherwise)
├── provenance/        # journey, usage, compile report, optional eval + score
└── signatures/        # mint attestation, optional anchors

Full package layout spec: docs/PROTOCOL.md.

Status

Specification: 1.0.0 (Stable) (docs/PROTOCOL.md) — future changes go through the open RFC process, not silent revisions.
Reference CLI: skillerr @ 1.2.0, a stable public API backed by 189 tests passing on every push (mac/Linux/Windows × Node 22/24), including an adversarial security corpus and a live-tested transparency-log integration.
Independent conforming implementations welcome.

Why the foundation is future-proof:

  • The format is protocol-defined, not tied to this CLI — any conforming implementation can read/write it (see RFCs for how the spec evolves in the open)
  • The PermanenceAnchor slot (skill registry, --transparency, --keyless) is an open extension point, not a required dependency: the wire format already reserves a ledger anchor kind alongside the shipped ones, so new anchor kinds can be added later without breaking existing packages
  • Trust states are explicit and versioned in the manifest, so a package minted today stays verifiable under future trust-store/issuer/anchor changes instead of silently degrading

Packages

Package Purpose
skillerr Reference CLI — bins skill / skillerr
@skillerr/cli CLI implementation
@skillerr/protocol SkillContract, SkillSource, types
@skillerr/core Compile, pack, validate, mint
@skillerr/runtime Inspect / dry-run / execute
@skillerr/workspace Local .skill/ working tree
@skillerr/registry Optional local transparency log

Host authors typically integrate the protocol libraries; end users install skillerr and talk to their agent.

Documentation

Before you run someone else's .skill file, read What is verifiable. It states plainly what a signature does and doesn't prove — most trust confusion comes from skipping this.

Agent Skills ecosystem: Agent Skills specification (the authoring format) · vercel-labs/skills (npx skills add, distribution) · skills.sh (directory) · Claude Code skills docs

Contributing

Independent runtimes, language ports, adapters, and adversarial fixtures make this real — see the second-runtime call in CONTRIBUTING.md.

License

MIT — Copyright (c) 2026 Bharat Dudeja

About

Open .skill Protocol — a sealed, inspectable package format for AI agent skills. Reference implementation: skillerr.

www.skillerr.com/docs/

Topics

cli open-source skill mcp protocol agents ai-agents ai-skills dot-skill skillerr

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases 22

v1.1.0 Latest
Jul 15, 2026
+ 21 releases

Packages

 
 
 

Contributors

Languages