Prueba práctica de permisos de Skills en pnpm 12.11.0: ¿qué significa exactamente aprobar una vez?

Descripción: A partir del código fuente de pnpm v12.11.0 y de la documentación de esa versión, analizo el alcance del descubrimiento de Skills, el proceso de aprobación y el comportamiento de los enlaces. Además, verifico las ramas clave mediante un modelo sintético independiente para ayudar a los desarrolladores a evaluar las actualizaciones de dependencias y la gestión de permisos.

Descubrimiento y límites de permisos

Al principio simplifiqué demasiado la pregunta: si una dependencia incluye un SKILL.md, pnpm o bien lo instala directamente en el directorio del agente o bien no hace nada. Al seguir el código fuente de la versión fija pnpm 12.11.0, vi que entre una cosa y otra hay varios pasos: descubrimiento, comprobación de permisos y creación de enlaces. Esos límites son la clave para entender qué significa «aprobar una vez».

Primero seguí la lógica de descubrimiento, pensando que cualquier archivo Skill presente en el árbol de dependencias entraría en el proceso de aprobación. Pero el alcance del escaneo es más limitado: pnpm comprueba las dependencias directas de cada importer del workspace en el lockfile y solo explora un nivel de directorios Skills. Las dependencias transitivas no forman parte de esta ruta de descubrimiento; no se puede equiparar «hay un archivo en el árbol de dependencias» con «pnpm lo descubrirá».

Después separé la instalación, la creación de enlaces y la carga por parte del agente. Los archivos del paquete pueden estar ya en el directorio de dependencias; el estado de los permisos determina si pnpm crea un enlace simbólico hacia el directorio de destino; y, más tarde, que Claude Code u otro agente los lea y cómo los procese depende del cliente correspondiente. El código fuente de pnpm gestiona los enlaces, no analiza ni ejecuta el contenido de los Skills.

Las ramas de permisos incluyen los estados pendiente de aprobación, rechazado y aprobado. La aprobación se gestiona a nivel de paquete; pnpm approve abarca tanto los scripts de compilación como los permisos de Skills. Esto no equivale a revisar cada archivo individualmente. Los permisos de los scripts de compilación y permissions.skills son ámbitos de permisos distintos: que se aprueben los scripts de compilación de un paquete no significa que el contenido de sus Skills se haya revisado por separado.

Lo que más me hizo detenerme a verificar fue el alcance de la aprobación. La documentación oficial de v12.11.0 indica que una aprobación a nivel de paquete cubre todos los Skills de esa dependencia y se mantiene también para sus versiones posteriores. Al actualizar, conviene prestar atención a los cambios en las instrucciones de las versiones nuevas: el estado de aprobación anterior podría seguir siendo válido aunque la nueva versión añada o modifique un Skill.

Si en el workspace hay varias versiones disponibles, el código fuente elige la versión más alta entre las versiones de registry instaladas que cumplen los requisitos. Esto puede afectar a qué contenido se enlaza realmente, así que no basta con mirar el rango de versiones de package.json. Para determinar qué podría leer el agente después de una actualización, también hay que comprobar qué versión del paquete se seleccionó y qué Skill incluye.

El directorio de destino también está sujeto a condiciones específicas. En v12.11.0 se tienen en cuenta las variables de entorno CLAUDECODE, CURSOR_AGENT y GEMINI_CLI, así como los directorios Agent Skills que ya existan en el workspace. skills.dirs permite especificar directorios explícitamente. Una configuración explícita vacía desactiva Skills; si al aprobar no se detecta automáticamente ningún directorio de destino, se produce un error por falta de destino.

# pnpm-workspace.yaml
skills:
  dirs:
    - .claude/skills
    - .cursor/skills

También había pensado que revocar los permisos eliminaría el contenido de los directorios correspondientes. El código fuente y un modelo independiente del sistema de archivos muestran un límite más acotado: el modelo observa que se eliminan los enlaces que había creado, mientras que los Skills locales creados manualmente permanecen intactos; una ruta de destino ocupada por un directorio real no se sustituye. La eliminación de paquetes, la ausencia del directorio de destino y otras ramas también deben entenderse según la lógica específica de limpieza de enlaces y gestión de errores.

Modelo sintético y resultados de las pruebas

Para concretar estas ramas, escribí un modelo independiente de sistema de archivos sintético con la biblioteca estándar de Node 22.16.0: crea dependencias falsas temporales, archivos SKILL.md sintéticos y enlaces simbólicos, y luego calcula huellas digitales del contenido. Los ocho escenarios cubren, respectivamente, la aprobación pendiente, el rechazo, la aprobación, un Skill añadido tras una actualización, la revocación, un conflicto de rutas, una dependencia solo transitiva y la ausencia de un directorio de destino detectado automáticamente.

Los ocho escenarios cubiertos por el modelo pasaron. En el escenario de actualización, se observó un cambio en la huella digital del contenido y apareció un segundo enlace a un Skill. En la primera ejecución del modelo, uno de los escenarios falló porque usé «el número esperado de enlaces es cero» para determinar si existía algún Skill aprobado y clasifiqué erróneamente el caso «no hay directorio de destino». Tras localizar el problema, cambié la comprobación para contar por separado los Skills aprobados. En la siguiente ejecución, pasaron los ocho escenarios.

Comprobaciones en el repositorio y alcance de aplicación

Al revisar el repositorio, se puede empezar con pnpm permissions o pnpm permissions list para consultar los permisos y contrastarlos con la configuración del workspace. Tras actualizar una dependencia, conviene revisar los archivos Skills de la nueva versión y sus diferencias. Los proyectos que quieran controlar mejor los cambios en las instrucciones pueden fijar la versión de la dependencia y comparar SKILL.md en CI.

pnpm permissions
pnpm permissions list

Límites / limitaciones

Este análisis toma como referencia el código fuente de pnpm v12.11.0 y la documentación de esa versión. Las pruebas usan un modelo sintético ejecutado de forma independiente con Node y cubren el comportamiento del sistema de archivos. El modelo no se integra con la CLI de pnpm, instalaciones o actualizaciones reales ni agentes; además, las reglas de descubrimiento y ejecución de los clientes pueden variar según sus respectivas versiones. Los cambios de reconocimiento del entorno de pnpm 12.11.1 no deben atribuirse retroactivamente a la versión 12.11.0. El alcance de confianza sobre versiones posteriores que conlleva una aprobación a nivel de paquete es un límite de diseño que conviene tener en cuenta al revisar actualizaciones.

Enlaces de referencia: Código fuente de pnpm v12.11.0 · Documentación de pnpm v12.11.0