JMBargueno/skanvil

¿Qué hace skanvil?

Objetivo

Cambiar bibliotecas de skills a través de la CLI skanvil, de modo que las carpetas de skills, el frontmatter de SKILL.md, el índice README y las convenciones de la biblioteca se mantengan consistentes y la validación se mantenga en verde.

Cuándo Activar Este Skill

• El repositorio tiene un .skanvilrc.json, una carpeta skills/ con archivos SKILL.md, o skanvil en su package.json.
• El usuario pide agregar, escribir, renombrar, mover, re-titular, re-describir, eliminar, listar, validar o indexar skills.
• skanvil validate, npm test o CI falla con diagnósticos de skanvil.
• El usuario quiere que los skills de una biblioteca estén disponibles para Claude Code, GitHub Copilot o Codex en otro proyecto.

Instrucciones

1. Oriéntate

1. Lee .skanvilrc.json. Define las categorías (id, prefijo de carpeta prefix, título del README title, aliases), las secciones requeridas, los marcadores de posición y las severidades de las reglas. Si falta el archivo, se usa el preset predeterminado: front-, back-, transversal sin prefijo (el predeterminado) y _internal.
2. Ejecuta npx skanvil list --json para ver cada skill con su categoría, presencia en README y validez.
3. Ejecuta npx skanvil validate --json antes de cambiar cualquier cosa, para saber qué problemas ya existían.

2. Reglas de oro

• Nunca renombres, muevas o elimines carpetas de skills manualmente, y nunca edites manualmente el índice README. Usa skanvil edit, que mantiene sincronizados la carpeta, el name del frontmatter, el # heading y la entrada del README, y revierte los cambios si falla.
• Nunca crees carpetas de skills manualmente. Usa skanvil add, que aplica el prefijo de categoría, la plantilla, los metadatos del frontmatter y la entrada del README.
• Pasa siempre todas las opciones en shells no interactivos. add necesita --type, --name y --description. edit --remove necesita --yes. De lo contrario, el comando solicita entrada o falla sin un TTY.
• Nunca ejecutes skanvil sin argumentos o skanvil wizard. Abren un menú interactivo pensado para humanos. Usa los comandos explícitos a continuación. Si el usuario prefiere menús, sugiérele que ejecute npx skanvil por sí mismo.
• Agrega --json cuando necesites analizar la salida. Los datos van a stdout; las advertencias y errores van a stderr.
• Ejecuta npx skanvil validate después de cada cambio y termina sin errores. El código de salida 1 significa errores, o advertencias cuando se usa --strict.
• Antepón npx a cada comando a menos que skanvil esté en PATH. Usa -C <ruta> para apuntar a una biblioteca en otra carpeta.

3. Tareas comunes

Crear un skill y luego escribir su contenido.

npx skanvil add --type <categoría> --name "<nombre corto>" \
  --description "<qué hace>. Úsalo cuando <situaciones desencadenantes>."

Luego edita skills/<prefijo><nombre>/SKILL.md:

• Completa cada sección requerida con contenido concreto y procesable.
• Reemplaza todas las oraciones genéricas de la plantilla. Hasta que lo hagas, validate reporta una advertencia template-unchanged, y validate --strict (el npm test de la biblioteca) falla.
• Mueve material largo a references/, y enlaza solo a archivos que existan (broken-references).

Usa --no-scripts, --no-assets o --no-references cuando esas carpetas vayan a estar vacías. Usa --template <nombre> para una plantilla personalizada en .skanvil/templates/.

Renombrar o mover un skill.

npx skanvil edit <skill> --rename <nuevo-nombre>          # el prefijo se re-aplica automáticamente
npx skanvil edit <skill> --type <otra-categoría>          # nuevo prefijo, sección README, metadatos
npx skanvil edit <skill> --title "<Título>" --description "<texto>"

--rename toma el nombre base: edit front-a --rename b da front-b.

Eliminar un skill. Confírmalo primero con el usuario; esto es permanente.

npx skanvil edit <skill> --remove --yes

Corregir errores de validación.

1. Ejecuta npx skanvil doctor --fix. Repara entradas de README, discrepancias de name, tabulaciones en el frontmatter y convierte tools a allowed-tools.
2. Arregla lo que quede editando SKILL.md. Usa la tabla de diagnóstico a continuación.
3. Ejecuta npx skanvil validate de nuevo.

Reconstruir el índice README después de cambiar los títulos de categorías en .skanvilrc.json:

npx skanvil index          # reescribe las secciones del índice
npx skanvil index --check  # solo verificar (CI)

Instalar los skills en un proyecto.

npx skanvil sync <directorio-proyecto> -C <directorio-biblioteca> --target claude,copilot --dry-run   # vista previa
npx skanvil sync <directorio-proyecto> -C <directorio-biblioteca> --target claude,copilot
npx skanvil sync --from @scope/package --target agents                             # paquete instalado

Destinos:

• claude instala en .claude/skills;
• copilot instala en .github/skills;
• agents y codex instalan en .agents/skills.
• Una ruta personalizada debe ser una carpeta dentro del proyecto.
• --global (sin directorio de proyecto) instala en ~/.claude/skills, ~/.copilot/skills o ~/.agents/skills del usuario. Úsalo solo cuando el usuario pida skills disponibles en todos los proyectos.

Cómo se comporta sync:

• Nunca sobrescribe carpetas que no instaló.
• Elimina skills que se hayan quitado de la biblioteca.
• Omite skills con errores de validación a menos que se dé --force.
• Nunca publica skills _internal.

Agregar o cambiar categorías. Edita categories en .skanvilrc.json:

• exactamente una categoría tiene "default": true y sin prefijo;
• cada otra categoría tiene un prefijo que es _ o kebab-case terminado en -;
• ningún prefijo puede comenzar con otro prefijo.

Luego mueve los skills existentes con edit --type, y ejecuta skanvil index.

4. Escribe buen contenido de skill

• description dice qué hace el skill y cuándo usarlo, con las palabras clave desencadenantes que vería un agente. Debe tener como máximo 1024 caracteres.
• name es igual al nombre de la carpeta: letras minúsculas, dígitos y guiones simples, como máximo 64 caracteres.
• Cuerpo: mantén SKILL.md por debajo de 500 líneas. Escribe instrucciones como pasos numerados y verificables, y pon ejemplos, casos límite y listas de verificación largas en references/ (un nivel de profundidad).
• Marcadores de posición: nunca dejes texto de relleno. Cualquier entrada de validation.placeholders (marcadores de tareas pendientes, texto en latín falso, notas "por decidir") falla la validación.
• metadata: solo valores de cadena, así que cita números, como en version: "1.0".
• allowed-tools: una cadena separada por espacios, no una lista.

5. Diagnóstico → corrección

Regla	Corrección
readme-missing, readme-orphan, readme-section	npx skanvil doctor --fix
name-matches-folder, name-required	doctor --fix, o edit --rename si el nombre de la carpeta está mal
frontmatter-tabs, tools-field	doctor --fix
frontmatter	Repara el YAML entre las líneas --- (cita valores que contengan : o #).
required-sections	Agrega la ## Sección faltante listada en validation.requiredSections.
placeholders	Reemplaza el texto marcador de posición con contenido real.
description-length, max-lines	Acorta; mueve los detalles a references/.
metadata-format	Cita valores que no sean cadenas.
duplicate-name	Dos carpetas comparten un name: renombra una con edit --rename.
broken-references	Crea el archivo referenciado, o arregla el enlace (las rutas son relativas al skill).
template-unchanged	Reescribe las oraciones genéricas de la plantilla con instrucciones específicas del skill.

Consulta references/REFERENCE.md para cada opción de comando, el esquema de configuración y las formas de salida JSON.

Formato de Salida

Informa al usuario:

• los comandos skanvil que ejecutaste;
• los skills creados, cambiados o eliminados, con sus nombres de carpeta;
• el resultado final de skanvil validate (errores y advertencias), y cualquier cosa que quede para que él decida.

Criterios de Calidad

• Cada cambio estructural se realizó a través de skanvil add o skanvil edit. No hay renombres de carpetas hechos a mano ni ediciones manuales del índice README.
• npx skanvil validate no reporta errores, y npx skanvil index --check pasa.
• Los skills nuevos o editados tienen descripciones específicas con desencadenantes, y no tienen contenido de plantilla ni marcadores de posición.
• Las eliminaciones y sincronizaciones en otros proyectos fueron confirmadas con el usuario.