Estructura de directorios de Skills
Comprender la estructura de directorios y el mecanismo de ejecución de Skill es la base para construir capacidades de AI Agent mantenibles y reutilizables.
Este artículo desglosa desde cero la estructura de directorios de un Skill estándar, la función de cada archivo y el flujo de trabajo completo.
¿Qué es Skill?
Skill es una unidad de capacidad independiente que se utiliza para completar un tipo específico de tarea.
Si comparamos a Agent con un sistema operativo, Skill es como una aplicación; si comparamos a Agent con un gerente de proyectos, Skill es una capacidad profesional que puede ser invocada.
Tipos comunes de Skill
A continuación se presentan algunos escenarios de aplicación típicos de Skill:
| Tipo | Descripción | Escenario aplicable |
|---|---|---|
| Análisis de documentos PDF | Extraer contenido de PDF y generar resúmenes | Procesamiento de documentos, extracción de información |
| Rastreo web | Obtención automática de datos web | Recopilación de datos, monitoreo de información |
| Optimización de SQL | Analizar y optimizar consultas SQL | Ajuste de rendimiento de bases de datos |
| Estadísticas de datos | Cálculo de datos y procesamiento estadístico | Análisis de datos, generación de informes |
| Reconocimiento de imágenes | Reconocer el contenido de las imágenes | OCR, clasificación de imágenes |
Relación entre Skill y Agent
Skill en sí no decide cuándo usarse; quien realmente toma la decisión es Agent.
El flujo de trabajo completo es el siguiente:
Punto clave: Agent no carga el contenido completo de todos los Skills a la vez. Primero lee la información de descripción de cada Skill y, una vez que encuentra el Skill objetivo, carga el contenido completo. La razón es: si hay cientos de Skills, cargar todo cada vez desperdiciaría enormemente tokens.
Estructura de directorios estándar de Skill
Un Skill completo no es un solo archivo, sino un directorio que contiene múltiples archivos.
A continuación se muestra la estructura de directorios completa de un Skill estándar:
my-skill/ │ ├── SKILL.md ← 核心执行文件 ├── metadata.json ← 元信息 ├── examples/ ← 示例目录 │ ├── example1.md │ └── example2.md │ ├── scripts/ ← 可执行脚本 │ ├── main.py │ └── utils.py │ ├── resources/ ← 资源目录 │ ├── prompt.md │ └── config.yaml │ ├── tests/ ← 测试目录 │ ├── test_cases.md │ └── eval.yaml │ ├── README.md ← 使用说明 │ └── CHANGELOG.md ← 变更日志
A continuación, desglosaremos uno por uno la función de cada archivo y directorio.
SKILL.md: archivo de ejecución central
Este es el archivo más importante de Skill, define toda la lógica de ejecución del Skill.
Contiene la siguiente información clave:
| Sección | Descripción | Función |
|---|---|---|
| Description | Descripción funcional de Skill | Para que Agent lo use en la coincidencia |
| When to use | Definir escenarios aplicables | Evitar activación accidental |
| When NOT to use | Definir escenarios no aplicables | Evitar conflictos con otros Skills |
| Input | Definir formato de entrada | Estandarizar el método de invocación |
| Instructions | Pasos de ejecución | Guiar la ejecución de tareas |
| Output | Descripción del formato de salida | Garantizar consistencia de resultados |
A continuación se muestra un ejemplo estándar de SKILL.md:
Ejemplo
## Description
Se utiliza para analizar contenido de PDF y generar resúmenes.
## When to use
Apto para:
- Lectura de PDF
- Extracción de resúmenes
- Análisis de contenido
## When NOT to use
No apto para:
- Edición de imágenes
- Procesamiento de video
## Input
Archivo PDF
## Instructions
1. Extraer texto
2. Identificar estructura de capítulos
3. Resumir contenido principal
4. Producir puntos clave
## Output
Resumen en formato Markdown
Errores comunes de escritura
Muchos principiantes escriben un SKILL.md demasiado simplificado, por ejemplo:
Escritura no recomendada
Leer PDF
Resumir contenido
Devolver resultado
Los problemas de esta escritura son: no se sabe cuándo usarlo, no se sabe cuándo no usarlo, el formato de salida no es claro y es fácil que entre en conflicto con otros Skills.
Un SKILL.md calificado debe permitir que Agent juzgue de un vistazo: si este Skill es adecuado para la tarea actual.
metadata.json: metainformación de Skill
Este archivo proporciona datos estructurados legibles por máquina, ayudando a Agent a filtrar rápidamente Skills.
Ejemplo
"name": "pdf-analyzer",
"version": "1.0.0",
"description": "Analizar PDF y generar resumen"
"tags": ["pdf", "summary"],
"category": "document"
}
Descripción de campos comunes
| Campo | Función | Importancia |
|---|---|---|
| name | Nombre de Skill | Obligatorio |
| description | Descripción funcional; Agent depende de ella para hacer coincidencias | Más importante |
| version | Número de versión | Recomendado |
| tags | Etiquetas, para facilitar la búsqueda | Recomendado |
| category | Categoría | Opcional |
| author | Autor | Opcional |
| permissions | Permisos requeridos | Opcional |
Entre ellosdescriptionel campo es el más importante, porque Agent normalmente depende de él para hacer coincidencias.
El proceso de coincidencia es aproximadamente el siguiente: después de que el usuario hace una solicitud, Agent escanea la description de todos los Skills, encuentra la descripción coincidente y luego carga el contenido completo del Skill y lo ejecuta.
examples: directorio de ejemplos
Muchos desarrolladores ignoran esta parte, pero en realidad es muy importante.
Estructura de directorios
examples/ ├── example1.md ├── example2.md
Contenido del archivo de ejemplo
Ejemplo
Ayúdame a analizar este PDF
Salida:
# Resumen del documento
## Contenido principal
1. ...
2. ...
3. ...
Función de examples
| Función | Descripción |
|---|---|
| Proporcionar ejemplos few-shot | Ayuda al modelo a comprender el comportamiento esperado mediante ejemplos |
| Estandarizar el formato de salida | Aclarar la estructura y el estilo de salida mediante ejemplos |
| Mejorar la estabilidad de salida | Reducir el comportamiento aleatorio y hacer los resultados más predecibles |
Experiencialmente, buenos examples suelen ser más efectivos que aumentar el prompt.
scripts: scripts ejecutables
Skill no es solo un prompt; a veces es necesario ejecutar código real para completar el trabajo real.
Los escenarios comunes que requieren scripts incluyen: leer PDF, ejecutar OCR, llamar a bases de datos, procesamiento de datos, generar gráficos, etc.
Estructura de directorios
scripts/ ├── main.py └── utils.py
Ejemplo de script Python
Ejemplo
# Función: extraer contenido de texto de un archivo PDF
from pypdf import PdfReader
# Abrir archivo PDF
reader = PdfReader("demo.pdf")
# Almacenar el texto extraído
text = ""
# Recorrer cada página y extraer texto
for page in reader.pages:
text += page.extract_text()
# Mostrar todo el contenido de texto
print(text)
El flujo de trabajo de Skill es: leer el archivo → ejecutar el script → obtener el resultado, y luego entregar el resultado al modelo grande para su procesamiento.
resources: directorio de recursos
Se utiliza para guardar contenido auxiliar, separando la configuración del código.
Estructura de directorios
resources/ ├── prompt.md ├── config.yaml
Tipos de recursos que puede incluir
| Tipo de recurso | Descripción | Ejemplo |
|---|---|---|
| Plantilla de Prompt | Plantillas de prompts reutilizables | prompt.md |
| Archivo de configuración | Parámetros y ajustes | config.yaml |
| Plantilla de texto | Plantillas de correo e informes | template.txt |
| Recursos de imagen | Iconos, diagramas | logo.png |
| Plantilla SQL | Plantillas de consulta predefinidas | query.sql |
Ejemplo de archivo de configuración
Ejemplo
# Configuración relacionada con el resumen
max_length: 1000 # Longitud máxima del resumen (número de caracteres)
language: zh # Idioma de salida: zh=chino, en=inglés
Al colocar la configuración en un archivo independiente, en el futuro no será necesario modificar el código para cambiar los parámetros.
tests: directorio de pruebas
Los proyectos maduros suelen incluir pruebas para verificar la efectividad y estabilidad de Skill.
Estructura de directorios
tests/ ├── test_cases.md └── eval.yaml
Ejemplo de caso de prueba
Ejemplo
Entrada:
Ayúdame a analizar el PDF
Esperado:
Resumen de salida
Incluir puntos clave
Función de las pruebas
| Función | Descripción |
|---|---|
| Verificar la efectividad | Asegurar que la salida de Skill cumpla con lo esperado |
| Pruebas de regresión | Verificar después de cambios que las funciones antiguas no se vean afectadas |
| Evaluación automática | Pruebas por lotes junto con flujos automatizados |
| Pruebas A/B | Comparar la calidad de salida de diferentes versiones |
Un Skill sin pruebas es propenso al problema de "cambié una frase y las funciones antiguas dejaron de funcionar de repente".
README: instrucciones de uso
README está dirigido a desarrolladores, explica cómo instalar y usar este Skill.
Ejemplo
Copiar al directorio skills
# Cómo usar
Subir PDF
# Formato de salida
Markdown
El problema central que resuelve es: en el futuro ni siquiera uno mismo sabrá cómo usar el Skill que escribió.
Caso completo: Skill de análisis de PDF
A continuación, se conectan todos los conceptos anteriores con un ejemplo completo.
Vista general de la estructura de directorios
pdf-analyzer/ ├── SKILL.md ├── metadata.json ├── examples/ │ └── summary.md ├── scripts/ │ └── extract.py ├── tests/ │ └── eval.md └── README.md
Flujo de invocación completo
用户：
上传 PDF 并总结
↓
Agent：
扫描所有 Skills
↓
发现：
description: 分析 PDF 并生成摘要
↓
命中 pdf-analyzer
↓
读取 SKILL.md
↓
调用 extract.py
↓
提取 PDF 内容
↓
生成摘要
↓
返回结果
¿Por qué Skill se diseña como estructura de directorios?
Mucha gente preguntará: ¿por qué no usar un solo prompt.txt para resolver todo?
La razón es que cuando la escala crece, se sale de control.
Problemas del enfoque de un solo archivo
| Problema | Manifestación específica |
|---|---|
| Imposible de mantener | Todo el contenido amontonado en un solo archivo, difícil de modificar |
| Imposible de probar | Sin casos de prueba, no se sabe si funciona correctamente después de los cambios |
| Imposible de reutilizar | Cada Skill tiene que escribirse desde cero |
| Imposible gestionar versiones | Difícil rastrear el historial de cambios |
| Imposible colaborar en equipo | Un archivo modificado por varias personas fácilmente genera conflictos |
Ventajas del enfoque basado en directorios
| Ventaja | Forma de implementación |
|---|---|
| Mantenible | Responsabilidades claras por archivo, localización rápida de cambios |
| Reutilizable | Los scripts y configuraciones se pueden compartir entre Skills |
| Testeable | Directorio de pruebas independiente, soporta verificación automatizada |
| Extensible | Para agregar nuevas funciones solo hay que añadir archivos |
| Publicable | Empaquetar el directorio y listo para distribuir |
Resumen
Skill no es esencialmente un prompt, sino un paquete completo de capacidades de software.
Relación entre archivos centrales
SKILL.md
↓
定义行为
metadata.json
↓
定义信息
examples/
↓
定义示例
scripts/
↓
定义能力
tests/
↓
定义质量
README
↓
定义使用方式
Otras extensionesEl Prompt solo puede resolver un problema puntual, mientras que Skill convierte las capacidades en activos.