昨日回顧

Day 22 整理了 eval 案例的來源與版本。今天換到第一次看到專案的人：他不需要先讀完我們的全部測試，卻需要知道這支 Skill 做什麼、何時不能相信結果，以及怎麼開始。

GitHub 文件把 README 定位為介紹專案、開始使用與取得協助的入口。對 ticket-source-guard，README 的目標不是把所有細節塞進首頁，而是讓讀者走完一次最小、安全、可重現的使用路徑。

第一屏先說清楚能力與限制

ticket-source-guard
依照已登錄的來源證據、host 邊界與有效日期，分類購票 URL。
它不保證票券真偽，不代表交易授權，也不會替你付款。
證據過期、撤銷或衝突時，回傳待重驗或衝突狀態。

這比「AI 自動辨識所有官方網站」準確。名稱、三句能力說明、支援環境與限制，放在安裝指令之前。若只做靜態檢查，就不要讓讀者以為已跑過原生 agent 或即時網站。

安裝與執行分開寫

安裝檔案成功不等於任務成功。README 應分開列出：

安裝：檔案放在哪裡，如何移除，是否會覆蓋既有檔案
需求：執行環境、依賴、網路與工具權限
執行：使用什麼輸入，呼叫哪支 script 或哪條任務路徑
驗證：成功時應看見什麼，失敗時如何退出

以下只是示意介面，script 名稱與參數要依真實實作調整；不要把它描述成已發布、可直接安裝的產品。

python scripts/check_domain.py \
  --url https://tickets.example.test/event/42 \
  --registry tests/fixtures/registry-stale.json \
  --evaluation-date 2026-10-04

這個範例只讀 fixture，不會抓真實網站，也不會付款。先讓讀者在不需要私人資料或 API key 的條件下重現一次結果。

範例要同時有輸入與解讀

{
  "status": "UNCONFIRMED",
  "normalized_host": "tickets.example.test",
  "next_step": "REVALIDATE"
}

範例輸出是縮減的示意，不取代正式 schema。重點是解釋 UNCONFIRMED 不代表已證實詐騙，也不代表可以購買；它表示目前沒有足夠且有效的證據確認。OFFICIAL 也只表示符合來源判定契約，不是交易安全的全面保證。

列出常見失敗，別只展示成功

缺日期：要求補入固定評估日期，不用執行日默默代替
registry 無法讀取：回報設定錯誤，不建立空清單假裝成功
證據過期：要求重驗，不把舊 evidence_url 當成現在有效
來源衝突：保留衝突，不選看起來比較像官方的一筆

真正的 README 要對應 Day 13 的精確狀態名稱與退出碼。錯誤訊息若能指到設定或 fixture，讀者就不需要猜是安裝壞了還是輸入不足。

README 與 SKILL.md 不要搶同一份工作

README 寫給人：目的、安裝、範例、限制、求助與授權。SKILL.md 寫給任務執行路徑：觸發條件、步驟、必要 reference、script 與停止政策。兩者共享規格，但不要各自維護一套互相矛盾的狀態定義。

用相對連結指向 references/、測試與貢獻指南，再在 CI 檢查連結和檔案存在。GitHub 支援 repository 內的相對連結，這能讓文件在不同分支仍指向對應版本。

demo 要忠於真正發生的事

GIF 或截圖可以讓人快速看懂，但要標明環境、版本與 fixture。顯示「輸入 → 執行 → 輸出 → 狀態解讀」，不要只放一個綠色成功畫面。若是模擬輸出，就寫「示意」，不要剪成像真實執行。

上傳前檢查終端、瀏覽器與路徑裡有沒有 token、cookie 或私人內容。為了教學好看，不值得把秘密放進 repository。

今天完成的驗收標準

[ ] 第一屏交代任務、範圍與不保證的事
[ ] 安裝、需求、執行與驗證分開
[ ] 最小範例不需要私人資料且能對應實作
[ ] 輸出包含狀態解讀與失敗處理
[ ] README 與 SKILL.md 共用同一套契約
[ ] demo 有版本、fixture 與敏感資料檢查

參考資料
https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes

明天預告

Day 24 整理發行包、文件版本與 CHANGELOG，讓別人安裝到的內容和我們驗證過的內容是同一份。