Las habilidades de los agentes son código: define su alcance, revela información al respecto, crea scripts para ellas y pruébalas.

Un archivo SKILL.md se parece a documentación, pero editarlo modifica el comportamiento de un agente. Eso lo acerca más al código que a la prosa, por lo que debe diseñarse, delimitarse y probarse en consecuencia.

Las habilidades no son documentación

La reacción habitual al crear una habilidad para un LLM es escribir más: explicar la arquitectura, añadir ejemplos, describir casos límite e incluir información de contexto para que el modelo comprenda por qué las cosas funcionan de esa manera. Esa reacción suele ser errónea.

Una habilidad no es un manual para un desarrollador que aprende tu sistema. Es un contexto que se inyecta en un agente que está ocupado intentando completar una tarea. Esa diferencia determina todo el diseño. La pregunta útil no es cómo explicar el sistema al modelo, sino qué necesita saber el agente para tomar la decisión correcta a continuación.

Desde ese punto de vista, varias opciones se vuelven más sencillas:

• Escribir instrucciones como procedimientos
• Hacer que las condiciones de activación sean específicas
• Cargar información de forma progresiva
• Transferir las tareas deterministas a scripts
• Probar habilidades en tareas reales

Solo conocimiento procedural

Los agentes de programación modernos ya manejan una cantidad sorprendente de aspectos relacionados con la ingeniería de software en general. Conocen Git y npm, y entienden Angular, React, TypeScript, SQL, APIs REST, marcos de pruebas y configuración de CI. Una habilidad que simplemente repite esto casi no aporta nada:

When implementing an Angular component, use TypeScript.
Write maintainable code.
Follow Angular best practices.
Add tests.

Quema el contexto sin proporcionar nada que le faltara al modelo. Las habilidades útiles capturan conocimientos específicos de tu entorno:

When modifying an Angular application in this repository:

1. Locate the closest project.json belonging to the affected application.
2. Check whether the project uses Vitest or Karma before generating tests.
3. For applications under apps/trading/, do not import directly from apps/shared/.
4. Run the affected project's test target rather than the workspace-wide test command.
5. Before changing a public interface in libs/order-entry/, search for consumers in
   apps/trading-terminal and apps/blotter.tp

Aquí el agente ha aprendido algo que no podía deducir con fiabilidad de la documentación pública de Angular, es decir, cómo debe proceder el trabajo en un repositorio específico. Eso es precisamente para lo que sirven las habilidades.

El formato Agent Skills organiza esto como un directorio que contiene un SKILL.md y, opcionalmente, scripts y recursos. Los metadatos están disponibles para su descubrimiento, y las instrucciones completas junto con los archivos de soporte se cargan solo cuando son necesarios. El formato del archivo no es el punto clave; lo importante es la distinción entre las capacidades generales del modelo y los conocimientos que su entorno debe proporcionar.

El contexto es un presupuesto

Todo lo que se proporciona a un agente consume contexto. Las descripciones de herramientas, los esquemas de herramientas MCP, las instrucciones del repositorio, el historial de conversaciones y las descripciones de habilidades lo consumen, y el cuerpo de una habilidad activada consume aún más. Por lo tanto, la pregunta no es simplemente si alguna información es útil, sino si resulta útil para la tarea en cuestión.

Supongamos que estas habilidades están instaladas:

angular-testing
angular-migration
jira-workflow
postgres-debugging
release-process
accessibility-review
storybook
incident-response
performance-profiling

Cuando el trabajo consiste en reparar una prueba de unidad de Angular que no funciona, el agente no tiene motivo para conocer el proceso de lanzamiento ni los pasos para depurar PostgreSQL. Por eso, el descubrimiento es casi tan importante como el contenido. Compare dos descripciones: esta es extremadamente fácil de activar:

---
name: testing
description: Helps run tests in our repository.
---

Este es mucho más preciso:

---
name: angular-unit-testing
description: >
  Run and debug Angular unit tests in projects using Karma or Vitest.
  Use for Angular unit-test failures and test creation.
  Do not use for Playwright E2E tests, React projects, or backend tests.
---

La segunda descripción va más allá de indicar qué es la habilidad. Establece un límite de enrutamiento que mantiene las instrucciones irrelevantes fuera del contexto de trabajo. Una charla sobre el diseño de habilidades para agentes LLM ilustra bien este punto: los metadatos de las habilidades no son solo decoración administrativa. Las reglas de activación poco claras introducen instrucciones útiles en tareas incorrectas, mientras que las reglas demasiado estrictas impiden que la habilidad sea encontrada en absoluto.

La divulgación progresiva es mejor que un SKILL.md enorme

Un error común es permitir que SKILL.md se convierta en una pequeña wiki interna. Comienza con veinte líneas, luego alguien agrega pasos de despliegue, después solución de problemas, luego ejemplos y finalmente opciones de configuración. Después de tres meses, el agente debe leer 1,500 líneas para modificar un solo archivo.

Estructúralo de la manera en que estructurarías un software:

angular-workflow/
├── SKILL.md
├── testing.md
├── migrations.md
├── architecture.md
└── scripts/
    ├── affected-projects.ts
    └── verify-boundaries.ts

SKILL.md contiene únicamente la lógica de enrutamiento:

# Angular repository workflow

When modifying an Angular project:
1. Identify the affected project.
2. Read `architecture.md` when changing dependencies between projects.
3. Read `testing.md` when creating or modifying tests.
4. Read `migrations.md` when changing Angular versions or framework APIs.
5. Run `scripts/verify-boundaries.ts` after changing imports between projects.

Las instrucciones detalladas de prueba solo se incluyen en el contexto cuando una tarea implica pruebas. Anthropic lo describe como divulgación progresiva: el agente carga primero los metadatos, lee el cuerpo principal una vez que la habilidad resulta relevante y abre los archivos a los que se hace referencia más tarde, solo si es necesario. El objetivo no es transmitir la mayor cantidad posible de conocimiento, sino entregar el conocimiento adecuado en el momento oportuno.

Deje que los scripts apliquen lo que pueden aplicar

Otra distinción útil es la siguiente: las instrucciones sirven para tomar decisiones, mientras que los scripts se encargan de tareas deterministas. Imagine una habilidad que diga lo siguiente:

Find all applications under apps/.
Check their Angular versions.
Ignore archived applications.
Compare their versions with the root package.json.
Report applications that are behind.

Un agente puede llevarlo a cabo, pero solo inspeccionando repetidamente directorios, interpretando archivos, decidiendo qué se considera archivado, haciendo un seguimiento del estado y probablemente realizando muchas llamadas a herramientas. Cuando una operación puede expresarse con exactitud, escríbala una sola vez:

node scripts/check-angular-versions.mjs

La habilidad simplemente indica cuándo ejecutarla y qué hacer con el resultado:

When checking Angular version consistency, run
`node scripts/check-angular-versions.mjs`.

If it reports mismatches, inspect only the projects listed in the output.

Esto es mejor por varias razones. El script puede someterse a pruebas unitarias y se comporta de la misma manera en cada ocasión. Requiere menos decisiones del modelo y, con frecuencia, menos llamadas a herramientas. Además, cuando algo falla, se puede reproducir el problema sin tener que pedirle a un LLM que repita su razonamiento.

Nada de esto implica reemplazar a los agentes por scripts. Significa elegir la abstracción adecuada. Utilice el modelo para tomar decisiones, como determinar qué proyectos probablemente se verán afectados por un cambio arquitectónico. Utilice código para algoritmos precisos, como listar qué proyectos importan un paquete determinado. El agente coordina ambos enfoques, y esa combinación es mejor que codificar todo un flujo de trabajo en inglés.

Herramientas y habilidades resuelven problemas diferentes

Una herramienta le brinda a un agente una acción, mientras que una habilidad enseña cuándo y cómo utilizar esas acciones. Una herramienta de línea de comandos podría ofrecer una forma de calcular los proyectos afectados:

tr project affected --base main

La herramienta proporciona la capacidad. La habilidad de correspondencia aporta los conocimientos de la organización:

Before modifying a shared library:
1. Run `tr project affected --base main`.
2. If either `trading-terminal` or `blotter` is affected, run their integration suites.
3. If more than five applications are affected, stop and inspect the dependency change
   before proceeding.1

La CLI no tiene idea de por qué cinco aplicaciones afectadas deberían parecer sospechosas, y el skill no necesita saber cómo funciona el recorrido de dependencias. Esa es una separación clara. La misma división se aplica cuando la capacidad es proporcionada por una orden de shell, una API web, un servidor MCP o cualquier otra interfaz: no entierre políticas en herramientas de bajo nivel a menos que realmente pertenezcan allí, y no escriba algoritmos deterministas como texto narrativo a menos que sea necesario.

Más skills no son automáticamente mejores

Un enfoque tentador en el desarrollo de agentes es recopilar skills que parezcan útiles, instalarlos todos y asumir que el agente se vuelve más capaz. La evidencia sugiere ser mucho más selectivo.

SkillsBench abarca 86 tareas distribuidas en 11 dominios. Según la primera versión de su estudio, las habilidades seleccionadas elevaron las tasas de aprobación en un promedio de 16,2 puntos porcentuales, con grandes diferencias entre los dominios. La ingeniería de software mejoró solo 4,5 puntos, y 16 de las 84 tareas tuvieron un rendimiento peor al incorporar esas habilidades. Las habilidades generadas por los propios modelos no supusieron ningún beneficio promedio.

SWE-Skills-Bench analizó 49 habilidades públicas aplicadas a tareas reales de ingeniería de software. Treinta y nueve de ellas no generaron mejora alguna en la tasa de aprobación, y el beneficio promedio fue de solo 1,2 puntos. Un pequeño número de habilidades altamente especializadas, siete en total, mejoraron los resultados hasta en 30 puntos. Otras tres empeoraron la situación hasta en 10 puntos, ya que sus indicaciones se referían a una versión diferente de la utilizada en el proyecto.

Eso coincide con lo que la arquitectura predice. Una habilidad genérica compite con lo que el modelo ya sabe, mientras que una muy específica puede proporcionar precisamente el hecho que falta:

When our generated API clients change, regenerate schemas before running typecheck.

Eso tiene valor. Esto tiene mucho menos:

Always think carefully before modifying APIs.

La regla general: no cree una habilidad solo porque existe una tarea. Créela cuando haya conocimientos procedimentales que el agente siga omitiendo.

Las habilidades necesitan pruebas

Esto podría ser el cambio conceptual más importante. Dado que modificar SKILL.md afecta el comportamiento, las consecuencias son similares a los cambios en el código:

• Si se elimina una instrucción, es posible que el agente omita una verificación necesaria.
• Si se amplía la descripción, la habilidad podría activarse durante tareas no relacionadas.
• Si se agrega un documento de referencia extenso, el uso de tokens podría aumentar sin mejores resultados.
• Si se reescribe un procedimiento, las tasas de éxito podrían disminuir.

Por lo tanto, pruébela. Para una habilidad relacionada con migraciones a Angular, un conjunto de evaluación podría incluir una tarea como:

Upgrade application A from Angular 20 to Angular 21.

con expectativas de este tipo:

Expected:
- correct migration command executed
- generated migration changes preserved
- application tests executed
- unrelated applications untouched

Otra tarea:

Upgrade a shared library consumed by applications A and B.

con sus propias expectativas:

Expected:
- consumers discovered
- both affected applications typechecked
- dependency constraints respected

Y un tercero:

Modify a React application in the same monorepo.

cuyo resultado esperado es la ausencia de activación:

Expected:
- Angular migration skill is NOT activated

Ese caso final cuenta tanto como cualquier ejecución exitosa, así que pruebe ambas direcciones: la habilidad debería activarse aquí y no allí. Una herramienta llamada SkillGrade se basa en esta idea. Defina tareas, ejecute al agente repetidamente y luego califique cada ejecución mediante verificaciones precisas, una rúbrica aplicada por un LLM sobre la sesión grabada, o ambos juntos. Puede aplicar este principio incluso sin ella. Lo importante es tratar una habilidad como algo que puede deteriorarse. Modifique una habilidad sin poder determinar si la nueva versión supera a la antigua, y estará editando lógica de producción sin probarla.

Comience con los fallos, no con un mercado de habilidades

La forma más sencilla de crear habilidades inútiles es preguntarse qué habilidades debería tener un agente de programación. Obtendrá una lista de pruebas, depuración, revisión de código, documentación, arquitectura, flujos de trabajo de Git, accesibilidad, seguridad y veinte otros temas que el modelo ya comprende razonablemente bien.

Un punto de partida mejor es la propia historia del agente. Busque fallas repetidas. Quizás el agente:

• ejecuta todo el conjunto de pruebas en un enorme monorepo en lugar de centrarse en el proyecto afectado
• sigue violando los límites de las dependencias en el repositorio
• elige la ruta de migración técnicamente válida pero omite un paso de compatibilidad interno
• edita los archivos generados en lugar de los esquemas que los crean
• pasa cinco minutos redescubriendo siempre el mismo procedimiento de depuración cada vez que falla un servicio

Esos son indicadores de habilidades necesarias. El ciclo de vida es el siguiente: observar una falla repetida, identificar el conocimiento procedural que falta, redactar la habilidad más útil y mínima, trasladar los pasos deterministas a scripts, crear tareas de evaluación representativas, medir y luego conservar, mejorar o eliminar dicha habilidad. La mejora conduce nuevamente a su reescritura.

Tenga en cuenta la última opción, ya que eliminarla es una acción legítima. Una habilidad que no mejora el comportamiento no es inofensiva; añade contexto, carga de mantenimiento y una instrucción más que podría entrar en conflicto con algo posteriormente.

La verdadera abstracción es el contexto controlado

A menudo la gente describe las habilidades como una forma de ampliar las capacidades de los agentes. Eso es cierto, pero oculta un problema de ingeniería mucho más interesante. Suministrar información a un agente es fácil; decidir qué información resulta relevante durante cada ejecución es lo difícil.

Un entorno de agente bien diseñado termina pareciéndose menos a un único prompt gigantesco y más a un sistema de software con capas. Siempre están presentes el conocimiento general del modelo y pequeñas instrucciones globales. Solo se incorporan cuando una tarea los necesita: las habilidades específicas para esa tarea, referencias cargadas condicionalmente, herramientas deterministas y el contexto del repositorio en tiempo de ejecución. Cada capa tiene su propia función. Si se difuminan esas responsabilidades, el contexto se vuelve excesivo hasta que resulta difícil razonar sobre el comportamiento. Al separarlas, las habilidades se vuelven agradablemente sencillas, lo cual es bueno.

Una buena habilidad no es un prompt llamativo. Es un fragmento compacto de conocimiento procedural que se activa en la situación adecuada, utiliza herramientas deterministas cuando es posible y se verifica contra los fallos que está diseñada para evitar.

Lecturas relacionadas

• Las cinco capas de un Agent Harness, con código que falla sin ellas — Un recorrido práctico por los cinco lugares donde un Agent Harness aplica reglas en el código, desde los límites de ejecución hasta las tuberías de contexto, y lo que la investigación puede y no puede demostrar.
• Usando Codex en VS Code: ámbito, puntos de recuperación y soluciones para los cuellos de botella habituales — Un camino práctico a través de la extensión Codex para VS Code: instalación, inicio de sesión, una primera tarea de Agent con límites definidos, uso en la nube frente a CLI, configuración compartida, y soluciones para problemas en WSL, aprobaciones y autenticación remota.