Skip to content

Habilidades: SKILL.md ​

Al terminar esta sección, podrás escribir un SKILL.md y hacer que tu Agent lo cargue automáticamente cuando lo necesite. Lo probaremos en la práctica con la habilidad de "escribir el informe semanal".

Qué es una habilidad ​

Las herramientas resuelven "qué se puede hacer" (leer archivos, ejecutar comandos); las habilidades resuelven "cómo se debe hacer esto".

Es como el manual de procedimientos que una empresa le da a un empleado nuevo: qué subtítulos debe tener un informe semanal, no inventar datos, con qué nombre de archivo guardarlo… Eso no son capacidades, son procedimientos. Si escribes los procedimientos en un archivo, el Agent los aprende con solo leerlo cuando lo necesite.

Agent Skills es justamente un formato de este tipo: una habilidad es una carpeta que contiene un SKILL.md (un bloque de metadatos YAML al inicio, seguido de los pasos escritos en Markdown), y puede incluir además scripts, material de referencia, etc.

Historia: Anthropic publicó Skills el 16 de 10 de 2025, y el 18 de 12 de 2025 publicó Agent Skills como estándar abierto en agentskills.io. El 4 de 11 de 2026, el proyecto aprobó su documento de gobernanza y, según dicho documento, se establecerá como un proyecto bajo la Linux Foundation, con licencia Apache-2.0.

Escribir un SKILL.md ​

Nuestra habilidad de "escribir el informe semanal" está en skills/weekly-report/SKILL.md:

markdown
---
name: weekly-report
description: Organizar los registros de trabajo de una carpeta en un informe semanal
---

# Escribir el informe semanal

1. Usa list_dir para ver qué archivos de registro hay en la carpeta indicada, y read_file para leerlos uno por uno.
2. Organiza el contenido bajo cuatro subtítulos: "Completado esta semana / En curso / Plan para la próxima semana / Necesita ayuda", con una frase por punto e indicando de qué día se trata.
3. No inventes contenido que no esté en los registros; en los subtítulos sin información escribe "ninguno".
4. Usa write_file para guardar el resultado en 周报.md; antes de escribirlo, muéstrale el texto completo al usuario.

Los dos campos obligatorios de la especificación:

CampoRequisitos
nameNo más de 64 caracteres, solo letras minúsculas, números y guiones; debe tener el mismo nombre que la carpeta que lo contiene
descriptionDe 1 a 1024 caracteres; explica con claridad "qué hace" y "cuándo usarlo"

Los campos opcionales son license, compatibility, metadata, y el experimental allowed-tools.

Divulgación progresiva: no hace falta leerlo todo de una vez ​

Si hay decenas de habilidades, meterlas todas en el prompt es un desperdicio. El enfoque de la especificación tiene tres niveles:

  1. Al iniciar, leer solo los metadatos: el name y la description de cada habilidad, unos 100 tokens;
  2. Leer el cuerpo solo cuando se use: el SKILL.md completo, recomendado por debajo de 5000 tokens y de 500 líneas;
  3. Leer los recursos solo cuando hagan falta: los scripts y archivos de referencia incluidos.

Hacer que tu propio Agent admita habilidades ​

En el sitio de la especificación hay un artículo específico sobre "añadir soporte de Skills a tu Agent". El núcleo son solo dos cosas: poner el catálogo de habilidades en el prompt del sistema y ofrecer una forma de leer las habilidades. Nuestra implementación:

python
def load_skills():
    skills = {}
    for f in sorted((HERE / "skills").glob("*/SKILL.md")):
        meta = dict(re.findall(r"^(\w+):\s*(.+)$", f.read_text(encoding="utf-8").split("---")[1], re.M))
        skills[meta["name"]] = (meta["description"], f)
    return skills

SKILLS = load_skills()

def load_skill(name):                               # 用到时才把完整说明读进来(渐进式披露)
    return SKILLS[name][1].read_text(encoding="utf-8") if name in SKILLS else f"没有叫 {name} 的技能"

SYSTEM = ("……\n可用技能(需要时先 load_skill):\n"
          + "\n".join(f"- {n}:{d}" for n, (d, _) in SKILLS.items()))

Luego añade load_skill a la lista de herramientas. La especificación da además dos sugerencias: conviene que el parámetro name de la herramienta sea un enum (que solo permita nombres de habilidades existentes), para evitar que el modelo invente habilidades inexistentes; y cuando no haya ninguna habilidad, no pongas un catálogo vacío ni registres esta herramienta. Por otra parte, .agents/skills/ se está convirtiendo en la convención universal de catálogo de habilidades compartida entre distintos clientes.

Pruébalo ​

bash
python agent.py "用写周报的技能,把 worklog 文件夹整理成周报"

Ejecución real nuestra en qwen3:8b:

text
  [1] load_skill({"name": "weekly-report"})
  [2] read_file({"path": "/worklog/11-16.txt"})
  [3] list_dir({"path": "./worklog"})
  [4] read_file({"path": "./worklog/11-16.txt"})
  [5] read_file({"path": "./worklog/11-18.txt"})
  [6] read_file({"path": "./worklog/11-20.txt"})

Agent: resultado del informe semanal:
# Informe semanal
## Completado esta semana
- Lunes: corregido el desajuste de estilos de la página de inicio de sesión en Safari
……
## Necesita ayuda
- Ninguno

Cuando confirmes el contenido, generaré el archivo 周报.md.

Fíjate en que cumplió las dos cosas escritas en la habilidad: los cuatro subtítulos completos, y "ninguno" donde no había información; y antes de escribir el archivo te mostró el texto completo. Nada de esto lo impone el código: está escrito en el SKILL.md.

Pon a prueba tus conocimientos¿Cuál es la diferencia entre habilidades y herramientas?

Compruébalo ​

  • Puedo nombrar los dos campos obligatorios del SKILL.md y sus requisitos
  • Puedo explicar los tres niveles de la divulgación progresiva
  • Logré ejecutar la habilidad de escribir el informe semanal y escribí una habilidad propia

El próximo capítulo conecta con el ecosistema: MCP: escribir un servidor y conectarlo.

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.