Skill Provenance

Version identity and integrity verification for Agent Skills.

Agent Skills move between sessions, surfaces, and platforms. Filename suffixes break. Git tags require repo access. Version identity gets lost at every boundary. This skill keeps it inside the bundle where it belongs.

Before

SKILL_v4.md
SKILL_v5.md
evals_old.json
evals.json

"which one is current?"

After

SKILL.md
MANIFEST.yaml
CHANGELOG.md

"bundle is at 4.8.0, evals are stale"

Version Identity

Semver bundle versions and per-file revision counters live inside the files and manifest, not in filenames.

Staleness Detection

When SKILL.md changes but evals.json doesn't, the changelog says so. Drift becomes visible, not silent.

Hash Verification

SHA-256 hashes in the manifest let any session verify that files match their recorded state.

Read the Skill Quick Start

Why provenance matters

Skills are the unit of reuse in the agent ecosystem. They get exported from Chat, installed in Code, uploaded to APIs, shared on registries, and copied into Obsidian vaults. Every boundary crossing is a chance for version confusion.

Cross-session

Chat sessions are stateless. Without a manifest, the next session has no idea what version it received or whether files are complete.

Cross-surface

A skill authored in Claude Code, exported as a .skill ZIP, and installed via Settings UI needs version identity that survives the round trip.

Cross-platform

The same skill running on Claude, Codex, Gemini CLI, and Copilot. Each platform has different frontmatter rules. The manifest stays consistent.

Trust and audit

Downloaded bundles, shared org installs, registry packages. Hashes and changelogs give agents and humans an audit trail before executing unfamiliar skills.

Approach	Versions	Staleness	Cross-session	Cross-platform
Git tags	Yes	No	No	No
Filename suffixes	Poorly	No	No	No
Skills API	Timestamps	No	Single surface	No
Skill Provenance	Semver	Yes	Yes	Yes

Quick start

Install the skill, then tell the agent to use it.

Claude Code (Plugin)

/plugin marketplace add snapsynapse/skill-provenance
/plugin install skill-provenance@snapsynapse-skill-provenance

Claude (Settings UI)

1. Download skill-provenance.skill from the latest release
2. claude.ai → Profile → Settings → Skills → Add Skill
3. Select the file

If your loader only accepts .zip, rename the file. The archive contents stay the same.

ClawHub

clawhub install skill-provenance

Codex

git clone https://github.com/snapsynapse/skill-provenance.git
./skill-provenance/package.sh strict
cp -r build/strict/skill-provenance ~/.codex/skills/

Gemini CLI

git clone https://github.com/snapsynapse/skill-provenance.git
./skill-provenance/package.sh strict
cp -r build/strict/skill-provenance ~/.gemini/skills/

Manual (any platform)

Copy the skill-provenance/ directory into your project.
Or use .agents/skills/ for the neutral cross-client path.

Then tell the agent:

"Use the skill-provenance skill to bootstrap this bundle."

Claude Claude Code Claude API Codex Gemini CLI Copilot Cursor Perplexity

Compatible with the agentskills.io open standard (30+ adopters).

View on GitHub Latest Release

8.41/10

ProSkills.md score

333

ClawHub installs

evaluation scenarios

platforms tested