git:20260829.feb818a to git:20260905.3d5c0c3

# Skill Provenance

A metaskill for version tracking across Agent Skills sessions, surfaces, and platforms. This is a skill bundle project, not a library.

Canonical site: https://skillprovenance.dev/ | Repo: snapsynapse/skill-provenance (public, MIT). Ships as a Claude Code plugin and as a standalone `.skill` upload. Zero external dependencies by design (bash + shasum/sha256sum + awk + zip only).

## Key files

- `skill-provenance/SKILL.md` -- the skill definition (what agents read)

- `skill-provenance/MANIFEST.yaml` -- file inventory with roles, versions, SHA-256 hashes

- `skill-provenance/CHANGELOG.md` -- rolling recent history (last 5 entries)

- `skill-provenance/validate.sh` -- local hash verification script

- `skill-provenance/package.sh` -- derived copy generator (strict/ClawHub)

- `skill-provenance/references/standalone-verification.md` -- no-plugin verify/bootstrap path

- `verify.sh` -- standalone wrapper pinned to the canonical validator

- `action.yml` -- GitHub Actions Marketplace wrapper for bundle validation

- `CHANGELOG.md` -- full append-only repo history

- `AGENTS.md` -- detailed guide for agents working on this repo

## Claude Code plugin

This repo doubles as a Claude Code plugin. The plugin structure:

- `.claude-plugin/plugin.json` -- plugin manifest (name, version, metadata)

- `.claude-plugin/marketplace.json` -- marketplace listing for self-hosted install

- `skills/open/SKILL.md` -- `/skill-provenance:open` (verify bundle on session start)

- `skills/close/SKILL.md` -- `/skill-provenance:close` (update versions on session end)

- `skills/handoff/SKILL.md` -- `/skill-provenance:handoff` (generate handoff note)

- `skills/bootstrap/SKILL.md` -- `/skill-provenance:bootstrap` (version an unversioned bundle)

- `skills/skill-provenance` -- symlink to `skill-provenance/` for the monolithic skill

The five focused skills extract specific workflows from the monolithic SKILL.md.

The symlink preserves `/skill-provenance:skill-provenance` as the full monolithic skill.

Test locally: `claude --plugin-dir .`

## Commands

```bash

./skill-provenance/validate.sh # verify all hashes match manifest

./skill-provenance/validate.sh --update # recompute hashes after edits

./skill-provenance/package.sh strict # generate strict-platform copy

./skill-provenance/package.sh clawhub # generate ClawHub upload copy

./skill-provenance/package.sh all # generate both

```

## Conventions

- No external dependencies. Scripts use only bash, shasum/sha256sum, awk, and zip.

- The `skill-provenance/` directory is the single source of truth. Everything else is derived.

- MANIFEST.yaml is not self-listed. It tracks other files but does not contain its own hash.

- Per-file versions are integers counting revisions. Bundle version (`bundle_version`) is semver.

- Canonical SKILL.md uses `frontmatter_mode: metadata`. Strict-platform copies strip the metadata block.

- Root `CHANGELOG.md` is append-only. In-bundle `CHANGELOG.md` keeps the newest 5 entries.

## After editing bundle files

1. Bump per-file `version` in MANIFEST.yaml for changed files

2. Run `./skill-provenance/validate.sh --update` to recompute hashes

3. Bump `bundle_version` (semver) and `bundle_date` in MANIFEST.yaml

4. Update both changelogs (in-bundle keeps 5 entries, root is append-only)

5. Rebuild the `.skill` ZIP:

```bash

rm -f skill-provenance.skill

zip -r skill-provenance.skill skill-provenance/

```

6. Run `./.github/scripts/release-surface-check.sh` to confirm eval-count declarations, the standalone validator pin, GuideCheck sidecar metadata, and the `.skill` ZIP all match the current source.

## CI

`.github/workflows/validate.yml` runs on push/PR to `main`: verifies bundle hashes via the repo's own `action.yml`, test-builds the strict and ClawHub packages, and runs `release-surface-check.sh`, `action-security-check.sh`, `test-validate.sh`, and `test-standalone-verify.sh`. All are bash scripts under `.github/scripts/` and `skill-provenance/`.

- Validation fails closed on unsafe or ambiguous paths, duplicates, missing

inventories, and symlink components. Packaging revalidates through the

same policy at each derived-package boundary.

Skill validation, exact-tag preview, and discovery search all pass.

- Roadmap priorities are portfolio dogfooding, Agent Skill publication,

evidence-led interop, and later optional signatures.