{
  "markdown": "[![Validate bundle](https://github.com/snapsynapse/skill-provenance/actions/workflows/validate.yml/badge.svg)](https://github.com/snapsynapse/skill-provenance/actions/workflows/validate.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/snapsynapse/skill-provenance/blob/main/LICENSE)\n[![Stable bundle](https://img.shields.io/github/v/tag/snapsynapse/skill-provenance?filter=v%2A&label=bundle)](https://github.com/snapsynapse/skill-provenance/releases/tag/v6.2.0)\n[![GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-Skill%20Provenance%20Validate-blue)](https://github.com/marketplace/actions/skill-provenance-validate)\n\n# Skill Provenance\n\nPortable provenance, integrity, and drift control for Agent Skills across\nlocal folders, registries, platform uploads, and multi-agent sessions.\n\n## Who this is for\n\nTeams that build, distribute, or run Agent Skills across multiple surfaces and need to know a bundle is the version they trust and hasn't silently drifted.\n\n## What problem it solves\n\nAgent Skills move across local folders, registries, and platform uploads with no portable way to verify version, integrity, or drift. Skill Provenance makes a bundle's identity and integrity travel with it.\n\nA public registry-diff observation dated 2026-08-27 reported that 169 of\n1,193 Agent Skill instruction-text changes, or 14.2 percent, had no version\nmovement. This is a dated third-party observation, not a live metric. It is\nevidence for making the digest load-bearing while keeping semver as a useful\nrelease label. See the [evidence note](docs/state-of-skill-versioning-2026.md).\n\n## Canonical URL\n\nhttps://skillprovenance.dev/\n\n```\nBefore                              After\n------                              -----\nSKILL_v4.md                         SKILL.md          (version lives inside)\nSKILL_v5.md                         MANIFEST.yaml     (what's in the bundle)\nevals_old.json                      CHANGELOG.md      (what changed and why)\nevals.json\n\"which one is current?\"             \"bundle is at 4.8.0, evals are stale\"\n```\n\nAgent Skills move between sessions, surfaces, and platforms. Every\nboundary crossing is a chance for version confusion, silent drift, or\nmodified bundle contents that no one can verify. Skill Provenance keeps\nversion identity, staleness detection, and hash-based integrity\nverification *inside the bundle* so it survives every transition.\n\n**For authors:** Know what version you're working on, what's stale, and\nwhat changed — across Chat, Code, Cowork, API, and non-Claude platforms.\n\n**For teams:** Know which copy is current when the same skill is installed\nin five places across three platforms.\n\n**For trust:** Verify that a downloaded or shared bundle matches its\nrecorded state before installing it. SHA-256 hashes in the manifest\ncatch tampering and accidental drift alike.\n\n## Why this still exists\n\nMost ecosystem tools track source, registry, install, or deployment state.\nSkill Provenance tracks the actual multi-file bundle an agent is editing.\nThat matters when `SKILL.md`, evals, scripts, packages, and deployed\ncopies can drift independently.\n\nIt is the author-side layer that complements package managers, registries,\nand platform APIs:\n\n| Approach | Tracks versions | Detects staleness | Cross-session | Cross-platform | Integrity |\n|---|---|---|---|---|---|\n| **GitHub `gh skill`** | Source/ref/tree | No | Repo-bound | Partial | Source pinning |\n| **ClawHub / registries** | Registry versions | No | Consumer package | Partial | Install trust |\n| **Claude Skills API** (`/v1/skills`) | Platform versions | No | Single surface | No | Deployment record |\n| **Filename suffixes** (`_v5`) | Poorly | No | No | No | No |\n| **Skillman** | Pins versions | No | Consumer-side only | No | No |\n| **Skill Provenance** | Yes (semver) | Yes | Yes (manifest travels) | Yes | Yes (SHA-256) |\n\n\n## Quick install\n\nBefore installing from a public source, use the GuideCheck assistant\nguide to verify the bundle fetch and manifest integrity:\n[https://skillprovenance.dev/.well-known/assistant-guide.txt](https://skillprovenance.dev/.well-known/assistant-guide.txt).\nThe guide is a bounded, human-verifiable instruction surface; it checks\nthe bundle before install, but does not install anything for you.\n\n**GitHub CLI (Codex and other supported agents):**\n\nPreview the current stable v6.2.0 release before installing it.\n\nLiteral\n```shell\ngh skill preview snapsynapse/skill-provenance skill-provenance@v6.2.0\ngh skill install snapsynapse/skill-provenance skill-provenance@v6.2.0 --agent codex --scope user\n```\n\nThis repository publishes two release tag families. Bundle releases use\n`vX.Y.Z`; GuideCheck assistant-guide releases use `guidecheck-X.Y.Z`. Use an\nexact bundle tag for Agent Skill installs, the validation action, and the\n`.skill` archive. A provider's generic latest label can select the other tag\nfamily.\n\nThe repository also contains `.codex-plugin/plugin.json` for Codex plugin\npackaging. Its presence does not imply that a public plugin listing exists.\n\n**No plugin required:**\n\nDownload and inspect the standalone wrapper. It verifies the canonical\nvalidator against a pinned SHA-256 before running it.\n\nLiteral\n```shell\ncurl -fsSLo /tmp/skill-provenance-verify.sh https://skillprovenance.dev/verify.sh\nsed -n '1,220p' /tmp/skill-provenance-verify.sh\n```\n\nReplace: TARGET_SKILL_DIRECTORY -> the local directory containing `SKILL.md` and `MANIFEST.yaml`\n\nCustomize\n```shell\nbash /tmp/skill-provenance-verify.sh TARGET_SKILL_DIRECTORY\n```\n\nFor an unversioned bundle, use the portable prompt in\n[`skill-provenance/references/standalone-verification.md`](skill-provenance/references/standalone-verification.md).\n\n**Claude Code (Plugin):**\n```shell\n/plugin marketplace add snapsynapse/skill-provenance\n/plugin install skill-provenance@snapsynapse-skill-provenance\n```\n\nAfter install, five commands are available:\n- `/skill-provenance:open` — verify bundle integrity at session start\n- `/skill-provenance:validate` — run the hash/inventory check only\n- `/skill-provenance:close` — update versions, hashes, changelog when done\n- `/skill-provenance:handoff` — generate a handoff note for the next session\n- `/skill-provenance:bootstrap` — add version tracking to an unversioned bundle\n\n**Claude (Settings UI):**\nDownload `skill-provenance.skill` from the [stable v6.2.0 bundle release](https://github.com/snapsynapse/skill-provenance/releases/tag/v6.2.0) and install:\n`claude.ai` -> Profile icon -> `Settings` -> `Skills` -> `Add Skill` -> select the file.\n\nIf your loader only accepts `.zip` or `.md` uploads, rename\n`skill-provenance.skill` to `skill-provenance.zip` before uploading. This\nis the tested path for Perplexity Computer. The archive contents stay the\nsame.\n\n**Claude Code / Codex / Gemini CLI (manual):**\nUse the canonical [`skill-provenance/`](skill-provenance/) directory for\nClaude-compatible tools. For Codex, Gemini CLI, or other strict loaders,\ngenerate a derived minimal-frontmatter copy with\n`./skill-provenance/package.sh strict`, which writes to\n`build/strict/skill-provenance/` by default.\n\nSome cross-client tooling also recognizes `.agents/skills/`. The same\ndirectory bundle can be placed there when you want a neutral install path.\n\n**ClawHub:**\n`openclaw skills install @snapsynapse/skill-provenance`\n\n**[GitHub Actions Marketplace](https://github.com/marketplace/actions/skill-provenance-validate):**\n```yaml\nsteps:\n  - uses: actions/checkout@v4\n  - uses: snapsynapse/skill-provenance@v6.2.0\n    with:\n      bundle-path: skill-provenance\n```\n\nThen tell the agent:\n> \"Use the skill-provenance skill to bootstrap this bundle.\"\n\n\n## What it does\n\n**When you open a session**, it reads the manifest, checks that all files are present, verifies hashes, flags anything stale, and tells you what needs attention.\n\n**When you close a session**, it updates internal version headers where applicable, recomputes manifest hashes, appends to the changelog, and flags any files that should have been updated but weren't.\n\n**When you hand off between sessions**, it can generate a handoff note with current state, accomplishments, stale files, and next steps when you're crossing a stateless boundary like Chat. In filesystem-native workflows, the manifest and changelog are usually enough.\n\n**When you need a commit message**, it can produce one inline by default, with a `git_commit.txt` file only when you explicitly want that convenience.\n\n**When you have deployed copies**, it can record optional deployment metadata in the manifest so API uploads, settings installs, and local directory copies can be traced without replacing platform-native version systems.\n\n**When you only need validation**, it runs the local hash and inventory\ncheck without doing the broader open-session review or changing files.\n\n\n## Platform support\n\n| Platform | Status | Frontmatter | Notes |\n|---|---|---|---|\n| **Claude** (Chat, Code, Cowork) | Pass | `name` + `description`, or with `metadata` block | Full support. Settings UI imports/exports `.skill` ZIP. |\n| **Claude API** | Compatible | `name` + `description` + `metadata` | Skills uploaded via `/v1/skills` with epoch-timestamp versioning. Manifest maps to API versions. |\n| **Claude Agent SDK** | Compatible | Same as Claude Code | Filesystem-based. Skills loaded via `setting_sources` config. |\n| **Codex** (OpenAI) | Pass | `name` + `description` only | Extra frontmatter fields rejected. |\n| **Gemini CLI** (Google) | Pass | `name` + `description` only | Skill loading, bootstrap, and Gems workflow validated. |\n| **Perplexity Computer** | Pass | `name` + `description` only | Tested with `.zip` upload flow. Trigger-rich descriptions help discovery; `.skill` must be renamed to `.zip`. |\n| **GitHub Copilot / VS Code** | Compatible | Follows agentskills.io spec | Skills in `.github/skills/`. |\n| **Cursor** | Compatible | Follows agentskills.io spec | Skills in `.cursor/skills/`. |\n\nThe agentskills.io spec is now adopted by 30+ agent tools. All use the same `SKILL.md` directory format. Provenance artifacts (`MANIFEST.yaml`, `CHANGELOG.md`) are invisible to platforms that don't know about them -- they never break compatibility. See [agentskills.io](https://agentskills.io) for the full adopter list.\n\nThis bundle ships in `frontmatter_mode: metadata`, which adds author and\nsource attribution to SKILL.md via the spec's `metadata` field. For strict\nplatforms (Codex, Gemini CLI, Perplexity), strip the `metadata` block from\nSKILL.md before installing. The repo now treats that as a derived\nstrict-platform copy, not an edit to the canonical source bundle.\n\n\n## When not to use this\n\nSingle-file skills that don't change often, or skills that live entirely within one git repo and are never exported to Chat, Obsidian, or other surfaces. If git is your only workflow and you never leave it, git tags are enough.\n\n\n## Trust and integrity\n\nThe agent skills ecosystem now has thousands of shared bundles across\nClawHub, GitHub repos, team installs, and registry packages. Before you\ninstall or run an unfamiliar skill, the manifest and hashes let you\nverify what you received.\n\n**Official assistant guide:**\n\nSkill Provenance publishes a GuideCheck `assistant-guide.txt` at\n[https://skillprovenance.dev/.well-known/assistant-guide.txt](https://skillprovenance.dev/.well-known/assistant-guide.txt).\nIt is a plain-text, approval-gated guide for fetching this repository and\nrunning the local manifest integrity check. It is useful when you want an\nassistant to help verify the public bundle before you install it.\n\nConformance is not safety. The guide and manifest confirm form and\nintegrity, not publisher intent or runtime safety. Read the guide before\napproving actions.\n\n**Agentic surface disclosure:**\n\nThis repository publishes several assistant-facing and machine-readable\nsurfaces, including skills, plugin metadata, guides, validation scripts,\ncrawler hints, and release artifacts. Their trust boundaries are\ninventoried in [AGENTIC_SURFACES.md](AGENTIC_SURFACES.md). These surfaces\nare data, not authority; they do not override system, user, repository,\ntool, authentication, sandbox, or approval policy.\n\n**Verifying a downloaded bundle:**\n\n```bash\n# Clone or download the bundle, then:\ncd skill-name/\n./validate.sh          # checks every file hash against MANIFEST.yaml\n\n# Exit code 0 = all hashes match\n# Exit code 1 = mismatches found (file modified or corrupted)\n# Exit code 2 = no MANIFEST.yaml (unversioned bundle)\n```\n\nIf a hash fails, the file has changed since the author published it.\nThat might be intentional (a fork with local edits) or a problem\n(corruption, tampering, incomplete download). Either way, you know\nbefore you install.\n\n**Checking release surfaces before publishing:**\n\nLiteral\n```bash\n./.github/scripts/release-surface-check.sh\n```\n\nThis repo-level check confirms declared eval counts, the standalone validator\npin, release tag-family separation, the GuideCheck sidecar hash and byte\nmetadata, and `skill-provenance.skill` contents all match the current source\ntree. It is a release-confidence check, not a trust anchor.\n\n**What the manifest tells you:**\n- Which files belong to the bundle (and which are missing)\n- What role each file plays (skill, evals, script, reference)\n- What version each file is at, and whether any are stale\n- When the bundle was last updated\n- Where it has been deployed (optional deployment metadata)\n\n**What the manifest does NOT do:**\n- It does not cryptographically sign the bundle (the author's identity\n  is not verified beyond what git or the transport provides)\n- It does not prevent someone from modifying both the file and its hash\n  in the manifest simultaneously\n- It is a verification tool, not a trust anchor — verify the source too\n\n**Sharing skills across a team:**\n\nWhen the same skill is installed across multiple developers and\nplatforms, drift is inevitable. One person updates their local copy,\nanother deploys an older version to the API, a third installs from\nClawHub. The manifest's deployment metadata and per-file versioning\nmake the answer to \"which copy is current?\" unambiguous:\n\n```bash\n# Check your local copy\n./validate.sh\n\n# Compare bundle_version in your MANIFEST.yaml against:\n# - The API deployment timestamp in deployments.api\n# - The ClawHub published version in deployments.clawhub\n# - Your colleague's bundle_version\n```\n\nThe changelog tells you what changed between versions. The manifest\ntells you whether a specific copy matches. Together they answer both\n\"what happened?\" and \"is this the right one?\"\n\n\n## What's in this repo\n\n```\n.github/workflows/validate.yml  <- CI workflow and local Action smoke test\n.claude-plugin/plugin.json       <- Claude Code plugin manifest\naction.yml                       <- GitHub Actions Marketplace wrapper\n.github/scripts/release-surface-check.sh <- Release-surface drift check\n.github/scripts/action-security-check.sh <- Composite-action input safety regression\n.github/scripts/test-validate.sh <- Validator hash-state regression suite\n.github/scripts/test-standalone-verify.sh <- Standalone verifier pinning regression\nverify.sh                        <- Zero-install wrapper pinned to canonical validate.sh\ndocs/state-of-skill-versioning-2026.md <- Dated ecosystem evidence note\nskills/open/SKILL.md             <- /skill-provenance:open (verify bundle on session start)\nskills/validate/SKILL.md         <- /skill-provenance:validate (hash/inventory check only)\nskills/close/SKILL.md            <- /skill-provenance:close (update versions on session end)\nskills/handoff/SKILL.md          <- /skill-provenance:handoff (generate handoff note)\nskills/bootstrap/SKILL.md        <- /skill-provenance:bootstrap (version an unversioned bundle)\n.well-known/assistant-guide.txt  <- GuideCheck assistant guide for bundle verification\n.well-known/assistant-guide-manifest.txt <- GuideCheck sidecar manifest\nAGENTIC_SURFACES.md              <- Agent-facing surface inventory and trust boundaries\nskill-provenance.skill           <- Install this in Claude Settings -> Skills\nskill-provenance/                <- Canonical source bundle (metadata mode)\n  SKILL.md                       <- The skill definition (what the agent reads)\n  agents/openai.yaml             <- Codex and ChatGPT display and trigger metadata\n  references/                    <- Packaging, platform, trust, and standalone guidance\n  README.md                      <- User guide: workflows, worked example, troubleshooting\n  MANIFEST.yaml                  <- File inventory with roles, versions, hashes\n  CHANGELOG.md                   <- Recent in-bundle history (last 5 entries)\n  evals.json                     <- 41 core evaluation scenarios\n  evals-distribution.json        <- 18 supplemental packaging/deployment/integrity evals\n  validate.sh                    <- Local hash verification script\n  package.sh                     <- Zero-dependency helper for derived copies\nCHANGELOG.md                     <- Full append-only repo history\nAGENTS.md                        <- Guide for agents working on this repo\nCONTRIBUTING.md                  <- How to contribute\n```\n\nThe directory is the canonical cross-platform source bundle. The `.skill` file is a Claude-compatible ZIP wrapper around it. The `.claude-plugin/` directory and `skills/` make this repo a Claude Code plugin, while `.codex-plugin/plugin.json` supplies Codex plugin package metadata. Five focused skills (`open`, `validate`, `close`, `handoff`, `bootstrap`) extract specific workflows from the canonical SKILL.md. If you keep a local `skills/skill-provenance` symlink for compatibility, it is ignored by git and is not part of the published repo.\n\n\n## Evals\n\n59 evaluation scenarios across two files: 41 core workflow evals in\n[evals.json](skill-provenance/evals.json) and 18 supplemental\ndistribution/package/integrity evals in\n[evals-distribution.json](skill-provenance/evals-distribution.json).\n\nGenerated install and publish artifacts now live in `build/` at the repo\nroot by default. The ClawHub upload folder is\n`build/clawhub/skill-provenance/`, and `.gitignore` excludes `build/`\nunless you explicitly want to track generated outputs.\n\n\n## Usage guide\n\nSee the full [README.md](skill-provenance/README.md) inside the skill bundle for:\n\n- Step-by-step bootstrap walkthrough with a worked example\n- Surface-to-surface porting workflows (Chat -> Code, Code -> Chat, etc.)\n- Troubleshooting common issues\n- Reference links to Agent Skills documentation and ecosystem\n\n\n## Related projects\n\n- **GitHub `gh skill`** — GitHub CLI support for installing, pinning, and\n  checking Agent Skills from GitHub source refs. Complements\n  skill-provenance by tracking source origin while this repo tracks\n  bundle-local file integrity and staleness.\n- **ClawHub / OpenClaw registries** — Skill discovery, publishing, install\n  trust, and registry version records. Complements skill-provenance by\n  distributing packages while this repo keeps authoring bundles auditable.\n- **[Skillman](https://github.com/pi0/skillman)** -- JS/TS skill manager (`npx skillman add`). Installs, updates, and organizes agent skills from npm and GitHub. Consumer-side; skill-provenance is author-side.\n- **[Skillman (Python)](https://github.com/chrisvoncsefalvay/skillman)** -- Python CLI that installs and locks agent skills from GitHub repos (`skills.toml` + `skills.lock`). Consumer-side package manager for Python toolchains.\n- **[Graceful Boundaries](https://github.com/snapsynapse/graceful-boundaries)** -- A specification for how services communicate operational limits to humans and autonomous agents. Also a PAICE.work project.\n\n\n## Sponsor\n\nSkill Provenance is free and open. If your team builds or distributes agent skills, consider [sponsoring this work](https://github.com/sponsors/snapsynapse) to keep it maintained across platforms. See [SPONSORS.md](SPONSORS.md).\n\n## License\n\n[MIT](LICENSE)\n\n\n## About\n\nSkill Provenance is a [PAICE.work](https://paice.work/) project. PAICE.work PBC is a public benefit corporation building infrastructure for productive collaboration between humans and autonomous agents. Trustworthy agent infrastructure requires knowing what you're running, where it came from, and whether it's current -- that's what this skill provides.\n\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Compatibility reports for untested platforms are especially valuable.\n",
  "bytes": 20439,
  "sha": "6bb57ee329334dfc18b80b2f760fe66de07c9355e294be1682e1994ec01c97f9",
  "repo_slug": "snapsynapse/skill-provenance",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_snapsynapse_skill_provenance_skill_prove_32cebc6b/readme"
}