# Skill Provenance

> Portable provenance, integrity, and drift control for Agent Skills.

Skill Provenance is a metaskill that keeps version identity, staleness detection, and hash-based integrity verification inside the skill bundle so it survives local folders, registries, platform uploads, and multi-agent sessions.

Most ecosystem tools track source, registry, install, or deployment state. Skill Provenance tracks the actual multi-file bundle an agent is editing, which matters when SKILL.md, evals, scripts, packages, and deployed copies can drift independently.

## Core concepts

- **Bundle version**: Semver version for the entire skill bundle, stored in MANIFEST.yaml
- **Per-file versions**: Integer revision counters for each file in the bundle
- **SHA-256 hashes**: Every file's hash is recorded in the manifest for integrity verification
- **Staleness detection**: When SKILL.md changes but evals.json doesn't, the changelog says so
- **Cross-platform**: Works across Claude, Codex, Gemini CLI, Copilot, Perplexity, and any agent that reads markdown
- **Complementary tooling**: Works alongside GitHub `gh skill`, ClawHub, Skillman, and platform APIs rather than replacing them
- **Trust model**: Provides an integrity check, not a trust anchor

## Key files in a bundle

- `SKILL.md` — the skill definition (what agents read)
- `MANIFEST.yaml` — file inventory with roles, versions, SHA-256 hashes
- `CHANGELOG.md` — rolling recent history (last 5 entries)
- `evals.json` — evaluation scenarios for testing skill behavior
- `validate.sh` — local hash verification script

## Links

- Canonical site: https://skillprovenance.dev/
- GitHub: https://github.com/snapsynapse/skill-provenance
- ClawHub: https://clawhub.ai/snapsynapse/skill-provenance
- Skill definition: https://github.com/snapsynapse/skill-provenance/blob/main/skill-provenance/SKILL.md
- Changelog: https://github.com/snapsynapse/skill-provenance/blob/main/CHANGELOG.md
- Assistant guide (GuideCheck): https://skillprovenance.dev/.well-known/assistant-guide.txt
- Agent Skills spec: https://agentskills.io

## Related patterns

- Knowledge as Code: https://knowledgeascode.dev/
- Graceful Boundaries: https://gracefulboundaries.dev/
- PAICE.work Open Patterns: https://paice.work/

## License

MIT — https://github.com/snapsynapse/skill-provenance/blob/main/LICENSE