Immutable. This exact content is served forever at /api/v1/blob/5087711c69a1f8f7.
# Agents Guide Instructions for AI agents (Claude, Codex, Gemini CLI, etc.) working on this repository. This metaskill is also published to [ClawHub](https://clawhub.com) for discovery by OpenClaw agents. ## Repository structure ``` skill-provenance/ ← Canonical source bundle (DO NOT rename) ├── SKILL.md ← Agent-facing skill definition ├── README.md ← Human-facing user guide (has internal version header) ├── MANIFEST.yaml ← File inventory: roles, versions, SHA-256 hashes ├── CHANGELOG.md ← Recent in-bundle change history (last 5 entries) ├── evals.json ← 42 core evaluation scenarios ├── evals-distribution.json ← 21 supplemental distribution evals ├── validate.sh ← Bash script for local hash verification ├── package.sh ← Bash script for derived strict/ClawHub outputs └── references/standalone-verification.md ← No-plugin verify/bootstrap path action.yml ← GitHub Actions Marketplace wrapper for validate.sh verify.sh ← Standalone wrapper pinned to canonical validate.sh CHANGELOG.md ← Full append-only repo history skill-provenance.skill ← Claude Settings ZIP (rebuilt from the directory) ``` The `skill-provenance/` directory is the single source of truth. The `.skill` file is a packaging wrapper. ## Before making changes 1. Read `skill-provenance/MANIFEST.yaml` to understand the current bundle state. 2. Run `./skill-provenance/validate.sh` to confirm all hashes are clean. 3. Read `skill-provenance/CHANGELOG.md` for recent context and root `CHANGELOG.md` if you need older release history. ## After making changes 1. Bump per-file `version` integers in `MANIFEST.yaml` for every file you changed. 2. Recompute hashes: run `./skill-provenance/validate.sh --update`. 3. Bump `bundle_version` (semver) in `MANIFEST.yaml`: - PATCH for docs, typos, non-functional changes. - MINOR for new features, new files, capability additions. - MAJOR for breaking changes to the versioning model or spec. 4. Update `bundle_date` to today. 5. Add a new entry at the top of both changelogs: - `skill-provenance/CHANGELOG.md` keeps the newest 5 entries only. - `CHANGELOG.md` at repo root is the full append-only archive. Name every file that changed and describe what changed in each. 6. Rebuild the `.skill` ZIP if bundle contents changed: ```bash rm -f skill-provenance.skill zip -r skill-provenance.skill skill-provenance/ ``` 7. 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. ## Key rules - **MANIFEST.yaml is not self-listed.** It tracks other files but does not contain its own hash. Do not add it to the `files:` list. - **Canonical `SKILL.md` uses metadata-mode frontmatter.** Keep the checked-in bundle aligned with the current manifest and README guidance. When preparing strict-platform copies, derive them from the canonical bundle rather than rewriting the source bundle in place. - **Per-file versions are integers.** They count revisions to that specific file. The bundle version (`bundle_version`) is semver. - **Paths in MANIFEST.yaml are relative** to the bundle root (`skill-provenance/`). No absolute paths. - **Root `CHANGELOG.md` is append-only.** New entries go at the top. Never edit or remove existing entries there. - **`skill-provenance/CHANGELOG.md` is rolling recent history.** Keep the newest 5 entries there and point readers to the root changelog for older history. - **validate.sh must stay zero-dependency.** Only `bash`, `shasum`/`sha256sum`, and `awk`. No Python, Node, or external tools. ## Files outside the bundle These repo-level files are not tracked in MANIFEST.yaml: - `README.md` (root) — GitHub landing page, not part of the skill bundle. - `verify.sh` — Standalone wrapper that delegates to the pinned canonical validator. - `CHANGELOG.md` (root) — Full repo history, not part of the skill bundle. - `AGENTS.md` — This file. - `CONTRIBUTING.md` — Contribution guide. - `.github/` — Issue templates, CI workflows. - `LICENSE` — MIT license. - `.gitignore` — Git exclusions. Changes to these files do not require a bundle version bump unless they also change files inside `skill-provenance/`. ## Testing changes Run validation after any edit to bundle files: ```bash cd skill-provenance ./validate.sh # Verify hashes match manifest ./validate.sh --update # Recompute hashes after edits ``` Exit code 0 means clean. Exit code 1 means mismatches or missing files. Exit code 2 means MANIFEST.yaml not found.