¿Qué es un archivo de skill para IA? Estructura, índices y controles de seguridad
Un archivo de skill da a un agente de IA un contexto permanente para un tipo de tarea. Qué debe contener, cuándo ayuda un índice, cuándo dividirlo y cómo revisar los de terceros.
Imagina a una persona muy capaz que no sabe nada de ti. Le das una tarea breve sin antecedentes, sin propósito, sin restricciones y sin idea de cómo es un buen resultado, y luego esperas que lo que entregue coincida con lo que tenías en mente, todas y cada una de las veces. No funcionaría.
Los agentes tienen el mismo problema. Una instrucción corta puede dar un resultado válido que aun así no es lo que se quería. Vuelve a ejecutarla, o pásasela a otro agente, y el estilo o el método pueden cambiar, porque la instrucción deja decisiones que la IA toma en tu lugar. Los archivos de skill son el remedio.
Una skill es más que un prompt largo
Una skill es un paquete reutilizable de contexto e instrucciones de trabajo. Le dice al agente cuál es el objetivo de la tarea, qué flujo seguir, qué información y archivos importan, qué forma tiene un buen resultado, cuáles son los límites de lo que puede hacer y cómo proceder cuando falta algo.
Un prompt suele ser una orden para el momento. Una skill recoge los hábitos permanentes para todo un tipo de trabajo. No hace al modelo más listo; reduce las conjeturas innecesarias y da al trabajo una dirección más estable.
La analogía del restaurante
Supón que te apetece comida japonesa, pero al chef solo le dices: "Usa arroz y carne, usa estos ingredientes y que esté rico". No es una petición equivocada, y el chef puede cocinar algo delicioso. Pero «delicioso» deja un abanico enorme de posibilidades, y podrías recibir un plato tailandés, coreano, indio o europeo.
Incluso pedir comida italiana deja mucho abierto. Podrías recibir una auténtica pasta al dente o una pizza fusión con piña. A algunos les encanta la segunda y otros se oponen con fuerza, pero cualquiera de las dos cumple la petición general.
La IA se comporta igual. Cuando una instrucción deja un hueco, el sistema elige un camino plausible, y ese camino puede ser razonable sin ser el que tú pretendías. Así que, antes de entregar una skill a un agente, reléela y pregúntate:
Partiendo solo de este texto, ¿se podría terminar el trabajo? ¿Qué detalles seguirían siendo conjeturas? Y donde una decisión es inevitable, ¿está clara la dirección?
Esa revisión rápida saca a la luz una cantidad sorprendente de puntos débiles.
Qué incluye un archivo de skill
La mejor skill no es necesariamente la más larga. Aporta lo necesario para tomar las decisiones correctas. Una skill práctica suele tener estas partes.
1. Metadatos que indican cuándo se aplica la skill
El nombre y la descripción deben dejar claro qué tareas deberían activar la skill y cuáles no. Algunas implementaciones de Agent Skills usan metadatos como name y description para decidir si se cargan las instrucciones completas, una forma de revelación progresiva. Aun así, el descubrimiento, la selección y la carga varían según el modelo, el entorno de ejecución del agente y las herramientas disponibles.
Evita que la descripción sea tan amplia que la skill se apropie de cualquier tarea, o tan estrecha que el agente nunca la encuentre para el trabajo relevante.
2. Objetivo y alcance
Indica qué ayuda a producir la skill, qué cuenta como terminado y qué queda fuera de su cometido. Sin límites, un agente puede hacer más de lo necesario o mezclar responsabilidades que no tienen nada que ver en un resultado desordenado.
3. Un flujo de trabajo ejecutable
Frases como "hazlo bien" o "sigue las buenas prácticas" no explican cómo hacer nada. Sustitúyelas por pasos observables:
- Leer los archivos de origen.
- Comprobar si está la información necesaria.
- Separar los hechos de las suposiciones.
- Generar el resultado con la estructura requerida.
- Revisarlo con una checklist.
- Ejecutar los tests o validaciones pertinentes.
El trabajo de alto riesgo exige una verificación especialmente explícita.
4. Límites y reglas de decisión
Deja por escrito lo que el agente no debe hacer nunca. Ejemplos típicos son inventar métricas, filtrar secretos, editar archivos fuera del alcance acordado o presentar un requisito como una funcionalidad ya publicada.
5. Contratos de salida y ejemplos
Si el resultado alimenta otro proceso, define su forma. Pueden ser encabezados de Markdown, un esquema JSON, nombres de archivo o secciones obligatorias. Los ejemplos reducen la ambigüedad, pero demasiados ejemplos rígidos hacen que todos los resultados se parezcan. Deben ilustrar el contrato, no sustituir el criterio.
6. Controles de calidad
Una skill debería explicar cómo saber que el trabajo está realmente terminado, porque generar un archivo no siempre equivale a acabar la tarea. Los controles pueden incluir una checklist, linting, tests unitarios, validación de esquemas o preguntas de revisión:
- ¿Están respaldadas las afirmaciones factuales?
- ¿Alguna afirmación va más allá del estado real del producto?
- ¿Cumple el resultado el contrato?
- ¿Expone datos personales o secretos?
¿Necesita una skill un índice?
Un índice se vuelve muy útil a medida que crece el material, pero no hace que la IA conozca automáticamente todo lo que hay en la skill.
Una forma habitual de explicarlo es que la IA lee desde arriba, encuentra el índice y puede saltar al contenido relevante sin leer el archivo entero. Como modelo mental es práctico, pero no es una regla universal. Cómo se lee, se busca y se selecciona la información depende del modelo, del entorno de ejecución del agente, de las herramientas de búsqueda de archivos, de la estrategia de carga de contexto y de las instrucciones del sistema.
Lo que un índice sí hace de forma fiable es mejorar la organización del material. En la práctica puede:
- Dar tanto al agente como a un lector humano una visión rápida del conjunto
- Describir qué hay en cada sección o archivo de referencia
- Ayudar al agente a elegir solo las referencias que necesita una tarea
- Reducir la tentación de cargar todos los documentos en el contexto
- Hacer más fácil mantener una skill de varios archivos
Así que un buen índice no se limita a enumerar nombres de archivo. Dice cuándo importa cada archivo. Por ejemplo:
references/
├── api-contract.md # Read when creating or changing an API
├── security-rules.md # Read when touching auth, secrets, or permissions
├── output-examples.md # Read when validating the required output shape
└── troubleshooting.md # Read when validation or tests fail
Una organización así permite al agente elegir y le ahorra adivinar por los nombres de archivo o cargarlo todo por si acaso.
Cuándo dividir una skill en varios archivos
Si una skill es corta, sigue un solo flujo y se lee de un vistazo, un único archivo puede ser lo más claro. Dividir demasiado pronto crea más enlaces que mantener y obliga al lector a saltar entre archivos.
La división empieza a compensar cuando la skill incluye mucho material de referencia, varios flujos de trabajo, un montón de ejemplos o scripts que vale la pena reutilizar. Una estructura posible:
skill-name/
├── SKILL.md
├── scripts/
├── references/
└── assets/
Qué directorios y nombres se admiten puede variar según la plataforma y el entorno de ejecución, y cómo usa los archivos un agente puede depender del modelo y sus herramientas. Como regla general, el archivo principal debería decir qué hacer y dónde buscar más detalle. No todo tiene que estar arriba, pero lo que esté debería ayudar a tomar decisiones rápidas y correctas.
Trata una skill como software
Una skill puede agrupar instrucciones, referencias y scripts ejecutables, así que instalar la de otra persona sin leerla conlleva más o menos el mismo riesgo que instalar un paquete o ejecutar código desconocido. Antes de adoptar una, hazte al menos estas preguntas:
- ¿Accede a más archivos de los que debería necesitar?
- ¿Hay llamadas salientes a la red o a APIs, y hacia qué destinos?
- ¿Hay secretos o credenciales escritos directamente en algún sitio?
- ¿Qué datos pueden modificar o borrar sus scripts?
- ¿Hay algo escrito para saltarse las reglas del sistema?
Las organizaciones también pueden necesitar revisión, sandboxing y pruebas de compatibilidad. Los modelos responden a las instrucciones y eligen herramientas de forma distinta, y cada plataforma o empresa puede aplicar su propia gobernanza.
Para saber más
Hay guías oficiales sobre cómo escribir skills en https://agentskills.io/skill-creation/best-practices y en la documentación de la plataforma de Anthropic sobre Agent Skills (en platform.claude.com, en la página de buenas prácticas de agent-skills).
La conclusión
Trabajar con IA no es tan distinto de trabajar con un compañero. Cuando explicas con claridad el objetivo, el contexto, el flujo, las restricciones y los criterios de revisión, quien reciba la tarea, persona o agente, tiene más opciones de entregar lo que necesitas. Un archivo de skill deja constancia de ese entendimiento compartido para que no tengas que reconstruirlo desde cero cada vez.
Cuando una skill crece o empieza a apuntar a varios archivos, añade un índice, pero constrúyelo como un mapa de decisiones y no como un índice decorativo. Después lee la skill como lo haría un desconocido y pregúntate:
¿Podría esa persona continuar realmente desde aquí, o seguiría tomando decisiones en nombre de quien la escribió?
Si quedan decisiones así, resuélvelas primero. Una buena skill no elimina la necesidad de pensar. Elimina las conjeturas evitables.