From Skill Provenance
Use when creating or updating a skill-source.json provenance sidecar for a new, copied, or modified skill, checking whether upstream sources have changed, or folding external guidance into a local skill.
How this skill is triggered — by the user, by Claude, or both
Slash command
/skill-provenance:skill-provenanceThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Skill source metadata travels with the skill. When you update a skill from upstream material, or fold in new guidance,
Skill source metadata travels with the skill. When you update a skill from upstream material, or fold in new guidance,
examples, scripts, references, or policy from another source, update that skill's skill-source.json in the same
change.
Use skill-source.json for durable provenance: source material, attribution, licenses, pinned versions, and cheap
update-check hints. Do not use it for reconstruction notes, review opinions, confidence labels, or temporary
diagnostics.
skill-source.json sidecar.references/skill-source-json.md.python3 SKILL_PATH/scripts/check_skill_updates.py --skills-root SKILLS_ROOT
Example when this skill is installed at .agents/skills/skill-provenance:
python3 .agents/skills/skill-provenance/scripts/check_skill_updates.py --skills-root .agents/skills
up-to-date means a commit-pinned, frontmatter-pinned, or fetch-date source matches the latest cheap signal.candidate means the source appears to have changed and needs manual upstream diff review.local-original means original local material, not an upstream update candidate.skipped means the source is intentionally manual, uncheckable, or pinned by a non-comparable signal.unknown means the check could not reach a conclusion. Causes include: GitHub and local checkout fallback both
failed (retry if transient); a date-only fetchedAt cannot disambiguate a same-day upstream change (use a full
ISO timestamp to resolve); or a local checkout fallback found the latest commit but could not determine its date
(switch to gitCommit versionSource or provide network access).error means the sidecar violates the required shape and should be fixed before update decisions.skill-source.json:
sources entry for every new upstream or supporting reference;localCheckoutHint only as an optional inspection aid, not as provenance;attribution whenever external material exists;python3 -m json.tool SKILL_PATH/skill-source.json
python3 SKILL_PATH/scripts/check_skill_updates.py --skills-root SKILLS_ROOT --validate-only
If the checker has changed, run its tests:
python3 SKILL_PATH/scripts/test_check_skill_updates.py
skill-source.json essentialsRead references/skill-source-json.md for the full contract and references/skill-source.schema.json for a JSON
Schema representation.
Required top-level fields:
schemaVersion: currently 1.skill: the directory name of the skill this sidecar describes.sources: non-empty array of source entries.attribution: required when any source has role upstream-source or supporting-reference.Required source fields:
type: one of upstream-skill, upstream-reference, local-original-content.role: one of upstream-source, supporting-reference, original-content.label: short human-readable source name.version: pinned source version.versionSource: one of frontmatter, gitCommit, fetchDate.fetchedAt: ISO date or timestamp for when the source was inspected.license: source license or unknown.Recommended version choice:
metadata.version frontmatter field (agentskills.io spec) — the checker reads this directly
and falls back to a top-level version: key;When the upstream skill has metadata.author in its frontmatter, the checker includes it as upstreamAuthor in the
report row — use it to write the top-level attribution field.
attribution inside a source entry. It is a required top-level field alongside skill and
schemaVersion, not a per-source field.gitEvidence, commit subjects, review notes, diagnostics, or confidence labels in skill-source.json.Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub rock3r/skill-provenance --plugin skill-provenance