shimo4228/claude-harness

hf-sync — 로컬 HF Dataset 미러 동기화

graph.jsonld를 가진 research repo의 HF dataset 미러를 로컬에서 한 명령으로 동기화하는 스킬입니다. jsonld-knowledge-graph로 인코딩된 그래프를 HF Datasets 상의 미러에 반영하는 운영 레이어입니다.

사용 시기

• release-doi의 Phase 5 마지막, gh release create 이후 HF 미러 반영
• 그래프를 직접 수정한 후 임시 재동기화(릴리스를 만들지 않고 HF만 업데이트하려는 경우)
• HF 토큰을 교체한 후 동작 확인

사용하지 말아야 할 경우

• graph.jsonld가 없는 repo(HF 미러가 존재하지 않음)
• HF dataset 자체가 아직 생성되지 않은 프로젝트(먼저 hf repo create <Owner/dataset> --repo-type dataset으로 repo를 만듦)
• HF clone 디렉터리($HF_CLONE_BASE/<dataset>/)가 존재하지 않음(먼저 mkdir -p ~/MyAI_Lab/hf-datasets/<dataset>으로 스테이징 디렉터리를 생성. HF 측의 README.md와 과거 스냅샷이 여기에 위치)
• hf login하지 않았거나 토큰에 write 스코프가 없음(먼저 hf auth login으로 토큰 재입력)

실행

bash ~/.claude/skills/hf-sync/sync.sh $ARGUMENTS

$ARGUMENTS는 HF dataset의 repo ID입니다(예: Shimo4228/agent-knowledge-cycle).

cwd 제약: graph.jsonld가 존재하는 프로젝트 루트에서 실행해야 합니다.

동작 방식

1. cwd의 graph.jsonld 구조적 정합성 검사(@graph가 배열이고 비어 있지 않음)
2. 소스 graph.jsonld를 HF clone 디렉터리($HF_CLONE_BASE/<dataset>/, 기본값 ~/MyAI_Lab/hf-datasets/<dataset>/)로 복사
3. HF clone 측에서 jq -c '.["@graph"][]' graph.jsonld > graph.jsonl 생성(HF Dataset Viewer용 노드당 1행 평탄화)
4. hf upload <Owner/dataset> <hf-clone>/graph.jsonld graph.jsonld --repo-type dataset
5. hf upload <Owner/dataset> <hf-clone>/graph.jsonl graph.jsonl --repo-type dataset
6. 성공 로그 + HF URL 표시

소스 repo를 오염시키지 않음: graph.jsonl은 HF clone 측에서만 생성·존재하며, 소스의 git tree에는 남지 않습니다.

인증은 ~/.cache/huggingface/token에 저장된 것(hf login으로 저장)을 hf CLI가 자동으로 읽습니다.

Repo 매핑

각 프로젝트의 GitHub repo와 HF dataset 간의 대응은 프로젝트마다 다릅니다. 스킬 본체에는 포함하지 않음(이식성 유지). 매핑은 프로젝트의 CLAUDE.md 또는 동등한 위치에 기록해 두고, 실행 시 복사하여 인수로 전달합니다.

shimo4228 계열의 현재 매핑은 ~/MyAI_Lab/shimo4228/CLAUDE.md의 "HF Datasets mirror" 섹션을 참조하세요.

관련 스킬

• jsonld-knowledge-graph — graph.jsonld의 설계 레이어. 본 스킬은 그 운영 미러에 해당
• release-doi — Zenodo DOI 릴리스 플로우. Phase 5 마지막에서 본 스킬 호출

실패 모드

• cwd에 graph.jsonld가 없음 → 프로젝트 루트로 이동한 후 실행
• HF clone 디렉터리가 없음 → 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로 토큰 확인. write 스코프가 없으면 HF 설정에서 새로 발급 → hf auth login
• HF dataset repo가 존재하지 않음(404) → 먼저 hf repo create <Owner/dataset> --repo-type dataset으로 repo 생성