Cómo escribir SKILL.md y descripciones de herramientas en Markdown para agentes de IA

Los asistentes de IA se vuelven mucho más útiles cuando pueden seguir instrucciones estables, cargar conocimiento específico de un dominio y utilizar herramientas de manera segura. Markdown es un formato muy práctico para esta capa porque es fácil de leer para las personas, admite control de versiones en Git y está estructurado de manera óptima tanto para los humanos como para los modelos de lenguaje.

Este artículo explica cómo escribir archivos SKILL.md basados en Markdown, archivos de instrucciones de agentes y descripciones de uso de herramientas. El objetivo no es hacer que los prompts sean más largos, sino hacer que las capacidades sean más fáciles de descubrir, comprender y aplicar por parte del agente de IA en el momento adecuado.

¿Qué es un archivo SKILL.md?

Un archivo SKILL.md es un documento de instrucciones en Markdown que describe una capacidad reutilizable. En sistemas como Claude Code, las habilidades (skills) son artefactos guardados en un directorio de habilidades, y cada habilidad se define mediante un archivo SKILL.md. El concepto central es el mismo en los diferentes sistemas de agentes: un documento corto y estructurado que le indica al agente cuándo usar una capacidad, qué flujo de trabajo seguir y dónde viven los scripts o referencias de apoyo.

El modelo mental a seguir es simple:

Un prompt normal le dice a la IA qué hacer en el paso actual.
Una habilidad (Skill) le enseña a la IA cómo realizar una clase de tareas de forma repetitiva.
Una descripción de herramienta le indica a la IA cuándo y cómo llamar a una función o API externa específica.

Markdown es una excelente opción porque una habilidad consta principalmente de instrucciones, ejemplos, restricciones y enlaces a archivos de soporte.

Por qué Markdown funciona bien para las habilidades de agentes

Las instrucciones de los agentes deben servir a dos lectores: el modelo de IA y el mantenedor humano. Markdown apoya a ambos.

Para la IA, los encabezados y las listas separan los disparadores de activación, los pasos del flujo, las restricciones, los ejemplos y el comportamiento de mitigación de errores. Para los humanos, el mismo archivo se puede revisar en Git, editar en cualquier editor de texto y documentar directamente junto al código de desarrollo.

Esto es sumamente importante para las habilidades y herramientas porque las instrucciones poco claras pueden causar errores graves en los flujos automatizados. Una habilidad vaga puede activarse en el momento equivocado. Una descripción de herramienta vaga puede llevar al modelo a invocar una API con los argumentos incorrectos. Una nota de seguridad omitida puede hacer que el agente actúe sin suficientes pruebas de confirmación.

Diferencia entre habilidades y descripciones de herramientas

Las habilidades y las herramientas están relacionadas, pero cumplen propósitos diferentes:

| Elemento | Propósito | Ejemplo | |---|---|---| | Habilidad (Skill) | Enseñar un flujo de trabajo reutilizable o procedimiento operativo estándar | „Cómo revisar un Pull Request“ | | Descripción de herramienta | Indicarle al modelo qué hace una función y cuándo usarla | „Buscar issues en GitHub mediante una consulta“ | | Prompt de sistema | Establecer el comportamiento global del asistente | „Sé conciso y verifica los hechos“ | | Reglas del proyecto | Explicar las convenciones locales del repositorio de código | „Usa pnpm y no ejecutes el comando build manualmente“ |

Según las APIs de OpenAI y las guías de SDK de agentes, las herramientas (tools) son formas en que los modelos obtienen datos, llaman a APIs externas, ejecutan código o interactúan con el entorno físico. Las directrices de los SDKs recomiendan: las descripciones de las herramientas deben ser cortas y precisas, explicando qué hace el elemento y cuándo invocarlo. Ese mismo principio se aplica a las habilidades en Markdown: sé explícito con el propósito y la activación.

Estructura práctica de un archivo SKILL.md

Un archivo de habilidad útil debe responder a seis preguntas clave:

¿Qué capacidad proporciona esta habilidad?
¿Cuándo debe el agente activarla?
¿Cuándo debe el agente evitar usarla?
¿Qué pasos concretos debe seguir el agente?
¿Qué archivos locales, scripts o referencias están disponibles?
¿Cómo debe ser el formato de la respuesta final?

Aquí tienes una plantilla reutilizable:

---
name: markdown-conversion-review
description: Utiliza esta habilidad al revisar, limpiar o mejorar documentos Markdown convertidos a partir de archivos PDF, Word, HTML o formatos de oficina.
---

# Habilidad: Revisión de calidad en conversión a Markdown

## Cuándo activar esta habilidad (Use This Skill When)
- El usuario solicita limpiar o normalizar Markdown convertido.
- Se necesita preparar un documento para su uso en un README, documentación, blog o contexto de prompt de sistema.
- El origen contiene tablas, encabezados, enlaces o bloques de código rotos que necesitan reparación.

## Cuándo no activar esta habilidad (Do Not Use This Skill When)
- El usuario solo hace una pregunta conceptual básica sobre la sintaxis de Markdown.
- La tarea requiere modificar archivos fuente fuera del documento proporcionado.

## Flujo de trabajo estándar (Workflow)
1. **Auditoría estructural**: Revisa el Markdown convertido para detectar jerarquías rotas, tablas mal formadas, enlaces perdidos y bloques de código sin cerrar.
2. **Preservación del sentido**: Conserva la intención original del autor y el orden del texto a menos que el usuario pida explícitamente reescribir la prosa.
3. **Normalización del formato**: Utiliza sintaxis estándar y sencilla de Markdown para unificar encabezados, listas, enlaces y tablas.
4. **Marcado de límites**: Si ciertos formatos originales no se pueden recuperar con seguridad en Markdown, agrégalos como advertencia al final del archivo.
5. **Entrega de resultados**: Devuelve el Markdown limpio y una nota corta sobre las decisiones clave de formato.

## Criterios de calidad y restricciones (Quality Bar)
- No inventes contenido fuente ausente en el original.
- Conserva el código de desarrollo exactamente igual a menos que se pidan cambios.
- Prefiere un Markdown limpio sobre HTML embebido complejo.

## Formato de salida esperado (Output Format)
Devuelve:
1. El Markdown corregido y normalizado.
2. Notas clave sobre las decisiones de conversión.
3. Lista de problemas de formato no resueltos o irrecuperables.

Los campos del Frontmatter dependerán de las especificaciones del sistema de agentes que utilices. El cuerpo del documento (escenarios, exclusiones, flujo, calidad, formato de salida) es completamente portátil.

Cómo escribir un excelente campo de descripción (Description)

El campo description en la definición de la habilidad o herramienta es el elemento clave, ya que el agente lo utiliza semánticamente para decidir si carga o no dicha capacidad en el hilo de ejecución.

Descripción débil:

description: Ayuda con Markdown.

Descripción excelente:

description: Utiliza esta habilidad cuando el usuario necesite limpiar, normalizar o corregir documentos Markdown convertidos, o prepararlos para su uso en archivos README, blogs, documentación del proyecto o contextos de prompts para IA.

La versión mejorada incluye de forma clara:

El disparador: „cuando el usuario necesite...“
La acción concreta: „limpiar, normalizar o corregir... o prepararlos“
El objeto de trabajo: „documentos Markdown convertidos“
Los casos de uso: „archivos README, blogs, documentación del proyecto o contextos de prompts para IA“

Cómo escribir descripciones de herramientas (Tool Descriptions)

Las descripciones de herramientas deben ser más cortas y concisas que las habilidades. Una herramienta realiza una función de software específica, por lo que el modelo necesita tres datos clave:

¿Qué hace la herramienta?
¿Cuándo debe invocarse?
¿Qué parámetros de entrada requiere?

Ejemplo en formato JSON:

{
  "name": "convert_file_to_markdown",
  "description": "Convierte un archivo PDF, DOCX, PPTX, XLSX, HTML o imagen cargado a formato Markdown cuando el usuario requiera texto editable o contenido estructurado listo para procesamiento por IA.",
  "parameters": {
    "type": "object",
    "properties": {
      "file_id": {
        "type": "string",
        "description": "El identificador del archivo cargado para convertir."
      },
      "preserve_tables": {
        "type": "boolean",
        "description": "Si se deben conservar las tablas como tablas de Markdown cuando sea posible. Por defecto es true."
      }
    },
    "required": ["file_id"]
  }
}

La descripción carece de modificadores vagos y describe directamente los archivos soportados, la intención del usuario y la semántica de cada parámetro de entrada. Esto reduce significativamente los errores de llamada por la IA.

Documentación de herramientas en Markdown

Es una excelente práctica documentar los límites de uso de los herramientas del sistema en archivos Markdown accesibles para el agente:

# Especificación de herramienta: convert_file_to_markdown

## Propósito
Convertir archivos de oficina y documentos cargados a Markdown estándar.

## Cuándo invocar
- El usuario sube un archivo y pide de forma directa convertirlo a Markdown.
- El contenido del documento debe prepararse para análisis de un LLM, una página de docs o una README del repositorio.

## No invocar cuando
- El usuario solo hace una pregunta conceptual sobre el formato Markdown.
- El archivo de entrada ya es Markdown limpio y no requiere procesamiento secundario.

## Parámetros de entrada
| Nombre | Tipo | Requerido | Descripción / Notas |
|---|---|---:|---|
| file_id | string | Sí | Identificador de archivo subido |
| preserve_tables | boolean | No | Intentar mantener el formato de tablas |

## Salida
Texto en Markdown corregido y notas de advertencia de conversión.

## Gestión de errores
- Si el tipo de archivo no está soportado, responde listando los formatos permitidos.
- Si no se puede mantener el diseño original, entrega la mejor extracción de texto y explica el límite.

Esto ayuda a añadir reglas de seguridad y guías operativas que los meros esquemas de código no siempre logran expresar para un agente de IA.

Qué hace que una habilidad sea realmente útil

Una buena habilidad es puramente operativa. Ayuda al agente a tomar decisiones correctas durante la ejecución de una tarea en el mundo real.

1. Disparadores de activación precisos

Usa condiciones específicas en lugar de nombres de categorías generales.

Schlecht:

# Habilidad SEO

Gut:

## Cuándo activar esta habilidad
- El usuario solicita explícitamente optimizar una página para mejorar su rendimiento en buscadores (SEO).
- El contenido requiere añadir meta títulos, meta descripciones, jerarquías de encabezados (H2/H3), enlaces internos o un bloque de preguntas frecuentes (FAQ).
- El usuario menciona estándares como E-E-A-T, revisiones de contenido útil (Helpful Content) o correcciones de calidad del sitio.

2. Criterios de exclusión claros (Non-Goals)

Definir qué no debe hacer el agente es tan importante como guiar lo que debe hacer. Previene que el asistente actúe fuera de su alcance.

## Cuándo no usar esta habilidad
- El usuario pide asesoramiento en temas legales, médicos o financieros que requieran una licencia profesional.
- La tarea requiere inventar testimonios de usuarios, estadísticas de marketing falsas o citas de fuentes inexistentes.
- El tema del documento está totalmente fuera de los productos o propósitos del usuario.

3. Workflow de pasos concretos

Proporciona un flujo paso a paso al que el agente pueda recurrir. Escribe los pasos con suficiente precisión para guiar las acciones, pero deja suficiente flexibilidad para el criterio del agente.

4. Ejemplos de salidas correctas y erróneas

En las guías de IA: un ejemplo de texto real dice más que mil directrices abstractas.

## Ejemplo de tono y estilo

- **A evitar (incorrecto)**:
  „Nuestro revolucionario convertidor garantiza resultados impecables en el 100% de los documentos.“
  *(Razón: Suena exageradamente publicitario y da falsas expectativas al usuario).*

- **A preferir (correcto)**:
  „La herramienta extrae el contenido del documento a formato Markdown. Funciona de manera óptima cuando el archivo de origen cuenta con encabezados claros, listas simples y tablas organizadas.“
  *(Razón: Es descriptivo, honesto y define tanto las capacidades como las limitaciones).*

5. Límites de seguridad y permisos

Si tu habilidad implica ejecutar scripts locales, realizar llamadas API sensibles o editar archivos críticos en el entorno del usuario, establece límites:

## Seguridad y permisos
- Lee los archivos por completo antes de intentar editarlos.
- Nunca elimines archivos del usuario sin solicitar confirmación explícita en el chat.
- Pide permiso antes de enviar datos del usuario a servicios de terceros.

Errores comunes al diseñar habilidades

Error 1: Sobrecargar una habilidad: Un archivo de habilidad debe enfocarse en una única tarea coherente. Si intentas meter SEO, análisis de datos, redacción de textos, anuncios y distribución de correos en una sola „habilidad de marketing“, el agente se confundirá al usarla.
Error 2: Usar adjetivos subjetivos no medibles: Evita reglas vagas como „escribe código de clase mundial“ o „haz el diseño increíble“. En su lugar, usa criterios observables: „añade enlaces de fuente para datos numéricos“, „limita la extensión del texto a 150 palabras“.
Error 3: Ocultar reglas clave en el flujo del texto: Utiliza listas con viñetas. Las reglas redactadas en párrafos largos son ignoradas con frecuencia por los modelos.
Error 4: Falta de gestión de fallos: Las APIs pueden fallar, las redes se caen. Proporciona siempre una instrucción de contingencia (p. ej., „si falla el servicio de red, intenta utilizar el fallback local y notifica al usuario“).

Conclusión

Los archivos SKILL.md en Markdown y las descripciones de herramientas precisas son la infraestructura ideal para guiar el comportamiento de los agentes de IA sin caer en rigidez. Definen con claridad cuándo se activa la capacidad, cómo se ejecuta paso a paso y dónde están las barreras.

Si estás diseñando flujos de IA en torno a la conversión de documentos, bases de conocimientos o tareas de codificación automatizadas, las habilidades en Markdown bien estructuradas son el puente más firme entre tus estándares y la ejecución confiable del agente.