Agent Skills

Qué es una skill

Una Agent Skill es una capacidad o procedimiento reutilizable empaquetado con instrucciones y, opcionalmente, recursos de apoyo para realizar una clase de tareas. Es una definición de trabajo del Atlas. Describe conocimiento operativo que un agente puede aplicar, sin convertir al paquete en un actor que persigue objetivos por cuenta propia ni exigir que contenga código ejecutable.

El problema aparece cuando el mismo saber debe recuperarse en distintos encargos. Investigar una regresión en Commerce requiere reconocer componentes relevantes, interpretar pruebas y conservar límites de cambio. Una skill puede organizar ese procedimiento y sus referencias. El encargo concreto sigue proporcionando qué regresión investigar, qué resultado se espera y qué acciones están autorizadas.

Empaquetar permite mantener y distribuir ese conocimiento como una unidad reconocible. También crea una responsabilidad: revisar instrucciones, recursos y compatibilidad con los entornos donde se usan. Que una skill tenga un nombre preciso o una descripción convincente no demuestra utilidad, seguridad ni corrección. Esas propiedades necesitan evidencia de su contenido y aplicación.

Skill vs Tool

Una herramienta proporciona un mecanismo para observar o actuar: leer archivos, consultar un servicio, ejecutar una prueba o modificar un recurso. La skill aporta saber sobre cómo abordar una clase de trabajo y puede orientar cuándo y cómo usar herramientas. Puede utilizar cero, una o varias. Una herramienta no se convierte automáticamente en skill por tener una descripción extensa.

En Commerce, una herramienta de terminal puede ejecutar el comando de tests. Una skill de diagnóstico podría explicar cómo seleccionar una prueba pertinente, interpretar el fallo y evitar confundir un problema de preparación con una regresión. El ejecutable que realiza la acción y el procedimiento que organiza su uso tienen responsabilidades diferentes. Ninguno garantiza que la prueba elegida sea suficiente.

La skill tampoco fabrica una capacidad ausente. Si el procedimiento requiere consultar un sistema al que el agente no tiene acceso, sus instrucciones pueden describir una alternativa o pedir intervención. No pueden otorgar credenciales ni hacer disponible una herramienta por mencionarla. Esta frontera importa al reutilizar el mismo paquete entre un entorno local y uno remoto con capacidades distintas.

Skill vs Prompt e Instruction

task-prompts comunica el encargo actual. Una skill conserva una capacidad aplicable a varios encargos. «Investigar el fallo de esta ejecución» puede activar un procedimiento de diagnóstico, pero el identificador del incidente y su alcance siguen perteneciendo a la tarea. Reutilizar una solicitud y reutilizar un procedimiento son decisiones relacionadas que no producen artefactos equivalentes.

persistent-instructions aporta guía reutilizable dentro de un scope, como respetar áreas generadas o mantener una convención del repositorio. Una skill puede contener instrucciones, pero no toda guía persistente constituye una capacidad empaquetada. Es útil conservar esa diferencia para no transformar cada regla de estilo en una skill ni cargar todos los procedimientos disponibles en cualquier tarea.

Una guía puede señalar que se use cierta skill cuando corresponda; una tarea puede solicitarla explícitamente. Ninguna relación debe interpretarse como autorización ilimitada. Si el procedimiento contiene una operación fuera del encargo, su presencia en un paquete no amplía el scope. El agente necesita relacionar la guía aplicable, el objetivo actual y las restricciones de ejecución.

Skill vs Profile, Subagent y Package

agent-profiles configura una especialización: instrucciones, herramientas u otras características admitidas por el producto. Una skill describe qué procedimiento reutilizable puede aplicarse. Un perfil puede ofrecer varias skills y una skill puede ser útil para distintos perfiles. Son dimensiones de configuración y conocimiento operativo, sin una relación universal de propiedad o exclusividad.

Un subagent es un actor o ejecución delegada. Puede recibir un encargo, utilizar una skill y devolver resultados. La skill no es ese actor ni crea concurrencia o aislamiento por existir. Invocar un procedimiento dentro del mismo agente y delegar una tarea a otra ejecución tienen consecuencias distintas sobre contexto, recursos y coordinación.

agent-extension-packages puede distribuir varias skills junto con otros artefactos. El paquete es una unidad de distribución; cada skill conserva su procedimiento. Agruparlos no significa que todos se activen juntos. Tampoco el descubrimiento de un paquete prueba que cada componente sea compatible con el cliente o que el usuario haya confiado su ejecución.

Mapa comparativo de artefactos

La tabla siguiente compara funciones; no establece un stack obligatorio ni una lista de componentes que todo agente deba tener. La misma implementación puede combinar varias funciones, pero conservar sus diferencias permite preguntar qué está ocurriendo realmente.

Elemento	Función principal	Uso o activación	Límite de autoridad
Task Prompt	Encargar trabajo concreto.	Solicitud actual o plantilla instanciada.	No concede acceso técnico.
Persistent Instruction	Orientar trabajo en un scope.	Carga según el contrato del cliente.	Texto no equivale a enforcement.
Skill	Aportar un procedimiento reutilizable.	Selección pertinente a la tarea.	Recursos sujetos a permisos.
Tool	Observar o actuar mediante una interfaz.	Invocación efectiva de la operación.	Capacidad limitada por entorno y políticas.
Profile	Configurar una especialización.	Selección o instanciación soportada.	Configuración no es autorización universal.
Subagent	Ejecutar trabajo delegado.	Inicio y coordinación de la delegación.	Autoridad efectiva de esa ejecución.
Hook	Ejecutar comportamiento asociado a eventos.	Evento y condiciones configurados.	Depende de cobertura y handler.
Extension Package	Distribuir artefactos y capacidades.	Instalación, carga y uso diferenciados.	Instalar no demuestra confianza.
MCP	Interoperar con capacidades y contexto.	Interacción de clientes y servidores.	Protocolo no otorga permiso comercial.
Execution Record	Conservar evidencia del trabajo.	Registro y recuperación posterior.	Evidencia no autoriza nuevos efectos.

Skill y tool tampoco son equivalentes a MCP. Es un protocolo de interoperabilidad; un servidor puede exponer herramientas que una skill utilice. La extensión oficial de skills para MCP contempla descubrir y recuperar estos artefactos. Ese transporte no convierte al servidor en una skill ni hace automática su activación. El canonical del protocolo desarrolla su extensión sin confundirla con el concepto o formato de Agent Skills.

Concepto, especificación y SKILL.md

Hay tres niveles semánticos. Agent Skill es el concepto. Agent Skills es una especificación abierta de representación. SKILL.md es un artefacto definido por esa especificación. Adoptar el formato puede facilitar intercambio, pero la definición conceptual no debe reducirse al nombre del archivo ni transformarse en una garantía de comportamiento idéntico entre productos.

En la especificación oficial consultada el 2026-10-26, una skill se organiza como un directorio con SKILL.md: frontmatter YAML y cuerpo Markdown. name y description son metadata requerida. Se permiten campos opcionales como licencia, compatibilidad y metadata; allowed-tools se describe como experimental. Estos detalles pertenecen a la especificación vigente, no al schema de documentos del Atlas.

El contenido de una skill puede incluir referencias, ejemplos, scripts o assets. La especificación no exige que toda skill tenga todos esos recursos. Un procedimiento breve puede bastar cuando el conocimiento adicional no es necesario. La ausencia de un script no vuelve incompleta a una skill; la presencia de muchos archivos tampoco demuestra que aporte una capacidad útil.

Un canonical del Atlas sobre skills no es una skill ejecutable. Su metadata identifica conocimiento y sus wikilinks organizan relaciones conceptuales. Un archivo SKILL.md puede ser documentación consumida por un runtime con otro contrato. Mantener ambos niveles evita introducir de forma accidental reglas del renderer, del editor o de un producto dentro del formato canónico de conocimiento.

Discovery y Activation

Discovery responde cómo el sistema conoce las skills disponibles. Puede involucrar rutas del filesystem, configuración, metadata o un catálogo. La ubicación y las fuentes aceptadas son decisiones de implementación. Una carpeta existente puede quedar fuera de las rutas inspeccionadas; una skill catalogada puede no estar disponible para una ejecución concreta por restricciones del cliente o del entorno.

Activation responde cuándo se aplica una skill a la tarea. Puede haber selección explícita de la persona o selección por relevancia realizada por el sistema. Codex documenta ambas formas. Eso ejemplifica una implementación; no obliga a otros hosts a compartir nombres, criterios o comportamiento. Descubrir una skill no implica usarla en cada interacción.

Una descripción ayuda a seleccionar, pero puede ser demasiado amplia, imprecisa o competir con otra. Una skill de revisión de contratos y otra de diagnóstico de tests podrían coincidir parcialmente. La tarea necesita el procedimiento pertinente, no activar todas por precaución. Si el sistema elige mal, disponer de más skills puede agregar confusión en vez de mejorar el trabajo.

También interesa distinguir selección de aplicación efectiva. El agente puede identificar una skill sin cargar su versión vigente o puede leerla sin seguir una restricción importante. El nombre que aparece en un reporte no demuestra cumplimiento. Para revisar el resultado se necesita relacionar la tarea, el procedimiento realmente disponible y la evidencia obtenida durante su uso.

Progressive Disclosure

Progressive Disclosure organiza acceso gradual: metadata suficiente para identificar pertinencia, instrucciones cuando la skill se selecciona y recursos adicionales según necesidad. Reduce la obligación de incorporar todos los detalles desde el inicio. La especificación de Agent Skills describe esta idea; cada host decide cómo la realiza y qué límites aplica a la carga.

El beneficio esperado es conservar capacidad informativa sin llenar el contexto activo con material irrelevante. No significa ocultar restricciones críticas hasta después de ejecutar una acción. Si una condición determina si el procedimiento puede usarse, debe resultar visible antes de ese uso. Una referencia opcional no es un lugar adecuado para esconder una autorización necesaria.

En Commerce, la descripción podría identificar una skill para investigar conversiones monetarias. El procedimiento principal puede orientar cómo localizar contratos y pruebas. Un documento de ejemplos puede cargarse solo si aparece un caso de redondeo. El orden ilustra una estrategia de información, no una API universal ni un número obligatorio de etapas o tokens.

Recursos de apoyo y scripts

Los recursos permiten separar instrucciones centrales de material especializado. Una referencia explica un contrato; un ejemplo ayuda a reconocer un caso; una plantilla guía un resultado; un script ejecuta una operación. El valor está en su relación con la tarea y en que puedan localizarse e interpretarse, no en reproducir una estructura de directorios por costumbre.

Un script es un recurso posible, no la skill completa. Su ejecución sigue sujeta a agent-execution-environment, agent-permissions-and-approval-boundaries y agent-sandboxing. Un procedimiento que indica consultar una base productiva no concede acceso a ella. Tampoco un campo declarativo de herramientas reemplaza las políticas efectivas del host y del servicio externo.

Los recursos pueden quedar obsoletos o incorporar entradas no confiables. Descargar una referencia no vuelve autoritarias sus instrucciones. Ejecutar código del paquete requiere considerar procedencia y efectos, igual que otros inputs de supply chain. Este documento conserva la frontera sin configurar controles de seguridad ni convertir cada skill en una política organizacional.

Una referencia relativa también necesita una base de resolución correcta. Si un recurso no puede localizarse, el agente no debería sustituirlo silenciosamente por una versión recordada de otro proyecto. Puede identificar qué parte del procedimiento depende de ese material y continuar con lo independiente, si sigue siendo válido. Un script presente pero incompatible con el sistema operativo merece la misma precisión: disponibilidad del archivo y capacidad de ejecutarlo son hechos distintos. Esa distinción ayuda a separar un defecto de packaging de un problema del procedimiento o de la preparación del entorno.

Composición y portabilidad

Combinar procedimientos puede ser útil: investigar un defecto, preparar un cambio y revisar evidencia son capacidades relacionadas. Sin embargo, referencias entre skills no garantizan dependencias resueltas, ejecución recursiva o chaining automático. Esas propiedades requieren contratos del sistema que las implemente. El formato de una skill, por sí solo, no define un motor de workflows.

La composición también puede introducir conflictos. Dos procedimientos pueden asumir distintos gestores de paquetes o proponer cambios fuera del mismo scope. Resolverlos exige examinar las condiciones actuales; concatenar instrucciones no produce un procedimiento coherente automáticamente. El agente sigue necesitando interpretar el objetivo y respetar restricciones de mayor autoridad que los recursos consultados.

Portabilidad del formato significa que varias implementaciones pueden reconocer un artefacto compartido. No garantiza ejecución equivalente. Modelo, agent-harness, herramientas, permisos, carga de recursos y extensiones pueden variar. Una skill basada en una capacidad del IDE puede necesitar adaptación en un entorno remoto que solo ofrece terminal. Esa diferencia no invalida el concepto, pero limita lo que puede prometer el paquete.

Las convenciones de invocación también varían. Claude Code documenta sus skills dentro de su propio mecanismo de extensibilidad. Que dos clientes reconozcan un directorio no prueba igualdad de precedencia, permisos o selección. Los detalles actuales deben atribuirse y fecharse, en vez de convertirse en reglas durables del Atlas.

Evaluación y mantenimiento

En una revisión de Commerce, el agente puede seleccionar una skill para contrastar contratos HTTP, consultar sus referencias y ejecutar una prueba existente. El resultado revisable debe separar qué procedimiento estuvo disponible, qué acciones se realizaron y qué evidencia se obtuvo. Si la skill recomendaba una comprobación que no pudo ejecutarse, haber leído sus instrucciones no permite afirmar que el contrato quedó verificado.

Un caso adverso útil sería un encargo parecido que excluye modificar código. La skill debería ayudar a investigar sin ampliar silenciosamente el scope. Otro caso puede retirar una herramienta opcional: interesa si el procedimiento conserva una alternativa válida o reconoce el bloqueo. Estos ejemplos permiten evaluar límites y condiciones de uso, además del camino exitoso, sin introducir una plataforma de evaluación ni exigir que todo paquete incluya su propio ejecutor de tests.

Una skill merece evaluación por utilidad y corrección en tareas representativas. Interesa si ayuda a obtener el resultado esperado, respeta límites y produce evidencia suficiente. Que el procedimiento se cargue o que su sintaxis sea válida prueba solamente parte de la integración. Una skill bien formada puede orientar un cambio incorrecto por un supuesto de dominio equivocado.

Conviene conservar casos donde ayuda, donde falla y donde no debería activarse. Si una actualización modifica recursos o instrucciones, tareas anteriores pueden revelar regresiones. agent-evaluation desarrolla la evaluación de agentes y tareas de coding, sin imponer un framework ni una métrica universal. Aquí importa separar disponibilidad, aplicación y calidad del resultado.

El mantenimiento incluye retirar instrucciones obsoletas, comprobar referencias y evitar duplicaciones con guía del repositorio. Una skill que acumula toda excepción histórica puede volverse difícil de seleccionar y aplicar. La unidad útil es una capacidad comprensible, no el paquete más extenso posible. Dividirla solo tiene sentido cuando aparecen responsabilidades suficientemente independientes para justificarlo.

Relaciones y fuentes

lifecycle-hooks activa comportamiento por eventos; una skill se selecciona por su relación con una tarea. development-context-and-execution-records puede conservar qué procedimiento se utilizó y qué evidencia produjo. ai-assisted-software-engineering ubica estas piezas junto a contexto e instrucciones. Ninguna relación exige instalar skills reales en este repositorio.

Fuentes primarias consultadas el 2026-10-26. Definiciones comparativas, matriz y ejemplos son síntesis editorial. Los campos del formato y las conductas de producto se atribuyen a sus fuentes.

• Agent Skills: Specification.
• OpenAI: Build skills.
• Anthropic: Extend Claude with skills.
• MCP: Agent Skills extension, solamente para delimitar transporte y capacidad.