shimo4228/claude-harness

hf-sync — Sincronización de Mirror Local de Dataset HF

Skill para sincronizar con un solo comando el mirror del dataset HF de un repositorio de investigación que tenga graph.jsonld. Es la capa operativa que refleja el grafo codificado con jsonld-knowledge-graph en el mirror de HF Datasets.

Cuándo usarlo

• Al final de la Fase 5 de release-doi, después de gh release create, para reflejar el mirror HF.
• Resincronización ad-hoc justo después de modificar el grafo (sin hacer un release, solo actualizar HF).
• Verificación de funcionamiento después de rotar el token HF.

Cuándo NO usarlo

• Repositorio que no tenga graph.jsonld (no existe mirror HF).
• Proyecto donde aún no se haya creado el dataset HF (primero crear el repo con hf repo create <Owner/dataset> --repo-type dataset).
• No existe el directorio de clon HF ($HF_CLONE_BASE/<dataset>/). Primero crear el directorio de staging con mkdir -p ~/MyAI_Lab/hf-datasets/<dataset>. Allí se colocarán el README.md y las instantáneas anteriores de HF.
• No se ha ejecutado hf login o el token no tiene alcance de escritura (primero volver a autenticar con hf auth login).

Ejecución

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

$ARGUMENTS es el ID del repositorio del dataset HF (ejemplo: Shimo4228/agent-knowledge-cycle).

Restricción de cwd: Ejecutar desde la raíz del proyecto donde exista graph.jsonld.

Qué hace

1. Verificación estructural de graph.jsonld en cwd (@graph debe ser un array no vacío).
2. Copia el graph.jsonld de origen al directorio de clon HF ($HF_CLONE_BASE/<dataset>/, por defecto ~/MyAI_Lab/hf-datasets/<dataset>/).
3. En el lado del clon HF, genera graph.jsonl con jq -c '.["@graph"][]' graph.jsonld > graph.jsonl (aplanado: 1 nodo por línea para el visor de HF Dataset).
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. Muestra el log de éxito y la URL de HF.

El repositorio de origen no se ensucia: graph.jsonl solo se genera y existe en el lado del clon HF; no queda en el árbol git de origen.

La autenticación utiliza ~/.cache/huggingface/token (guardado con hf login) que la CLI hf lee automáticamente.

Mapeo de repositorios

La correspondencia entre el repositorio GitHub de cada proyecto y su dataset HF varía por proyecto. No se incrusta en el skill en sí (para mantener la portabilidad). El mapeo se registra en el CLAUDE.md del proyecto o en un lugar equivalente, y se pasa como argumento al iniciar.

Para los proyectos shimo4228, consultar la sección "HF Datasets mirror" en ~/MyAI_Lab/shimo4228/CLAUDE.md.

Skills relacionados

• jsonld-knowledge-graph — Capa de diseño de graph.jsonld. Este skill corresponde a su mirror operativo.
• release-doi — Flujo de publicación DOI de Zenodo. Al final de la Fase 5 invoca este skill.

Modos de falla

• graph.jsonld no encontrado en cwd → Moverse a la raíz del proyecto antes de ejecutar.
• Directorio de clon HF no encontrado → Crear el directorio de staging con mkdir -p $HF_CLONE_BASE/<dataset>/. Si HF ya tiene archivos existentes, descargarlos manualmente o hacer una sincronización inicial con hf download <Owner/dataset> --local-dir <hf-clone>.
• @graph no es array / está vacío → Revisar la estructura de graph.jsonld (consultar el skill jsonld-knowledge-graph).
• hf upload 401 / 403 → Verificar el token con hf auth whoami. Si no tiene alcance de escritura, generar uno nuevo en la configuración de HF y autenticar con hf auth login.
• El repositorio del dataset HF no existe (404) → Crear el repositorio primero con hf repo create <Owner/dataset> --repo-type dataset.