skill-provenance

Skill: skill-provenance

Provenance + integrity ledger for each skill. orca-sec-scans scans for vulns/secrets in CONTENT; this skill answers two other supply-chain questions: where does the skill come from and has it been tampered with after installation. The store is fdk/skills.provenance.json (source + recorded date + sha256 of every file in skills/<name>/). Verify by recomputing the checksum and comparing against the ledger — mismatch = MODIFIED, a skill on disk but not recorded in the ledger = UNTRACKED.

WHAT

Purpose and context

• Purpose: answers two supply-chain questions for each skill — where it comes from and whether it has been tampered with after installation — using the ledger fdk/skills.provenance.json (source + recorded date + sha256 of every file) and a verify command that recomputes checksums.
• Trigger (when to use):
  • Just installed / distilled a skill from an external source (marketplace, another repo, distill in another project session) → record to lock in the source + checksum.
  • Suspect / want to check whether a skill has been modified out-of-band → check.
  • Ask "where does this skill come from ", "audit skill sources", "skill checksum", "skill supply-chain".
  • CI wants to block unknown skills or skills modified without the ledger being updated.
• Non-goals: does not scan for vulns/secrets in skill content (that is the job of orca-sec-scans); does not guess a skill's source.

Mental model

skills/<name>/ (file trên đĩa) → sha256 mỗi file → so với sổ fdk/skills.provenance.json → OK | MODIFIED (lệch) | UNTRACKED (trên đĩa chưa ghi sổ) | MISSING (trong sổ, không còn trên đĩa). record = write/overwrite ledger entry; check = read and compare.

Input and output contract

	Field	Required?	Meaning
In	<name> or --all	present for record	skill to be recorded in the ledger
In	--source	present for record	URL, repo#ref real, or local-authored
In	--ci	no	check returns exit 1 when there is MODIFIED/UNTRACKED
Out	ledger entry in fdk/skills.provenance.json	after record	source + recorded date + sha256
Out	status of each skill	after check	OK / MODIFIED / UNTRACKED / MISSING + exit code

Rules and capabilities

• RULE-01 (MUST): Do not make up sources. --source must be a real URL/ref or local-authored; wrong provenance is worse than none.
• RULE-02 (MUST): record after EVERY valid install/edit — the ledger is the source of truth; a skill modified without re-recording will be blocked by CI as an unexpected modification (as intended).
• RULE-03 (MUST): Do not replace orca-sec-scans — this skill handles provenance/integrity, not vuln/secret content scanning; use both.
• RULE-04 (MUST): check --ci treat MISSING (skill removed) as not-an-error; only MODIFIED/UNTRACKED block.
• RULE-05 (MUST): Store fdk/skills.provenance.json is a curated file — commit it together with skill changes, don't let it drift.
• Capabilities: read skill files + compute hashes; write a local provenance ledger. No network.

Failure boundaries

• Don't know the true source of a skill → clarify with the user, don't record --source guesses.
• check --ci see MODIFIED/UNTRACKED → failed (exit 1); intentional modification → re-record, unexpected modification → investigate.
• MISSING → report, don't block.

HOW

Main workflow

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	effect	empty ledger	Backfill once record --all --source local-authored	full ledger	ledger already exists → skip
W02	effect	new skill + true source	record <name> --source …	ledger entry	source unclear → clarify
W03	deterministic	ledger + disk	check (all or one skill)	OK/MODIFIED/UNTRACKED/MISSING	—
W04	deterministic	ledger + disk	Gate CI check --ci	exit 0/1	MODIFIED/UNTRACKED → exit 1
W05	effect	skill intentionally modified	re-record with old source	new checksum	no re-record → W04 red

Details of each step (source of truth for W01–W05):

1. Backfill once (if the ledger is empty) — record every existing skill as self-written:

   python3 fdk/tools/skill-provenance.py record --all --source local-authored
   

2. When installing / adding a new skill — record the true source (URL, repo#ref, or local-authored):

   python3 fdk/tools/skill-provenance.py record <name> --source "https://github.com/<owner>/<repo>#<ref>"
   

3. Check integrity at any time (prints OK / MODIFIED / UNTRACKED / MISSING):

   python3 fdk/tools/skill-provenance.py check          # xem tất cả
   python3 fdk/tools/skill-provenance.py check <name>   # một skill
   

4. Gate CI — exit 1 if there is MODIFIED or UNTRACKED (already wired into .github/workflows/skills-sync.yml):

   python3 fdk/tools/skill-provenance.py check --ci
   

5. After intentionally modifying a skill, re-run record <name> --source <nguồn cũ> to update the checksum — otherwise, check --ci will report MODIFIED (correct: every change must go through the ledger).

Branches

ID	Kind	Guard	Behavior	Skip / failure	Rejoin
B01	conditional_required	empty registry	backfill W01	registry already has it → skip	W03
B02	recovery	check reports MODIFIED	intentional edit → W05 re-record; unclear who edited → investigate as an anomalous edit	—	W03
B03	recovery	check reports UNTRACKED	valid new skill → W02 record with the real source	unknown source → clarify	W03

Validation and stopping

Fully deterministic: checksum + exit code of skill-provenance.py. The part that needs a person: is the source --source real. Stop when check prints all OK (MISSING accepted).

Examples

• Positive: just pulled the skill from https://github.com/acme/skills#v1.2 → python3 fdk/tools/skill-provenance.py record foo --source "https://github.com/acme/skills#v1.2" → check foo prints OK.
• Boundary/failure: edit skills/foo/SKILL.md without re-recording → check --ci prints MODIFIED foo, exit 1; the user asks "where did foo come from" but nobody knows → do not record --source as a guess, ask again.