昨日回顧

Day 23 寫了可使用的 README。今天問一個更直接的問題：讀者拿到的，真的是我們測過的那份 Skill 嗎？如果測試跑在 commit A，下載頁卻指向不斷變動的 main，文件又描述下一版，安裝成功也不代表一致。

本文是 ticket-source-guard 的發行設計，不表示已經建立公開 release 或安裝驗證。

先劃清發行內容

Agent Skills 規格要求 skill 目錄包含 SKILL.md，並可帶 scripts、references 與 assets。對我們的範例，發行包至少要能找回指令引用的程式與規格。

ticket-source-guard/
  SKILL.md
  scripts/check_domain.py
  references/output-schema.json
  references/freshness-policy.md
  assets/registry.example.json
  README.md
  CHANGELOG.md
  LICENSE

這是建議結構，不是說規格強制所有專案都附這些檔案。不要把私人 registry、暫存結果、cookie 或本機環境設定打包。測試資料是否公開，也要依 Day 22 的來源與授權紀錄判斷。

把版本連到具體證據

發行標識：v0.4.0（示意）
來源：固定 commit SHA
測試：eval-set-4，固定評估日期與設定
內容：檔案清單與各檔 digest
文件：同一版 README、狀態契約與相容性表

tag 是方便閱讀的名字，commit 是來源定位，digest 是內容比對。只留下其中一個，仍可能不知道下載包是否少了檔案或與測試來源不同。正式發行時保留整個對照紀錄。

從乾淨目錄檢查發行包

Day 18 已經討論安裝環境。這次不要直接在開發目錄跑測試，因為那裡可能有未提交檔案替你補洞。

1. 從候選 commit 產生發行包
2. 解開到空目錄
3. 核對清單、digest 與相對路徑
4. 在這份內容上跑 schema、smoke test 與任務型 eval
5. 檢查 README 的範例能對應這份內容
6. 驗證完成後才指向公開發行入口

如果實際 installer 會轉換目錄或複製檔案，再檢查安裝後的結果，而不是只檢查原始包。不要宣稱「支援某 agent」，卻只看它的資料夾名稱存在。

安裝工具不是安全認證

Vercel 的 skills CLI 文件提供 npx skills add 等安裝路徑，也支援列出與選擇 skill。這是分發工具，不代表被安裝的內容已通過安全、品質或相容性審查。

不要把範例專案寫成真實發布地址。等 repository、版本與可用的來源格式都確認後，才把實際安裝指令放進 README，並在乾淨環境測試。第三方 CLI 的版本和行為也可能變更，因此記錄測試過的版本與命令，不把一次成功當成永久保證。

CHANGELOG 寫對使用者有影響的變更

v0.4.0（示意，未發布）
Changed：過期證據一律要求重驗
Fixed：host 邊界比對漏掉額外 suffix
Migration：舊 registry 缺 review_after 時需補欄位
Validation：新增兩筆回歸案例，完整 eval 結果另附
Known limits：不驗證票券真偽、不執行付款

不要只貼 commit 標題清單。讀者需要知道輸出是否改變、舊設定是否還能用、怎麼升級與怎麼回退。資料相容性破壞要明講，不能藏在「小修正」裡。

文件也需要版本邊界

README 的 quick start 指向同版規格；下一版草稿放在清楚標示的位置。文件站如果同時保留多個版本，讓讀者看得出目前讀的是哪一版。修錯字不一定要重新發行程式，但涉及契約、輸出或安裝行為的文件修改，要重新檢查相應案例。

今天完成的驗收標準

[ ] 發行包沒有私人資料、暫存檔或未提交依賴
[ ] tag、commit、清單、digest 與 eval 報告可對照
[ ] 空目錄與安裝後內容都核對過
[ ] 安裝方式與相容性宣稱都有實際驗證範圍
[ ] CHANGELOG 說明影響、遷移與已知限制
[ ] 文件描述的是同一份發行內容

參考資料
https://agentskills.io/specification
https://github.com/vercel-labs/skills?tab=readme-ov-file

明天預告

Day 25 整理對外索引與回報入口：被找到不等於被認證，公開資訊也要保留版本、限制與可重現的錯誤紀錄。