A metaskill for version tracking across Agent Skills sessions, surfaces, and platforms.
You upload a SKILL.md to a new session and can't tell if it's the latest version. You update the skill definition but forget to update the evals. You deploy a skill via the API but your local copy drifts. Skills don't sync between surfaces — a skill in Claude Code, claude.ai, and the API are three separate copies. Git tracks that something changed — Skill Provenance tracks what it means across all of them.
As of March 7, 2026, skills are no longer a Claude-only niche. Anthropic supports skills across Claude, the API, and the Agent SDK; other clients now load skills from local directories or uploaded bundles; and the same skill often exists in several places at once. That makes author-side provenance more important: you need to know which copy is current, which deployed surface is stale, and what changed between installs.
Before After
────── ─────
SKILL_v4.md SKILL.md (version lives inside)
SKILL_v5.md MANIFEST.yaml (what's in the bundle)
evals_old.json CHANGELOG.md (what changed and why)
evals.json
"which one is current?" "bundle is at 4.2.1, evals are stale"
As of 4.3.0, the portable core is intentionally small: the bundle files,
MANIFEST.yaml, and CHANGELOG.md. Optional conveniences like handoff.md
and git_commit.txt are still supported when useful, but they are no longer
treated as default required artifacts.
| Approach | Tracks versions | Detects staleness | Cross-session | Cross-platform | Tracks intent |
|---|---|---|---|---|---|
| Git tags | Yes | No | No (requires repo access) | No | No |
Filename suffixes (_v5) |
Poorly | No | No | No | No |
| Skillman | Pins versions | No | Consumer-side only | No | No |
Skills API (/v1/skills) |
Upload timestamps | No | Single surface only | No | No |
| Skill Provenance | Yes (semver) | Yes | Yes (manifest travels) | Yes | Yes (changelog) |
Git tags work when everyone has repo access. Filename suffixes break as soon as you rename. Skillman pins versions for consumers. The Skills API tracks which upload is active on a single surface but doesn't track what changed or detect staleness. Skill Provenance fills the gap for authors: it tracks version identity, staleness, and intent inside the bundle so it survives session boundaries, surface transitions, and platform changes.
When not to use this: Single-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.
| Platform | Status | Frontmatter | Notes |
|---|---|---|---|
| Claude (Chat, Code, Cowork) | Pass | name + description, or with metadata block |
Full support. Settings UI imports/exports .skill ZIP. |
| Claude API | Compatible | name + description + metadata |
Skills uploaded via /v1/skills with epoch-timestamp versioning. Manifest maps to API versions. |
| Claude Agent SDK | Compatible | Same as Claude Code | Filesystem-based. Skills loaded via setting_sources config. |
| Codex (OpenAI) | Pass | name + description only |
Extra frontmatter fields rejected. |
| Gemini CLI (Google) | Partial | name + description only |
Skill loading works. Gems workflow untested. |
| Perplexity Computer | Partial | name + description only |
Tested with .zip upload flow. Trigger-rich descriptions help discovery; .skill must be renamed to .zip. |
| GitHub Copilot / VS Code | Compatible | Follows agentskills.io spec | Skills in .github/skills/. |
| Cursor | Compatible | Follows agentskills.io spec | Skills in .cursor/skills/. |
The 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 for the full adopter list.
This bundle ships in frontmatter_mode: minimal for maximum portability.
Claude (Settings UI):
Download skill-provenance.skill from the latest release and install:
claude.ai → Profile icon → Settings → Skills → Add Skill → select the file.
If your loader only accepts .zip or .md uploads, rename
skill-provenance.skill to skill-provenance.zip before uploading. This
is the tested path for Perplexity Computer. The archive contents stay the
same.
Claude Code / Codex / Gemini CLI:
Use the skill-provenance/ directory directly. Same source works across all platforms.
Some cross-client tooling also recognizes .agents/skills/. The same
directory bundle can be placed there when you want a neutral install path.
ClawHub:
clawhub install skill-provenance
Then tell the agent:
"Use the skill-provenance skill to bootstrap this bundle."
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.
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.
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.
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.
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.
Modern skill workflows increasingly involve downloaded bundles, shared org installs, and multiple local copies. The manifest, changelog, and hashes give agents and humans an audit trail: what files belong to the bundle, what changed, and whether a copied bundle still matches its recorded state. This is especially useful before reinstalling a skill, moving it between tools, or checking whether a deployed surface is behind local changes.
skill-provenance.skill ← Install this in Claude Settings → Skills
skill-provenance/ ← Canonical source bundle (use this for Code/Codex/Gemini)
├── SKILL.md ← The skill definition (what the agent reads)
├── README.md ← User guide: workflows, worked example, troubleshooting
├── MANIFEST.yaml ← File inventory with roles, versions, hashes
├── CHANGELOG.md ← Change history
├── evals.json ← 22 evaluation scenarios
└── validate.sh ← Local hash verification script
AGENTS.md ← Guide for agents working on this repo
CONTRIBUTING.md ← How to contribute
The directory is the canonical cross-platform source bundle. The .skill file is a Claude-compatible ZIP wrapper around it.
22 evaluation scenarios covering bootstrap, session open/close, conflict detection, optional handoff, cross-platform compatibility, deployment drift, trust checks, redeploy events, deployment conflicts, packaged subsets, and more. See evals.json for the full list.
See the full README.md inside the skill bundle for:
- Step-by-step bootstrap walkthrough with a worked example
- Surface-to-surface porting workflows (Chat → Code, Code → Chat, etc.)
- Troubleshooting common issues
- Reference links to Agent Skills documentation and ecosystem
- 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. - Skillman (Python) — Python CLI that installs and locks agent skills from GitHub repos (
skills.toml+skills.lock). Consumer-side package manager for Python toolchains.
See CONTRIBUTING.md. Compatibility reports for untested platforms are especially valuable.
