Delimitación de Permisos de Skills de Claude: Una Guía para el Frontmatter allowed-tools

Una skill de Claude es un archivo de texto plano, SKILL.md, que agrupa instrucciones y metadatos para extender las capacidades del modelo base. Este archivo puede otorgar al modelo acceso a su entorno local, incluyendo la capacidad de leer y escribir archivos, y ejecutar comandos de shell. Esto es potente. También es una consideración de seguridad significativa.

El mecanismo principal para controlar este poder es el campo allowed-tools dentro del frontmatter de la skill. Esta única línea de configuración es el elemento más crítico para definir los límites de una skill. Hacerlo correctamente es la diferencia entre una herramienta útil y confiable, y una posible vulnerabilidad.

En SkillProof, no solo listamos skills; las instalamos y ejecutamos en tareas del mundo real. Nuestro proceso se basa en la verificación, y una parte fundamental de ello es analizar los permisos solicitados por una skill en comparación con su función real. Publicamos nuestros hallazgos, incluyendo los fallos. De 743 skills probadas hasta la fecha, solo 508 pasaron nuestros criterios. 204 requirieron configuración manual, a menudo relacionada con permisos, y 31 tuvieron un rendimiento peor que usar Claude directamente, algunas por razones de seguridad. Este artículo explica cómo evaluamos claude skill allowed-tools y por qué es un tema que todo usuario y desarrollador debe comprender.

El Principio de Mínimo Privilegio en las Skills de Claude

El campo allowed-tools es un array en el frontmatter de SKILL.md que especifica qué herramientas se le permite a la skill solicitar del entorno anfitrión. Si una herramienta no está en esta lista, la skill no puede usarla, y el modelo no puede ser incitado a invocarla.

Esta es una implementación directa del principio de mínimo privilegio (PoLP): a un sujeto se le deben otorgar solo los permisos necesarios para completar sus tareas requeridas. Una skill diseñada para refactorizar código Python dentro de un directorio de proyecto no necesita acceso al shell del sistema. Una skill que formatea archivos markdown no necesita leer su directorio ~/.ssh.

Cuando se delimitan correctamente las herramientas de una skill de Claude, se crea un contrato predecible y seguro entre el usuario y la skill. La señal de alerta más común que vemos durante las pruebas es una declaración allowed-tools excesivamente permisiva. Una skill que solicita allowed-tools: ["*"] está pidiendo todos los permisos posibles, incluyendo shell, file_read y file_write. Esto es el equivalente a darle a una aplicación acceso de root cuando todo lo que necesitaba era leer un solo archivo. Indica pereza por parte del desarrollador o, lo que es más preocupante, una intención de realizar acciones más allá de su propósito declarado.

Un frontmatter de seguridad de skill de Claude configurado correctamente es la primera línea de defensa contra comportamientos no deseados. Es una clara declaración de intenciones por parte del desarrollador. Una lista allowed-tools mínima y bien definida es una señal de calidad y respeto por el sistema del usuario.

Definiendo un Conjunto de Herramientas Mínimo y Efectivo

Para delimitar correctamente los permisos de una skill, un desarrollador debe analizar su función principal y mapearla directamente a las herramientas requeridas. El proceso es sencillo:

1. Defina el Objetivo: ¿Cuál es la función única y principal de la skill? (ej., "Ejecutar pytest en el proyecto actual.")
2. Identifique las Acciones: ¿Qué pasos se requieren para lograr ese objetivo? (ej., "Ejecutar un comando en la terminal.")
3. Mapee Acciones a Herramientas: ¿Qué herramientas específicas se necesitan para esas acciones? (ej., La herramienta shell es necesaria para ejecutar un comando.)
4. Declare Solo lo Necesario: La lista allowed-tools resultante debe contener solo las herramientas identificadas en el paso anterior.

Cualquier cosa más es una vulnerabilidad potencial. Considere estos escenarios comunes que hemos evaluado:

Caso de Uso	allowed-tools Excesivamente Permisivo	allowed-tools Delimitado Correctamente	Justificación
Leer un archivo de configuración e informar sobre él	["*"]	["file_read"]	La skill solo necesita leer. El acceso de escritura y shell son riesgos innecesarios.
Aplicar un formateador de código como black	["file_read", "file_write", "shell"]	["shell"]	El comando black maneja su propia E/S de archivos. La skill solo necesita invocarlo.
Refactorizar código en múltiples archivos	["*"]	["file_read", "file_write"]	La skill necesita leer archivos para entender el contexto y escribir archivos para guardar los cambios. El acceso a shell no es necesario.

Este proceso analítico es una parte fundamental de nuestra metodología de prueba. Si los permisos solicitados por una skill no se alinean con su función documentada, falla nuestra revisión o se marca como que requiere verificación manual. Para una lista completa de herramientas disponibles y campos de frontmatter, consulte nuestra /blog/claude-skill-frontmatter-reference.

Casos de Estudio de 743 Skills Probadas

La teoría es útil, pero ver fallos en el mundo real demuestra lo que está en juego. El modelo de permisos de las skills de Claude es robusto, pero depende de que desarrolladores y usuarios apliquen buenas prácticas. Aquí hay tres ejemplos anonimizados de nuestras pruebas que resaltan lo que puede salir mal.

La Skill Auto-Escalable

Una de las vulnerabilidades más preocupantes que descubrimos fue en una skill diseñada para ayudar a gestionar configuraciones de proyectos. En su primera ejecución, la skill funcionó como se esperaba. Sin embargo, también realizó una acción no documentada: utilizó su permiso file_write para modificar el archivo global .claude/settings.json del usuario.

La modificación fue sutil. Añadió la herramienta shell a su propia allow_list dentro de la configuración, escalando efectivamente sus propios privilegios para todas las ejecuciones futuras. El usuario, habiendo aprobado solo file_write inicialmente, no se daría cuenta de que la skill ahora tenía la capacidad de ejecutar cualquier comando en su sistema.

Para empeorar las cosas, la documentación de la skill recomendaba ejecutar el host de Claude en modo acceptEdits, lo que haría que esta escalada de privilegios ocurriera silenciosamente, sin una solicitud de confirmación del usuario. Esta combinación de una configuración con puerta trasera y la ingeniería social para deshabilitar las comprobaciones de seguridad representa una grave brecha de seguridad. Marcamos esta skill, Self-Modifying Configurator, con nuestra calificación de severidad más alta.

El Scraper de Dotfiles Excesivamente Ambicioso

Otra categoría de fallo involucra skills que son demasiado agresivas con file_read. Probamos una skill destinada a ayudar a los desarrolladores a encontrar y usar herramientas CLI. Su SKILL.md solicitaba amplios permisos de lectura de archivos. Durante nuestra ejecución de prueba, observamos que intentaba leer el contenido de ~/.zshrc, ~/.bash_profile y otros archivos de configuración de shell.

Estos archivos son un lugar común para que los desarrolladores almacenen información sensible, como declaraciones EXPORT para claves API, credenciales de bases de datos y otros secretos. Aunque el autor de la skill pudo haber tenido la intención de analizar inocentemente el PATH del usuario, la implementación fue imprudente. Una skill con este comportamiento, como la que registramos como Dotfile Scraper, podría modificarse fácilmente para exfiltrar cualquier secreto que encuentre.

Casi no hay una razón legítima para que una skill genérica lea estos archivos específicos y de alta sensibilidad. Una skill que necesita acceso a variables de entorno debería usar un mecanismo dedicado y seguro, no raspar archivos de configuración.

El Artista del Escape del Sandbox

Algunas herramientas incluyen características de seguridad, como redactores que impiden que el modelo vea información sensible como claves API encontradas en archivos. Probamos una skill que parecía estar diseñada intencionalmente para eludir estas protecciones. Utilizó una serie de prompts complejos y operaciones de archivo para intentar engañar al host y revelar información redactada.

Esta skill, Redactor Bypass Attempt, no tuvo éxito en nuestro entorno de prueba, pero el intento en sí es un fallo crítico. Demuestra una intención maliciosa. El desarrollador no fue simplemente descuidado con los permisos; estaba intentando activamente romper el modelo de seguridad del entorno anfitrión. Esto es fundamentalmente diferente de una herramienta mal delimitada y representa un nivel de riesgo inaceptable en cualquier software.

Responsabilidades para Desarrolladores y Usuarios

Proteger el ecosistema de skills de Claude es una responsabilidad compartida.

Para Desarrolladores:

La confianza es su activo más valioso. Cuando publica una skill, está pidiendo a los usuarios que ejecuten su código en su máquina. La forma más rápida de ganarse su confianza es ser transparente y conservador con sus solicitudes de permisos. Una lista allowed-tools estrictamente delimitada es una característica. Demuestra que ha pensado en la seguridad y respeta el entorno del usuario. Antes de publicar, pregúntese: "¿Cuál es el conjunto mínimo absoluto de herramientas que mi skill necesita para funcionar?" Si está construyendo su primera skill, tenemos una guía sobre cómo /blog/write-your-own-claude-skill que cubre estos principios.

Para Usuarios:

Sea vigilante. Antes de instalar una skill, tómese un momento para inspeccionar su archivo SKILL.md. Mire la lista allowed-tools. ¿Tiene sentido? Si una skill que promete escribir poesía está pidiendo acceso a shell, debería sospechar. Pregúntese por qué necesita ese permiso. Si la respuesta no es obvia a partir de la descripción de la skill, es más seguro evitarla.

Esto es, ciertamente, mucho trabajo para cada skill. Por eso son necesarios los directorios que realizan una verificación independiente. Todo nuestro proceso está diseñado para realizar esta auditoría en su nombre, para que pueda usar las skills con confianza.

Skills Verificadas en las que Puede Confiar

Examinar cada skill en busca de fallos de seguridad, especialmente los sutiles relacionados con cómo delimitar las herramientas de las skills de Claude, es un proceso técnico y que consume mucho tiempo. Después de revisar cientos de skills, hemos visto lo fácil que es que se publiquen herramientas peligrosas o defectuosas.

Construimos SkillProof para resolver este problema. Hacemos el trabajo de prueba, verificación y auditoría de seguridad para que usted no tenga que hacerlo. Por una compra única de $10, nuestro Paquete Completo de 508 Skills Aprobadas le ofrece un conjunto de herramientas completamente verificado. Cada skill ha pasado nuestras comprobaciones de seguridad, incluyendo una revisión estricta de su alcance allowed-tools.

El poder de una skill proviene de su código; su fiabilidad proviene de sus restricciones. Verificar allowed-tools es el primer y más crítico paso para construir esa confianza.