You build a skill for your AI coding agent. You refine it across five sessions. You upload it to a new conversation and immediately hit the question you can't answer: is this the one from yesterday, or the one from Tuesday?
If you're working in Claude Chat, there's no persistent filesystem. If you're in Codex, the session is stateless. If you moved the skill from Claude Code to Gemini CLI, you probably renamed a file and forgot which copy is canonical. And if someone else is using your skill, they have no way to know whether their copy matches yours.
Git solves this for code repositories. But agent skills don't always live in repos. They live in chat uploads, settings panels, Obsidian vaults, .skill files, and directories that get copied between surfaces with no audit trail. The version information needs to travel with the files, not alongside them in a system the files might never touch.
What skill-provenance does
skill-provenance is a meta-skill, or a skill that manages other skills. Load it alongside any skill project and it handles the versioning bookkeeping at session boundaries.
Three conventions make it work:
Version identity lives inside the files. Not in a filename suffix, not in a folder name, not in your memory of when you last edited it. The SKILL.md frontmatter carries the version, and the manifest confirms it.
A changelog travels with the bundle. Every session close appends what changed. When the next session opens, it can read the history without asking you to remember.
A manifest lists every file with roles and hashes. Open a session, the skill reads the manifest, checks that all files are present, verifies hashes, and tells you what's stale or missing before you start working.
What happens at session boundaries
When you open a session, it reads the manifest, compares hashes, flags missing files, and reports what needs attention.
When you close a session, it updates version headers, recomputes hashes, appends to the changelog, and flags files that should have been updated but weren't.
When you hand off between sessions, it generates a handoff note: current state, what was accomplished, stale files, next steps. Because the next instance of Claude has no memory of what you just did, and "I think I left off around..." is not version control.
Cross-platform portability
The skill works on any platform that supports the agentskills.io standard. But different platforms have different opinions about SKILL.md frontmatter:
| Platform | Frontmatter rules |
|---|---|
| Claude | Full metadata block with version info |
| Gemini CLI | Name and description only |
| Codex | Name and description only |
| GitHub Copilot | Follows agentskills.io spec |
The manifest tracks a frontmatter_mode field (claude or minimal) so the skill knows whether to embed version info in SKILL.md or keep it manifest-only. The repo ships in minimal mode for maximum portability.
This means you can author a skill in Claude Code, export it for Gemini CLI, and the version identity carries over without manual conversion.
What's in the bundle
skill-provenance.skill # Install this in Claude Settings
skill-provenance/
├── SKILL.md # The skill definition
├── README.md # User guide with worked examples
├── MANIFEST.yaml # File inventory: roles, versions, hashes
├── CHANGELOG.md # Change history
├── evals.json # 13 evaluation scenarios
└── validate.sh # Local hash verification script
The .skill file is a ZIP for Claude's Settings UI. The directory is the same content for Claude Code, git repos, and Obsidian vaults. Use whichever format fits your workflow.
The evals
13 structured evaluation scenarios covering: bootstrapping an unversioned bundle, detecting missing and stale files on session open, conflict detection between version headers and manifests, cross-platform bootstrapping for Codex and Gemini CLI, frontmatter mode toggling, generating git commit messages, and handoff notes with per-file change summaries.
These aren't unit tests. They're prompt-and-expected-behavior pairs you can use to verify the skill works correctly on your platform, or as a reference for how to write evals for your own skills.
Who this is for
This is for anyone who builds or maintains agent skills and has been bitten by the "which version is this?" problem. If you're a solo author working across multiple surfaces, it catches the drift you'd otherwise miss. If you're handing skills to a team, it gives the next person a manifest they can verify instead of a folder they have to trust.
It's also a reference implementation for how to structure a skill bundle. If you're building your first skill and wondering what files to include, how to write evals, or how to handle cross-platform compatibility, this is one answer to those questions.
Install
For Claude Chat: download skill-provenance.skill from the latest release, go to Settings, Skills, Add Skill, select the file.
For Claude Code, Codex, or Gemini CLI: use the skill-provenance/ directory directly.
Then tell your agent:
Use the skill-provenance skill to bootstrap this bundle.
GitHub repo -- MIT licensed, v4.0.0.
Built by SnapSynapse. Used as the versioning backbone for skill-a11y-audit, ai-capability-reference, and the rest of the SnapSynapse skill ecosystem.
Top comments (0)