---
name: comfyui_save_skill
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: impure
signature: "def comfyui_save_skill(recipe: dict, *, library_dir: str = None) -> dict"
description: "Persiste una receta de skill ComfyUI (schema comfyui-skill) en la libreria de disco: valida el schema minimo y escribe <library_dir>/<slug>/recipe.json + un snapshot inmutable versions/vN.json (N incremental) + bitacora growth_log.jsonl + regenera INDEX.md. No muta la receta (round-trip identico con comfyui_load_skill). library_dir default ~/ComfyUI/skills_library. Devuelve dict {ok, slug, path, version_file, n_versions, error}; nunca lanza."
error_type: error_go_core
tags: [comfyui, comfyui-skill, ml, skill, library, persistence]
uses_functions: []
uses_types: []
params:
  - name: recipe
    desc: "Dict de la receta (schema comfyui-skill). Requiere al menos slug, base_workflow y version (strings no vacios). No se muta."
  - name: library_dir
    desc: "Raiz de la libreria en disco. Default ~/ComfyUI/skills_library. keyword-only."
output: "dict {ok, slug, path, recipe_path, version_file, n_versions, error}. En error de validacion o escritura ok=False y error describe la causa."
file_path: python/functions/ml/comfyui_save_skill.py
---

# comfyui_save_skill

Escribe una receta de skill en la libreria de disco con versionado por snapshots. Parte del CRUD
del grupo `comfyui-skill` ([`comfyui_load_skill`](comfyui_load_skill.md),
[`comfyui_list_skills`](comfyui_list_skills.md)).

## Ejemplo

```python
import sys, os
sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions"))
from ml.comfyui_save_skill import comfyui_save_skill

recipe = {
    "schema_version": 1, "slug": "portrait_cinematic_sdxl", "version": "1.0.0",
    "title": "Retrato cinematográfico SDXL", "base_workflow": "txt2img",
    "checkpoint": "juggernaut_xl_v11.safetensors",
    "params": {"steps": 30, "cfg": 5.5, "sampler_name": "dpmpp_2m", "scheduler": "karras"},
    "prompt_scaffold": {"positive": "cinematic portrait of {subject}", "negative": "blurry",
                        "trigger_words": []},
    "provenance": {"source": "manual", "nsfw": False},
}

res = comfyui_save_skill(recipe, library_dir="/tmp/skills_demo")
# {'ok': True, 'slug': 'portrait_cinematic_sdxl', 'n_versions': 1,
#  'version_file': '/tmp/skills_demo/portrait_cinematic_sdxl/versions/v1.json', ...}
```

O directo: `./fn run comfyui_save_skill` (guarda una skill demo en /tmp/skills_demo).

## Cuando usarla

- Cuando crees o actualices una receta de skill y quieras persistirla con versionado. Cada save
  escribe un snapshot nuevo `versions/vN.json` además de actualizar `recipe.json`, así que el
  historial queda intacto.
- Tras ajustar params/loras/blocks de una skill que iterabas: guárdala para reproducirla luego
  con `comfyui_load_skill` + `comfyui_build_skill_workflow`.

## Gotchas

- **No muta la receta**: lo escrito en `recipe.json` es idéntico al dict de entrada (garantiza el
  round-trip con `comfyui_load_skill`). No rellena defaults ni reordena.
- **Validación mínima**: exige `slug`, `base_workflow` y `version` (strings no vacíos); el `slug`
  no puede contener separadores de ruta ni empezar por `.`. No valida la semántica completa del
  workflow (eso lo hace `comfyui_build_skill_workflow` al compilar).
- **`n_versions` cuenta los snapshots existentes + 1**: guardar la misma skill dos veces crea
  `v1.json` y `v2.json`; `recipe.json` siempre apunta a la última.
- **No lanza excepción**: errores (validación, permisos de escritura) salen como `{ok: False, error: ...}`.
- **Escribe bajo `~/ComfyUI/skills_library` por defecto** (carpeta de metadata, no toca el venv
  ni los modelos). Para tests/uso aislado pasa un `library_dir` propio.