Archivo SKILL.md

SKILL.md es el archivo central de Agent Skills.

Esta sección explicará en detalle la estructura completa de SKILL.md y todos los campos disponibles.

Estructura básica

Un archivo SKILL.md contiene dos partes principales:

  1. YAML Frontmatter (sección de metadatos)
  2. Contenido Markdown (sección de instrucciones)

Ejemplo completo

---
name: my-skill
description: Descripción de la skill, nos dice cuándo usar esta skill
license: Apache-2.0
compatibility: Requiere Python3.10+
metadata:
  author: your-name
  version: "1.0"
---

# Nombre de la skill

Aquí están las instrucciones detalladas de la skill...

## Primer paso

Pasos de operación específicos...

## Segundo paso

Más pasos de operación...

Explicación detallada de los campos de metadatos

A continuación se muestran todos los campos de metadatos admitidos por SKILL.md:

Campo Requerido Restricciones
name Sí Máximo 64 caracteres, solo se pueden usar letras minúsculas, números y guiones, no puede comenzar ni terminar con un guion
description Sí Máximo 1024 caracteres, describe la funcionalidad y los escenarios de uso de la skill
license no Nombre de la licencia o referencia a un archivo de licencia incluido
compatibility no Máximo 500 caracteres, describe los requisitos del entorno (producto objetivo, paquetes del sistema, acceso a red, etc.)
metadata no Pares clave-valor arbitrarios, utilizados para almacenar metadatos adicionales
allowed-tools no Lista de herramientas preaprobadas separadas por espacios (función experimental)

Explicación detallada del campo name

El campo name es el identificador de la skill y debe seguir las siguientes reglas:

  • Longitud: 1-64 caracteres
  • Restricción de caracteres: solo se pueden usar letras minúsculas Unicode (a-z) y guiones (-)
  • Inicio y final: no puede comenzar ni terminar con un guion
  • Caracteres consecutivos: no puede contener guiones consecutivos (--)
  • Requisito de coincidencia: debe coincidir con el nombre del directorio padre

Ejemplos válidos:

name: pdf-processing
name: data-analysis
name: code-review

Ejemplos no válidos:

name: PDF-Processing   # 错误：不能使用大写字母
name: -pdf           # 错误：不能以连字符开头
name: pdf--processing  # 错误：不能包含连续连字符

Explicación detallada del campo description

El campo description es uno de los campos más importantes; le indica al agente cuándo debe activar esta skill.

Una buena descripción debe:

  • Describir la funcionalidad de la skill (qué hace)
  • Explicar los escenarios de uso (cuándo usarla)
  • Incluir palabras clave que ayuden al agente a identificar tareas relacionadas

Ejemplo de una buena descripción:

description: 从 PDF 文件中提取文本和表格，填写 PDF 表单，合并多个 PDF。处理 PDF 文档或用户提及 PDF、表单或文档提取时使用。

Ejemplo de una mala descripción:

description: 帮助处理 PDF 文件。  # 太笼统，代理无法判断何时使用

Consejo: el campo description se carga al inicio de la conversación. Asegúrate de que contenga suficientes palabras clave para que el agente pueda identificar correctamente cuándo necesita activar esta skill.

Explicación detallada del campo license

El campo license se utiliza para especificar la licencia de la skill. Este es un campo opcional.

license: Apache-2.0
# 或者引用 bundled 的许可证文件
license: Proprietary. LICENSE.txt has complete terms

Explicación detallada del campo compatibility

El campo compatibility se utiliza para indicar los requisitos de entorno de la skill. Solo se debe añadir cuando la skill tiene requisitos de entorno especiales.

# 指定目标产品
compatibility: Designed for Claude Code

# 指定系统依赖
compatibility: Requires git, docker, jq, and access to the internet

# 指定编程语言版本
compatibility: Requires Python 3.14+ and uv

Nota: la mayoría de las skills no necesitan el campo compatibility. Añádelo solo cuando la skill realmente tenga requisitos de entorno específicos.

Explicación detallada del campo metadata

El campo metadata puede almacenar información arbitraria de pares clave-valor. El cliente puede usarlo para almacenar atributos adicionales no definidos en la especificación.

metadata:
  author: example-org
  version: "1.0"
  tags:
    - pdf
    - document
    - extraction

Consejo: se recomienda utilizar nombres de clave relativamente únicos para evitar conflictos con otras skills.

Explicación detallada del campo allowed-tools

allowed-tools es un campo experimental que se utiliza para especificar las herramientas preaprobadas que la skill puede usar.

allowed-tools: Bash(git:*) Bash(jq:*) Read

Nota: esta es una función experimental; diferentes implementaciones de agentes pueden tener distintos niveles de soporte.

Explicación detallada de la sección de instrucciones

El contenido Markdown después de la sección de metadatos es la parte de instrucciones de la skill. No hay restricciones de formato aquí; puedes escribir cualquier contenido según sea necesario.

Se recomienda incluir lo siguiente:

  • Instrucciones de operación paso a paso
  • Ejemplos de entrada y salida
  • Manejo de casos límite comunes
# 技能名称

## 功能说明

简要描述这个技能做什么。

## 操作步骤

1. 第一步：执行某个操作
2. 第二步：执行另一个操作
3. 第三步：完成最终操作

## 示例

### 输入示例
描述输入是什么...

### 输出示例
描述输出是什么...

## 注意事项

- 注意点 1
- 注意点 2

Nota: una vez que la skill se activa, todo el archivo SKILL.md se carga en el contexto. Se recomienda mantener las instrucciones principales dentro de 500 líneas y por debajo de 5000 tokens. Mueve los materiales de referencia detallados a un archivo separado.

Otras extensiones