De la carpeta a la librería: skanvil forja, valida y sincroniza Agent Skills con edición transaccional, doctor reparador, sync idempotente por manifiesto y una API programática para que los agentes operen tu librería.
Si tu equipo usa agentes de código, ya tienes skills. Una de review de frontend, un playbook de migración de backend, el flujo de release interno. Cada una vive en su SKILL.md, con su frontmatter, sus referencias y su carpeta. Y a partir de ahí, todo el trabajo alrededor es manual: crear la carpeta con el nombre correcto, rellenar el frontmatter, actualizar el índice del README, validar que la skill cumple la spec, y copiarlo todo a los proyectos donde los agentes la van a leer.
Ese trabajo mecánico es lo que me llevó a construir skanvil, que hoy lanzo en la versión 1.0.0: una CLI y una librería de Node.js para forjar, validar y distribuir librerías de Agent Skills.
Qué es una skill de agente (y una librería de ellas)
Una Agent Skill es una carpeta con, como mínimo, un SKILL.md: frontmatter en YAML (name, description) más instrucciones en markdown. Claude Code, GitHub Copilot y Codex las descubren en carpetas concretas de cada proyecto: .claude/skills, .github/skills, .agents/skills.
Una librería de skills es el siguiente paso: un repo git (opcionalmente un paquete npm) donde un equipo mantiene sus skills compartidas, agrupadas en categorías. Unas para frontend, otras para backend, algunas transversales.
El frontmatter mínimo de una skill cabe en dos líneas:
---
name: api-review
description: Revisa cambios de integración de APIs. Usar en PRs que toquen clientes HTTP.
---Pero a partir de ahí empieza la vida real de una librería. El problema no es escribir la skill — la escribe cualquiera con el agente delante —, sino todo lo que rodea a decenas de skills mantenidas por varias personas:
- ¿El nombre de la carpeta coincide con el
namedel frontmatter? - ¿El índice del README está al día?
- ¿Esta skill de hace tres meses sigue cumpliendo la spec?
- ¿Y cuando la renombro, quién actualiza la carpeta, el frontmatter, el heading y el README?
skanvil responde a las cuatro.
Qué hace skanvil
skanvil es una CLI (binario skanvil) y una librería programática de TypeScript con API tipada. Cada comando acepta --json, y cada comando que opera sobre una librería acepta -C, --cwd <path> para apuntar a otra carpeta.
Las piezas principales:
skanvil initcrea la librería completa: carpetas de skills, el README con índice, el.skanvilrc.json,AGENTS.md, un workflow de CI y elpackage.jsoncon los scripts. Si prefieres menús, ejecutarnpx skanvilsin argumentos abre un wizard interactivo que recorre cada paso y te imprime el comando equivalente.skanvil addcrea una skill desde la plantilla: aplica el prefijo de la categoría, renderiza la plantilla, rellena el frontmatter con los metadatos de categoría, añade la entrada en el README y valida.skanvil editrenombra, recategoriza y elimina skills manteniendo consistente la carpeta, elnamedel frontmatter, el# headingy la entrada del README. Es transaccional: si algo falla a medias, revierte los ficheros.skanvil validatecomprueba cada skill contra la spec de Agent Skills y contra las convenciones propias de tu librería. Los errores fallan; los avisos se reportan, y con--stricttambién fallan.skanvil doctor --fixrepara lo que se pueda reparar solo: entradas de README,namedescuadrados, tabs en el frontmatter.skanvil synccopia las skills de la librería a los folders que leen los agentes, en cualquier proyecto:.claude/skills,.github/skills,.agents/skills. Puedes syncar desde npm o desde un checkout git local.
Quick start
Tres minutos para tener la librería corriendo:
npx skanvil init my-skills --scope acme \
--description "Skills compartidas de agentes de código de Acme."
cd my-skills
npm install
npx skanvil add --type front --name "API review" \
--description "Revisa cambios de integración de APIs: errores, tipos y reintentos."A partir de aquí escribes el contenido real en skills/front-api-review/SKILL.md (las secciones requeridas de la plantilla son Objetivo, Cuándo Activar, Instrucciones, Formato de Salida y Criterios de Calidad, y el material largo va en references/). Cada cambio se valida:
npx skanvil list
npx skanvil validate # los errores fallan
npx skanvil validate --strict # los avisos tambiénY en el proyecto de aplicación:
npm install --save-dev @acme/my-skills skanvil
npx skanvil sync --from @acme/my-skills --target claude,copilotLas skills quedan en .claude/skills/ y .github/skills/, donde Claude Code y Copilot las descubren. Volver a ejecutar el mismo comando actualiza lo que cambió, borra lo que se eliminó de la librería, y no toca nunca skills que skanvil no instaló: cada target lleva un manifiesto .skanvil-sync.json que es la única autoridad sobre qué puede actualizar o borrar. Eso convierte el sync en algo idempotente y seguro de correr en CI.
Si los proyectos del equipo son muchos, el sync puede instalarse como script npm en cada uno (npm run skill:sync), o con --link en Windows, que usa junctions sin necesidad de permisos de administrador. Y si quieres que los agentes del proyecto también gestionen la librería — por ejemplo, re-ejecutar el sync cuando sube una versión de las skills —, instala la skill de skanvil también en ese proyecto: npx skanvil install-skill --target claude,copilot.
La API programática
Todo lo que hace la CLI se puede hacer desde Node.js, tipado y documentado. La librería abre un Library, y las operaciones son funciones:
import { Library, scaffoldSkill, validateLibrary, syncSkills } from "skanvil";
const lib = await Library.open("./my-skills");
await scaffoldSkill(lib, {
type: "front",
name: "a11y",
description: "Audita accesibilidad en componentes.",
});
const { errors, diagnostics } = await validateLibrary(lib);
if (errors === 0) await syncSkills(lib, { dest: "../my-app", targets: ["claude"] });Eso es lo que habilita el patrón que más me gusta: pipelines de generación. Un script que a partir de un catálogo interno (un JSON, una hoja de cálculo, una API) genera skills con scaffoldSkill, valida con validateLibrary y sincroniza solo si hay cero errores. El --json de la CLI y la API comparten la misma forma de diagnósticos, así que un agente que automiza la librería programa contra lo mismo que lee en la salida del comando.
Decisiones de diseño que merecen una línea
Tras un tiempo con la herramienta, estas son las que más uso:
La configuración manda, no los constantes. Nada de las convenciones de tu librería está hardcodeado: prefijos de carpetas, títulos del README, metadatos por categoría, secciones requeridas y severidades de reglas viven en .skanvilrc.json. Por defecto vienen front-, back-, skills transversales sin prefijo y _internal; el cargador de config rechaza configuraciones ambiguas (dos categorías por defecto, un prefijo que empieza por otro prefijo, aliases duplicados).
Ediciones transaccionales. edit calcula el nuevo SKILL.md y el nuevo README en memoria, los escribe y renombra la carpeta al final. Si falla en el punto c, los dos ficheros vuelven a su estado anterior. La consecuencia práctica: un agente no te puede dejar la librería a medio renombre.
Diagnósticos estructurados. Cada diagnóstico lleva rule, severity, skill, message y fixable. Esa misma forma alimenta la salida de texto, el --json, el doctor --fix y el chequeo de seguridad del sync. Un agente que parsea validate --json sabe exactamente qué regla falló, en qué skill y si es auto-reparable.
El README es markdown plano. El índice vive en el README como entradas normales (- Título + descripción + carpeta, dentro de un <details>), y no en un fichero aparte. Lo que lees en GitHub es lo que el agente usa.
La herramienta se explica a sí misma a los agentes. skanvil se distribuye con su propia skill: init la instala en la librería y skanvil install-skill --target claude,copilot,agents la añade a cualquier repo. El resultado es el que cambia el flujo: en vez de decirle a Claude Code «crea la carpeta, escribe el frontmatter, actualiza el README y valida», le dices «añade una skill de backend para migraciones de base de datos» y el agente ejecuta skanvil add, escribe el contenido y valida, sin tocar ficheros a mano. La skill lleva reglas de oro (nunca renombrar carpetas a mano, pasar siempre opciones explícitas en shells no interactivos, terminar con validate sin errores) y una tabla de cada diagnóstico a su arreglo.
Plantillas como datos. Cambiar cómo se ve una skill o una librería no requiere tocar código de skanvil: echas la plantilla fuera con --eject-templates y la personalizas.
Por qué hoy: la 1.0.0
Hoy publico la 1.0.0 en npm, con lo que de un repo experimental pasa a herramienta que puedes instalar con garantías:
- CI verde: lint, typecheck, build y tests (unitarios, end-to-end del core y suites con la CLI real empaquetada) en cada push.
- Publicación automatizada: release-please prepara el PR de versión y npm publica tras CI en verde, con Trusted Publishing y provenance en el paquete.
prepublishOnly: no se publica sin lint, typecheck, build y tests limpios.- Node ≥ 20, TypeScript ESM, dependencias mínimas (commander, zod, yaml, @inquirer/prompts, picocolors).
- MIT, con documentación completa: getting started, comandos, configuración, reglas de validación, plantillas, sync, API y arquitectura.
El paquete se llama skanvil en npm y el código está en github.com/JMBargueno/skanvil.
Una nota sobre la memoria de tu agente
Las skills no son conocimiento; son procedimiento: cómo se hace una cosa en tu equipo. El conocimiento (qué decidimos, qué aprendimos) vive en otro sitio — en mi caso, en un vault de markdown con mantenimiento nocturno, de lo que escribí aquí. Los dos sistemas se complementan: la memoria que sobrevive a las sesiones + el procedimiento que sobrevive a los proyectos. skanvil se encarga de la segunda mitad.
Cierre
Si en tu equipo alguien ya ha renombrado una carpeta de skills a mano y ha tenido que perseguir el frontmatter y el README, ya sabes qué problema resuelve skanvil. Empieza por npx skanvil init, añade una skill, y déjale al agente el resto: con su propia skill instalada, tu equipo no edita la librería a mano — la opera con comandos que validan a cada paso.
El repo está abierto: si quieres una categoría por defecto distinta, una regla de validación nueva o un target de sync que falte, abre un issue o un PR. La 1.0.0 es el principio, no el fin.