skills-here-run-place/PLAN.md

Plan: Soporte de Skills en formato carpeta (Folder-based resources)

Contexto

El PDF oficial de Anthropic define que una skill puede ser una carpeta con subdirectorios:

my-skill/
├── SKILL.md          # Requerido
├── scripts/          # Opcional - codigo ejecutable
├── references/       # Opcional - documentacion
└── assets/           # Opcional - plantillas, fuentes, iconos

Actualmente Skillit almacena cada recurso como un unico .md en data/<type>/<slug>.md. Queremos soportar ambos formatos: simple (archivo .md) y carpeta (directorio con SKILL.md + subdirectorios).

Archivos a modificar

Archivo	Cambio
src/lib/registry.ts	Agregar mainFileName por tipo y constante FOLDER_SUBDIRS
src/lib/resources.ts	Reescribir CRUD para detectar/manejar ambos formatos; nuevas funciones para sub-archivos
src/lib/skills.ts	Actualizar interfaz Skill con format y files
src/lib/sync.ts	Scripts de sync/push con soporte carpeta
src/pages/api/resources/[type]/index.ts	Aceptar format en POST
src/pages/api/resources/[type]/[slug].ts	Manejar carpeta en GET
src/pages/[type]/[slug].astro	Mostrar arbol de archivos
src/pages/[type]/[slug]/edit.astro	Pasar format/files al editor
src/pages/[type]/new.astro	Soporte selector de formato
src/pages/[type]/[slug]/i.ts	Install scripts multi-archivo
src/pages/[type]/[slug]/gi.ts	Install global multi-archivo
src/components/ResourceEditor.vue	Toggle formato + integrar FileManager

Archivos nuevos

Archivo	Proposito
src/pages/api/resources/[type]/[slug]/files/index.ts	Listar y subir sub-archivos
src/pages/api/resources/[type]/[slug]/files/[...filePath].ts	CRUD individual de sub-archivos
src/components/FileManager.vue	Componente Vue para gestionar sub-archivos
src/components/FolderTree.astro	Componente Astro para mostrar arbol de archivos en detalle

Fases de implementacion

Fase 1: Registry (registry.ts)

Agregar campo mainFileName a ResourceTypeConfig:

• skills: SKILL.md
• agents: AGENT.md
• output-styles: OUTPUT-STYLE.md
• rules: RULE.md

Agregar constante FOLDER_SUBDIRS = ['scripts', 'references', 'assets'].

Fase 2: Core CRUD (resources.ts)

Cambios principales:

1. Nuevos tipos:

   • ResourceFormat = 'file' | 'folder'
   • ResourceFileEntry = { relativePath: string; size: number }
   • Agregar format y files a interfaz Resource

2. resolveResource(type, slug) (nueva): detecta si el recurso es archivo o carpeta. Carpeta tiene prioridad si ambos existen.

3. listResources(type): escanear tanto *.md como directorios con el mainFileName.

4. getResource(type, slug): usar resolveResource, leer mainFile, listar sub-archivos si es carpeta.

5. createResource(type, slug, content, format?): parametro format opcional (default 'file'). Si 'folder', crear directorio y escribir mainFileName.

6. updateResource(type, slug, content): auto-detectar formato, escribir en la ruta correcta.

7. deleteResource(type, slug): auto-detectar. Para carpeta usar fs.rm(dirPath, { recursive: true }).

8. Funciones nuevas para sub-archivos:

   • listResourceFiles(type, slug) - listar archivos auxiliares
   • getResourceFile(type, slug, relativePath) - leer sub-archivo (Buffer)
   • addResourceFile(type, slug, relativePath, data: Buffer) - escribir sub-archivo
   • deleteResourceFile(type, slug, relativePath) - eliminar sub-archivo
   • convertToFolder(type, slug) - convertir simple a carpeta

9. Seguridad: validar que relativePath no contenga .., solo permita rutas dentro de FOLDER_SUBDIRS.

Fase 3: API de sub-archivos

/api/resources/[type]/[slug]/files/index.ts:

• GET: lista sub-archivos (JSON)
• POST: subir archivo via multipart/form-data

/api/resources/[type]/[slug]/files/[...filePath].ts:

• GET: descargar sub-archivo
• PUT: subir/reemplazar sub-archivo
• DELETE: eliminar sub-archivo

Modificar /api/resources/[type]/index.ts:

• POST acepta format: 'file' | 'folder' opcional

Fase 4: Pagina de detalle ([type]/[slug].astro)

• Comprobar resource.format
• Para carpeta: renderizar seccion "Files" con FolderTree.astro
• El raw markdown (para curl) sigue devolviendo solo el mainFile

FolderTree.astro: componente que muestra arbol de archivos con links de descarga.

Fase 5: Editor UI

ResourceEditor.vue:

• Nuevos props: initialFormat, files
• Toggle formato al crear (Simple / Carpeta)
• Seccion FileManager al editar recurso tipo carpeta

FileManager.vue (nuevo componente Vue):

• Lista archivos con boton eliminar
• Boton subir: selector de subdirectorio (scripts/references/assets) + file input
• Llamadas fetch a la API de files

Fase 6: Scripts de instalacion

[type]/[slug]/i.ts y gi.ts:

• Para formato carpeta: generar script que crea estructura de directorios y descarga cada archivo
• URLs de sub-archivos: ${origin}/api/resources/${type}/${slug}/files/${relativePath}
• chmod +x para archivos en scripts/

sync.ts:

• Sync: detectar formato por recurso, generar descarga multi-archivo
• Push: iterar tanto *.md como directorios; subir main content + sub-archivos

Fase 7: Backward compat (skills.ts)

Actualizar interfaz Skill con format y files. El wrapper sigue delegando a resources.ts.

Orden de implementacion

1. Fase 1 (registry) - base
2. Fase 2 (resources.ts CRUD) - critico
3. Fase 3 (API sub-archivos)
4. Fase 4 (pagina detalle)
5. Fase 5 (editor UI)
6. Fase 6 (scripts instalacion)
7. Fase 7 (backward compat)

Verificacion

1. Crear un skill simple (test-simple) via web - verificar que funciona como antes
2. Crear un skill carpeta (test-folder) via web - verificar que se crea directorio con SKILL.md
3. Subir archivos a scripts/ y references/ del skill carpeta via FileManager
4. Ver pagina de detalle - verificar arbol de archivos
5. Ejecutar script de instalacion (curl .../skills/test-folder/i | bash) - verificar descarga completa
6. Verificar que listado muestra ambos formatos correctamente
7. Editar ambos formatos - verificar que se actualizan
8. Eliminar ambos formatos - verificar limpieza