hf-sync — 本機 HF 資料集鏡像同步
graph.jsonld 研究倉庫的 HF 資料集鏡像，可從本機端一條指令完成同步。此技能為 jsonld-knowledge-graph 的操作層，將編碼後的圖譜反映到 HF Datasets 上的鏡像。
使用時機
release-doi的 Phase 5 末尾，在gh release create之後執行 HF 鏡像同步- 對圖譜進行臨時修改後，進行即時重新同步（不發布新版本，僅更新 HF 端）
- 輪換 HF Token 後的連線驗證
不應使用的情況
- 專案中沒有
graph.jsonld（HF 鏡像不存在） - HF 資料集本身尚未建立（請先使用
hf repo create <Owner/dataset> --repo-type dataset建立儲存庫） - HF 克隆目錄 (
$HF_CLONE_BASE/<dataset>/) 不存在（請先使用mkdir -p ~/MyAI_Lab/hf-datasets/<dataset>建立暫存目錄。HF 端的README.md與歷史快照會放置於此） - 尚未執行
hf login或 token 不具備寫入權限（請先使用hf auth login重新設定 token）
執行方式
bash ~/.claude/skills/hf-sync/sync.sh $ARGUMENTS
$ARGUMENTS 為 HF 資料集的儲存庫 ID（例如 Shimo4228/agent-knowledge-cycle）。
工作目錄限制：請在 graph.jsonld 所在的專案根目錄執行。
功能說明
- 檢查目前目錄下
graph.jsonld的結構完整性（@graph必須為非空陣列） - 將來源端的
graph.jsonld複製到 HF 克隆目錄 ($HF_CLONE_BASE/<dataset>/，預設為~/MyAI_Lab/hf-datasets/<dataset>/) 中 - 在 HF 克隆端使用
jq -c '.["@graph"][]' graph.jsonld > graph.jsonl產生 HF Dataset Viewer 適用的扁平化格式（每個節點一行） hf upload <Owner/dataset> <hf-clone>/graph.jsonld graph.jsonld --repo-type datasethf upload <Owner/dataset> <hf-clone>/graph.jsonl graph.jsonl --repo-type dataset- 顯示成功訊息與 HF 連結
不會汙染來源儲存庫：graph.jsonl 僅在 HF 克隆端產生與存在，不會留在來源端的 Git 樹中。
驗證機制依賴 ~/.cache/huggingface/token（透過 hf login 儲存），hf CLI 會自動讀取。
儲存庫對應
每個專案的 GitHub 儲存庫與 HF 資料集的對應關係因專案而異。此技能本身不嵌入對應資訊（以保持可移植性）。請將對應關係記錄在專案的 CLAUDE.md 或類似文件中，啟動時以複製貼上的方式作為參數傳入。
shimo4228 系列的現行對應關係請參閱 ~/MyAI_Lab/shimo4228/CLAUDE.md 中的「HF Datasets mirror」小節。
相關技能
jsonld-knowledge-graph—graph.jsonld的設計層。本技能對應於其操作鏡像層release-doi— Zenodo DOI 發布流程。在 Phase 5 末尾會呼叫本技能
常見失敗模式
- 目前目錄找不到
graph.jsonld→ 請移至專案根目錄後再啟動 - HF 克隆目錄不存在 → 使用
mkdir -p $HF_CLONE_BASE/<dataset>/建立暫存目錄（若 HF 端已有現有檔案，需手動下載放置，或使用hf download <Owner/dataset> --local-dir <hf-clone>進行初始同步） @graph不是陣列或為空 → 請檢查graph.jsonld的結構（參見jsonld-knowledge-graph技能）hf upload回傳 401 / 403 → 使用hf auth whoami確認 token 狀態。若無寫入權限，請在 HF Settings 中重新發行 token 並執行hf auth login- HF 資料集儲存庫不存在 (404) → 請先使用
hf repo create <Owner/dataset> --repo-type dataset建立儲存庫