Skills en NuGet: inspecciona el SKILL.md de tu dependencia
Guía defensiva para empaquetar e inspeccionar SKILL.md en NuGet sin confundir contenido distribuido con instrucciones ejecutadas por cualquier agente.
6 de noviembre de 2026 · Leopoldo Benavente Cadena · 5 min de lectura
Una dependencia NuGet suele llegar al proyecto como una biblioteca, pero también puede transportar documentación, analizadores y otros archivos. La propuesta reciente de Microsoft para distribuir Agent Skills aprovecha ese mismo vehículo: una versión del paquete puede llevar un SKILL.md ajustado a las APIs que contiene. Es una relación útil entre documentación y código, siempre que no confundamos las capas.
NuGet restaura paquetes; no es, por sí mismo, un intérprete de instrucciones para agentes. Tras una restauración, los archivos pueden quedar en la caché local y aparecer en el grafo de activos del proyecto. Que un cliente compatible los descubra, los cargue en contexto o los copie a una carpeta del repositorio es una decisión posterior, con sus propias reglas y permisos.
Tres capas que conviene separar
| Capa | Qué aporta | Qué no garantiza |
|---|---|---|
.nupkg |
Un archivo ZIP versionado con DLL, metadata y contenido adicional | Que cada archivo sea una skill activa o segura |
SKILL.md |
Frontmatter y Markdown según el formato Agent Skills | Que sus instrucciones sean correctas, confiables o compatibles con tu cliente |
| Cliente o agente | Descubrimiento, carga o copia cuando implementa esa integración | Que dotnet restore ejecute instrucciones o que todos los asistentes se comporten igual |
La especificación de Agent Skills exige un directorio con SKILL.md. El archivo debe tener frontmatter YAML con name y description; admite directorios opcionales como scripts/, references/ y assets/. Es un formato abierto, no una promesa de soporte universal en IDE, CLI o modelo concreto.
Cómo empaquetarla sin ocultarla
Para un mantenedor, la inclusión puede declararse como contenido de MSBuild. Este patrón es una propuesta basada en la documentación de NuGet; los nombres y rutas deben adaptarse al proyecto:
<ItemGroup>
<Content Include="skills\**\*">
<Pack>true</Pack>
<PackagePath>skills\</PackagePath>
</Content>
</ItemGroup>Pack=true marca los archivos para el paquete y PackagePath expresa dónde deben aparecer dentro del .nupkg. Después de dotnet pack, revisa el archivo generado, no solo el proyecto fuente: confirma que cada skill tenga su SKILL.md, que las rutas relativas conserven la estructura y que no se hayan incluido secretos, archivos temporales ni scripts inesperados. Empaquetar contenido no activa nada en un agente consumidor.
Si la skill debe acompañar a una API concreta, usa una versión explícita del paquete y revísala junto con el cambio de código. La colocación conjunta reduce el riesgo de consultar documentación vieja, pero no reemplaza un contrato de compatibilidad. Un agente puede ignorar la skill, cargar otra del repositorio o interpretar el texto de forma distinta según el cliente.
Inspección segura del .nupkg
Trata el paquete como código de terceros aunque el archivo que quieras leer sea Markdown. Trabaja en una carpeta temporal y de solo lectura lógica; no ejecutes los scripts contenidos ni abras el flujo con las credenciales del proyecto. Por ejemplo, este esqueleto de PowerShell permite listar y leer archivos sin instalar la skill:
$paquete = (Get-ChildItem .\artifacts\*.nupkg | Select-Object -First 1).FullName
$destino = Join-Path ([IO.Path]::GetTempPath()) "skill-inspect-$([guid]::NewGuid())"
Expand-Archive -LiteralPath $paquete -DestinationPath $destino
$skills = Get-ChildItem -LiteralPath $destino -Recurse -Filter SKILL.md
$skills | Select-Object FullName, Length
Get-Content -LiteralPath $skills[0].FullName -TotalCount 40El ejemplo solo extrae para inspección; no afirma haberlo ejecutado con un paquete real. Comprueba el identificador, la versión, el feed, la licencia, el mantenedor y la lista de dependencias antes de aceptar el contenido. En cada SKILL.md, valida que name use minúsculas, números y guiones, que coincida con el directorio y que description explique qué hace y cuándo aplica. Revisa también los enlaces relativos: references/ y assets/ deben quedarse dentro del ámbito esperado de la skill.
Busca señales que cambiarían la decisión: órdenes destructivas, envío de secretos, hosts externos, cambios de configuración, instrucciones que desactiven controles y scripts que no correspondan a la API documentada. Que el archivo sea Markdown no lo vuelve inofensivo; un cliente podría usarlo para decidir qué herramientas leer o invocar. La extracción tampoco prueba que el cliente vaya a respetar todas las instrucciones.
Microsoft muestra dotnet-inspect package <id> -S Skills para enumerar skills de un paquete y dotnet-inspect project <proyecto.csproj> -S Skills para consultar las dependencias directas. dotnet-inspect es una herramienta separada, no un subcomando estándar confirmado de dotnet. Otra herramienta mostrada en la publicación, dotnet-package-skills, puede copiar skills revisadas a .agents/skills; esa copia debe ser explícita y pasar por revisión, no producirse como efecto silencioso de restore.
De contenido distribuido a activación controlada
Decide primero dónde vive la versión aprobada. Mantenerla en la caché del paquete conserva su relación con la dependencia, mientras que copiarla al repositorio permite revisar el diff y someterlo al mismo control que el código. No mezcles automáticamente una copia de la caché con instrucciones propias del proyecto ni la ubiques en una carpeta global que otros repositorios puedan consumir sin revisión.
En un laboratorio aislado, compara una tarea acotada con la skill y sin ella usando el mismo commit, versión de paquete y cliente. Registra qué archivos se leyeron, qué herramientas fueron invocadas y qué salida cambió. No lo llames benchmark general: una sola tarea no mide precisión, coste ni seguridad de todos los modelos. El laboratorio tampoco debe tener secretos, acceso de escritura a producción ni permisos que una instrucción accidental pueda aprovechar.
Para quien publica el paquete, la revisión continúa en cada versión: inspección del .nupkg, diff del SKILL.md, verificación de dependencias y comprobación de que la licencia y el mantenedor siguen siendo aceptables. Para quien lo consume, fija la versión que evaluaste, conserva la evidencia del feed y retira la skill si introduce instrucciones que el equipo no acepta. La distribución puede ser práctica; la confianza no viene incluida en el ZIP.
Comentarios