Skill: skill-provenance

Sổ nguồn gốc + toàn vẹn cho từng skill.

orca-sec-scans

quét vuln/secret trong NỘI DUNG; skill này trả lời hai câu hỏi khác của chuỗi cung ứng (supply-chain): skill từ đâu tới và có bị sửa lén sau khi cài không. Store là

fdk/skills.provenance.json

(nguồn + ngày ghi + sha256 mọi file trong

skills/<name>/

). Verify bằng cách tính lại checksum và so với sổ — lệch = MODIFIED, có skill trên đĩa mà chưa ghi sổ = UNTRACKED.

WHAT

Purpose và context

Purpose: trả lời hai câu hỏi supply-chain cho từng skill — từ đâu tới và có bị sửa lén sau khi cài không — bằng sổ
```
fdk/skills.provenance.json
```
(nguồn + ngày ghi + sha256 mọi file) và lệnh verify tính lại checksum.
Trigger (when to use):
- Vừa cài / chưng cất một skill từ nguồn ngoài (marketplace, repo khác, distill trong phiên dự án khác) →
```
record
```
  để chốt nguồn + checksum.
- Nghi ngờ / muốn kiểm skill có bị sửa ngoài luồng không →
```
check
```
  .
- Hỏi "skill này từ đâu ra", "audit nguồn skill", "checksum skill", "supply-chain skill".
- CI muốn chặn skill lạ hoặc skill bị sửa mà chưa cập nhật sổ.
Non-goals: không quét vuln/secret trong nội dung skill (việc của
```
orca-sec-scans
```
); không tự đoán nguồn skill.

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

= ghi/ghi đè mục sổ;

check

= đọc so.

Input và output contract

	Field	Required?	Ý nghĩa
In	`<name>` hoặc `--all`	có với `record`	skill cần ghi sổ
In	`--source`	có với `record`	URL, `repo#ref` thật, hoặc `local-authored`
In	`--ci`	không	`check` trả exit 1 khi có MODIFIED/UNTRACKED
Out	mục sổ trong `fdk/skills.provenance.json`	sau `record`	nguồn + ngày ghi + sha256
Out	trạng thái từng skill	sau `check`	OK / MODIFIED / UNTRACKED / MISSING + exit code

Rules và capabilities

RULE-01 (MUST): Không tự bịa nguồn.
```
--source
```
phải là URL/ref thật hoặc
```
local-authored
```
; provenance sai còn tệ hơn không có.
RULE-02 (MUST): record sau MỌI lần cài/sửa hợp lệ — sổ là nguồn chân lý; skill sửa mà không re-record sẽ bị CI chặn như sửa đổi lạ (đúng ý đồ).
RULE-03 (MUST): Không thay
orca-sec-scans
— skill này lo provenance/toàn vẹn, không quét vuln/secret nội dung; dùng cả hai.
RULE-04 (MUST):
```
check --ci
```
coi MISSING (skill đã gỡ) là không-phải-lỗi; chỉ MODIFIED/UNTRACKED mới chặn.
RULE-05 (MUST): Store
```
fdk/skills.provenance.json
```
là file curated — commit cùng thay đổi skill, đừng để drift.
Capabilities: đọc file skill + tính hash; ghi sổ provenance cục bộ. Không mạng.

Failure boundaries

Không biết nguồn thật của skill → clarify với user, không ghi
```
--source
```
đoán.
```
check --ci
```
thấy MODIFIED/UNTRACKED → failed (exit 1); sửa có chủ đích → re-record, sửa lạ → điều tra.
MISSING → báo, không chặn.

HOW

Main workflow

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	effect	sổ trống	Backfill một lần `record --all --source local-authored`	sổ đầy đủ	sổ đã có → skip
W02	effect	skill mới + nguồn thật	`record <name> --source …`	mục sổ	nguồn không rõ → clarify
W03	deterministic	sổ + đĩa	`check` (tất cả hoặc một skill)	OK/MODIFIED/UNTRACKED/MISSING	—
W04	deterministic	sổ + đĩa	Gate CI `check --ci`	exit 0/1	MODIFIED/UNTRACKED → exit 1
W05	effect	skill đã cố ý sửa	re-record với nguồn cũ	checksum mới	không re-record → W04 đỏ

Chi tiết từng bước (nguồn chân lý cho W01–W05):

Backfill một lần (nếu sổ trống) — ghi mọi skill hiện có là tự viết:
bash
```
python3 fdk/tools/skill-provenance.py record --all --source local-authored
```

Khi cài / thêm skill mới — ghi nguồn thật (URL,

repo#ref

, hoặc

local-authored

bash

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

Kiểm toàn vẹn bất cứ lúc nào (in OK / MODIFIED / UNTRACKED / MISSING):

bash

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

Gate CI — exit 1 nếu có MODIFIED hoặc UNTRACKED (đã gắn trong

.github/workflows/skills-sync.yml

bash

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

Sau khi cố ý sửa một skill, chạy lại
```
record <name> --source <nguồn cũ>
```
để cập nhật checksum — nếu không,
```
check --ci
```
sẽ báo MODIFIED (đúng: mọi thay đổi phải qua sổ).

Branches

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	conditional_required	sổ trống	backfill W01	sổ đã có → skip	W03
B02	recovery	`check` báo MODIFIED	sửa có chủ đích → W05 re-record; không rõ ai sửa → điều tra như sửa lạ	—	W03
B03	recovery	`check` báo UNTRACKED	skill mới hợp lệ → W02 record với nguồn thật	nguồn không rõ → clarify	W03

Validation và stopping

Hoàn toàn tất định: checksum + exit code của

skill-provenance.py

. Phần cần người: nguồn

--source

có thật không. Dừng khi

check

in toàn OK (MISSING chấp nhận).

Examples

Positive: vừa kéo skill từ

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

in OK.

Boundary/failure: sửa
```
skills/foo/SKILL.md
```
mà không re-record →
```
check --ci
```
in MODIFIED foo, exit 1; user hỏi "foo từ đâu" nhưng không ai biết → không ghi
```
--source
```
đoán, hỏi lại.

skill-provenance

NPX Install

Tags

SKILL.md Content

Skill: skill-provenance

WHAT

Purpose và context

Mental model

Input và output contract

Rules và capabilities

Failure boundaries

HOW

Main workflow

Branches

Validation và stopping

Examples