Descripción de Skills

La descripción de la habilidad (description) es la parte más importante de una habilidad; determina si el agente puede reconocer correctamente cuándo debe activar la habilidad. Esta sección te enseñará cómo escribir descripciones de habilidades efectivas.


Por qué la descripción es importante

La descripción de la habilidad desempeña un papel clave en el proceso de carga de habilidades por parte del agente:

  • En la fase de descubrimiento, el agente solo carga el nombre y la descripción de cada habilidad
  • La descripción es la base principal para que el agente decida si activar la habilidad
  • Una buena descripción puede mejorar la precisión de activación de la habilidad

Si la descripción está mal escrita, el agente puede:

  • Activar la habilidad cuando no es necesaria (falso positivo)
  • Olvidar activar la habilidad cuando es necesaria (falso negativo)
  • Activar la habilidad equivocada

Consejo: La calidad de la descripción de la habilidad afecta directamente su usabilidad. Vale la pena invertir tiempo en optimizar la descripción.


Estructura básica de la descripción

Una buena descripción de habilidad debe incluir dos partes:

  1. Descripción funcional: describe qué puede hacer la habilidad
  2. Condiciones de activación: explica en qué situaciones se usa
description: 从 PDF 文件中提取文本和表格,填写 PDF 表单,合并多个 PDF。处理 PDF 文档或用户提及 PDF、表单或文档提取时使用。
#                         ↑ 功能说明                                      ↑ 触发条件

Consejos para escribir descripciones efectivas

1. Incluye palabras clave de activación específicas

Incluye palabras y frases específicas que los usuarios puedan usar. Estas palabras clave ayudan al agente a identificar tareas relevantes.

Buena descripción:

description: 提取 PDF 文本和表格,填写表单,合并 PDF。使用场景:处理 PDF 文件、提取文档内容、填写 PDF 表单、合并多个 PDF、用户提及「PDF」「提取」「表单」「合并」等关键词。

2. La descripción debe ser específica, no general

Evita descripciones demasiado amplias, ya que esto impide que el agente juzgue con precisión.

# 不好的描述 - 太笼统
description: 帮助处理各种文件。

# 好的描述 - 具体明确
description: 处理图像文件,包括调整大小、转换格式、应用滤镜。使用场景:处理图片、调整图像尺寸、转换图片格式。

3. Explica múltiples escenarios de uso

Enumera los diferentes escenarios en los que la habilidad puede aplicarse para ayudar al agente a realizar coincidencias más precisas.

description: 执行代码审查,检查安全漏洞、代码质量和性能问题。使用场景:代码审查、PR 审查、代码检查、安全扫描、质量评估、用户要求「review」「检查代码」「安全性」等。

4. Distingue habilidades similares

Si tienes múltiples habilidades relacionadas, asegúrate de que sus descripciones tengan diferencias claras.

# 技能 1:PDF 文本提取
name: pdf-extract
description: 从 PDF 文件中提取文本内容和表格数据。使用场景:提取 PDF 文字、读取 PDF 内容、PDF 转文本、用户提及「PDF 提取」「读取 PDF」等。

# 技能 2:PDF 表单处理
name: pdf-form
description: 填写 PDF 表单字段,提取表单数据。使用场景:填写 PDF 表单、填充表单字段、PDF 表单数据处理、用户提及「PDF 表单」「填写表单」等。

Control de la longitud de la descripción

La longitud máxima del campo description es de 1024 caracteres. Pero ese no es el objetivo; la descripción debe ser concisa y precisa.

Situación Longitud recomendada
Habilidad simple 50-100 caracteres
Habilidad de complejidad media 100-200 caracteres
Habilidad compleja 200-400 caracteres

Nota: Una descripción no es mejor por ser más larga. Las descripciones demasiado largas pueden incluir demasiada información irrelevante y, por el contrario, interferir con el juicio del agente.


Prueba y optimización de la descripción

Después de crear una habilidad, debes probar si la descripción activa correctamente la habilidad. Estos son los pasos de prueba:

1. Prueba de funcionalidad básica

Prueba usando las palabras clave incluidas en la descripción para confirmar que la habilidad puede activarse.

2. Prueba de casos límite

Prueba algunos escenarios que podrían activarla pero no deberían activarla.

3. Optimización iterativa

Ajusta la descripción según los resultados de las pruebas:

  • Si aumentan los falsos positivos: agrega más condiciones restrictivas en la descripción
  • Si aumentan los falsos negativos: agrega más palabras de activación posibles en la descripción
  • Si la activación es incorrecta: asegúrate de que la descripción se distinga suficientemente de otras habilidades similares

Ejemplo de optimización:

# 初始版本 - 可能漏报
description: 提取 PDF 文本。

# 优化版本 - 减少漏报
description: 从 PDF 文件中提取文本内容和表格数据。使用场景:提取 PDF 文字、读取 PDF 内容、PDF 转文本。

# 最终版本 - 进一步优化
description: 从 PDF 文件中提取文本内容和表格数据。使用场景:提取 PDF 文字、读取 PDF 内容、PDF 转文本、用户提及「PDF 提取」「读取 PDF」「PDF 文字」「PDF 内容」等关键词时使用。

Problemas comunes y soluciones

Problema 1: La habilidad siempre se activa

Esto indica que la descripción es demasiado amplia. La solución es agregar más condiciones restrictivas y escenarios de uso.

Solución:

# 修改前 - 太宽泛
description: 处理文本。

# 修改后 - 更具体
description: 使用正则表达式处理和转换文本字符串。使用场景:文本匹配、字符串替换、模式提取、数据清洗。

Problema 2: La habilidad nunca se activa

Esto indica que la descripción carece de palabras clave que los usuarios puedan usar. La solución es agregar más palabras de activación.

Solución:

# 修改前 - 关键词太少
description: 优化数据库查询。

# 修改后 - 添加更多触发词
description: 优化 SQL 查询性能,分析执行计划,添加索引。使用场景:SQL 优化、查询慢、数据库性能、调优索引、执行计划分析。

Problema 3: Se activa la habilidad equivocada

Esto indica que las descripciones de varias habilidades son demasiado similares. La solución es hacer que las descripciones se distingan más.

Consejo: Probar y optimizar regularmente las descripciones de tus habilidades es un buen hábito. A medida que aumenten los escenarios de uso, es posible que descubras que las descripciones necesitan ajustes.

Otras extensiones