Extensión de scripts de Skills

Además de escribir instrucciones en SKILL.md, también puedes añadir código ejecutable a la Skill mediante el directorio scripts.

Esta sección te enseñará a usar scripts para ampliar las funciones de la Skill.

Por qué usar scripts

Usar scripts permite:

  • Encapsular lógica compleja, evitando escribir mucho código en SKILL.md
  • Proporcionar implementaciones fiables y probadas
  • Permitir que el agente reutilice las mismas herramientas y funciones
  • Manejar operaciones de entrada/salida más complejas

Consejo: cuando notes que el agente implementa repetidamente la misma lógica en múltiples ejecuciones, suele ser un buen momento para crear un script.

Estructura del directorio de scripts

Los scripts deben colocarse en el subdirectorio scripts/ del directorio de la Skill:

Estructura de directorios

my-skill/
├── SKILL.md
└── scripts/
    ├── script1.py
    ├── script2.sh
    └── helper.js

Normas de escritura de scripts

1. Autocontenido

El script debe ser lo más autocontenido posible, o documentar claramente sus dependencias.

Ejemplo de script autocontenido

#!/usr/bin/env python3
"""
Script de extracción de texto PDF

Dependencia: pip install pdfplumber
Ejecutar: python scripts/extract_pdf.py input.pdf
"""

import sys
import pdfplumber

def extract_text_from_pdf(pdf_path):
    """Extrae texto de archivos PDF"""
    with pdfplumber.open(pdf_path) as pdf:
        text = ""
        for page in pdf.pages:
            text += page.extract_text() or ""
    return text

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Uso: python extract_pdf.py <archivo pdf>")
        sys.exit(1)

    pdf_path = sys.argv[1]
    text = extract_text_from_pdf(pdf_path)
    print(text)

2. Manejo claro de errores

El script debe proporcionar mensajes de error útiles que ayuden al agente a entender qué salió mal.

Ejemplo de manejo de errores

import sys

def main():
    if len(sys.argv) < 2:
        print("Error: falta un parámetro requerido", file=sys.stderr)
        print("Uso: python script.py <archivo de entrada> [archivo de salida]", file=sys.stderr)
        sys.exit(1)

    input_file = sys.argv[1]

    try:
        # Ejecuta la lógica principal
        process_file(input_file)
    except FileNotFoundError:
        print(f"Error: no se encuentra el archivo {input_file}", file=sys.stderr)
        sys.exit(1)
    except PermissionError:
        print(f"Error: sin permiso para leer el archivo {input_file}", file=sys.stderr)
        sys.exit(1)
    except Exception as e:
        print(f"Error: error desconocido al procesar el archivo: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

3. Manejo de casos límite

El script debe manejar con elegancia diversos casos límite en lugar de fallar.

Ejemplo de manejo de casos límite

def validate_input(text):
    """Verifica si la entrada es válida"""
    if not text:
        return False, "La entrada no puede estar vacía"

    if len(text) > 10000:
        return False, "La entrada supera el límite de longitud (máximo 10000 caracteres)"

    return True, ""

# Usa la verificación
is_valid, error_msg = validate_input(user_input)
if not is_valid:
    print(f"Error de verificación: {error_msg}")
    sys.exit(1)

Referenciar scripts en SKILL.md

Cuando la Skill necesite ejecutar un script, explica en SKILL.md cómo invocarlo.

Referenciar scripts:

## PDF 文本提取

使用脚本提取 PDF 中的文本：

```bash
python scripts/extract_pdf.py input.pdf
```

脚本会从 input.pdf 提取所有文本并输出到标准输出。

如果需要将结果保存到文件：

```bash
python scripts/extract_pdf.py input.pdf > output.txt
```

Nota: al referenciar scripts, usa rutas relativas al directorio raíz de la Skill.

Lenguajes de script compatibles

Los lenguajes de script compatibles dependen de la implementación del agente que utilices. Las opciones comunes incluyen:

Lenguaje Descripción
Python La opción más común, potente y fácil de escribir
Bash Adecuado para operaciones de sistema y herramientas de línea de comandos
JavaScript Adecuado para tareas relacionadas con la Web

Consejo: al elegir el lenguaje de script, considera el entorno de ejecución de los usuarios objetivo. Si no estás seguro, Python es la opción más segura.

Ejemplo completo: Skill de procesamiento de PDF

Veamos un ejemplo completo que muestra cómo combinar SKILL.md y scripts:

Estructura de la Skill

pdf-tool/
├── SKILL.md
└── scripts/
    ├── extract.py
    ├── fill_form.py
    └── merge.py

Contenido de SKILL.md:

---
name: pdf-tool
description: 处理 PDF 文件，包括提取文本、填写表单、合并文件。使用场景：处理 PDF、提取文本、填写表单、合并 PDF.
---

## 提取 PDF 文本

从 PDF 文件中提取文本内容：

```bash
python scripts/extract.py input.pdf
```

输出是提取的纯文本内容。

## 填写 PDF 表单

使用 JSON 数据填写 PDF 表单：

```bash
python scripts/fill_form.py input.pdf data.json output.pdf
```

data.json 格式：
```json
{
  "field_name": "字段值",
  "another_field": "另一个值"
}
```

## 合并 PDF

将多个 PDF 文件合并为一个：

```bash
python scripts/merge.py output.pdf input1.pdf input2.pdf input3.pdf
```

## 依赖安装

需要安装 pdfplumber 和 PyPDF2：

```bash
pip install pdfplumber PyPDF2
```

Dos formas de uso

Hay dos formas de usar código en una Skill:

Forma Escenario de aplicación ¿Requiere el directorio scripts/?
Comandos de un solo uso Solo se necesitan llamar a herramientas existentes, sin lógica personalizada No
Script autocontenido Lógica compleja que necesita reutilizarse Sí

Comandos de un solo uso

Cuando las herramientas existentes del gestor de paquetes ya satisfacen la necesidad, simplemente refiérelas en las instrucciones de SKILL.md, sin necesidad de crear el directorio scripts/.

A continuación se presentan las formas habituales de ejecución en cada ecosistema de lenguaje:

uvx（Python）

uvx es el comando de ejecución de herramientas incluido con uv; ejecuta paquetes de Python en un entorno aislado y, gracias a su caché agresiva, las repeticiones son casi instantáneas.

Ejemplo

# Ejecuta ruff de una versión específica para revisar el código
uvx ruff@0.8.0 check .

# Ejecuta black de una versión específica para formatear el código
uvx black@24.10.0 .

pipx（Python）

pipx es una alternativa madura a uvx; se puede instalar mediante el gestor de paquetes del sistema (por ejemplo,brew install pipx）。

Ejemplo

# Ejecuta black de una versión específica
pipx run 'black==24.10.0' .

# Ejecuta ruff de una versión específica
pipx run '[email protected]' check .

npx（Node.js）

npx viene con npm, descarga y ejecuta paquetes de npm según sea necesario.

Ejemplo

# Ejecuta ESLint para revisar
npx eslint@9 --fix .

# Usa Vite para crear un proyecto
npx create-vite@6 my-app

go run（Go）

El comando de ejecución de herramientas incluido con Go, compila y ejecuta paquetes remotos directamente.

Ejemplo

# Ejecuta goimports para formatear importaciones
go run golang.org/x/tools/cmd/goimports@v0.28.0 .

# Ejecuta golangci-lint para revisar
go run github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.0 run

Consejos para escribir comandos de un solo uso: fija el número de versión (por ejemplo,npx [email protected]) para garantizar un comportamiento consistente; declara los requisitos previos en SKILL.md (por ejemplo, "se requiere Node.js 18+"); cuando el comando se vuelva complejo, extráelo al directorio scripts/.

Referenciar scripts en SKILL.md

Usa rutas relativas que comiencen desde la raíz del directorio de la SkillRutas relativaspara referenciar los archivos empaquetados.

El agente resolverá estas rutas automáticamente, sin necesidad de usar rutas absolutas.

Primero, enumera los scripts disponibles en SKILL.md:

Ejemplo

## Scripts disponibles

- **`scripts/validate.sh`** — Valida el archivo de configuración
- **`scripts/process.py`** — Procesa los datos de entrada
- **`scripts/report.py`** — Genera el informe de análisis

Luego, refiérelos en los pasos de operación:

Ejemplo

## Flujo de trabajo

1. Ejecuta el script de validación:
   ```bash
   bash scripts/validate.sh "$INPUT_FILE"
   ```

2. Procesa los datos:
   ```bash
   python3 scripts/process.py --input results.json
   ```

La ruta de ejecución de los scripts es relativa a la raíz del directorio de Skill, porque el Agent ejecuta comandos desde el directorio de Skill. Esto también aplica a archivos auxiliares como references/*.md.

Script autocontenido

Cuando necesites lógica reutilizable, puedes empaquetar scripts en elscripts/directorio y declarar las dependencias dentro del script.

El Agent solo necesita un comando para ejecutarlo, sin pasos de instalación adicionales.

Script autocontenido de Python (PEP 723)

PEP 723 define un formato estándar para declarar dependencias dentro de scripts de Python.

Usa# ///marcadores para envolver la declaración de dependencias en formato TOML:

Ejemplo: Script autocontenido de Python

# /// script
# dependencies = [
#   "beautifulsoup4",
# ]
# ///

from bs4 import BeautifulSoup

# Contenido HTML de ejemplo
html = '<html><body><h1>Bienvenido</h1><p class="info">EJEMPLO prueba</p></body></html>'

# Parsear HTML con BeautifulSoup
soup = BeautifulSoup(html, "html.parser")

# Extraer el texto del párrafo con class="info"
info_text = soup.select_one("p.info").get_text()
print(info_text)

Cómo ejecutar:

Ejemplo

# Ejecutar con uv (recomendado)
uv run scripts/extract.py

# Ejecutar con pipx
pipx run scripts/extract.py
EJEMPLO 测试

Script autocontenido de Deno

Deno usanpm:yjsr:especificadores de importación para lograr la autocontención:

Ejemplo: Script autocontenido de Deno

#!/usr/bin/env -S deno run

import * as cheerio from "npm:[email protected]";

const html = `<html><body><h1>Welcome</h1><p class="info">Test de EJEMPLO</p></body></html>`;
const $ = cheerio.load(html);
console.log($("p.info").text());

Ejemplo

deno run scripts/extract.ts

Script autocontenido de Bun

Bun, cuando no hay unnode_modulesdirectorio, instala automáticamente los paquetes faltantes:

Ejemplo: Script autocontenido de Bun

#!/usr/bin/env bun

import * as cheerio from "[email protected]";

const html = `<html><body><h1>Welcome</h1><p class="info">Test de EJEMPLO</p></body></html>`;
const $ = cheerio.load(html);
console.log($("p.info").text());

Ejemplo

bun run scripts/extract.ts

Script autocontenido de Ruby

Ruby usabundler/inlinepara declarar dependencias de gemas en el script:

Ejemplo: Script autocontenido de Ruby

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'nokogiri'
end

html = '<html><body><h1>Bienvenido</h1><p class="info">EJEMPLO prueba</p></body></html>'
doc = Nokogiri::HTML(html)
puts doc.at_css('p.info').text

Ejemplo

ruby scripts/extract.rb

Puntos clave para diseñar scripts para el agente

El Agent decide el siguiente paso leyendo stdout y stderr; por lo tanto, el diseño de los scripts debe tener en cuenta las características de uso del Agent.

Evita las indicaciones interactivas

Es un requisito estricto. El Agent se ejecuta en un shell no interactivo y no puede responder a solicitudes TTY, diálogos de contraseña ni menús de confirmación.

Toda la entrada debe pasarse mediante argumentos de línea de comandos, variables de entorno o stdin.

Ejemplo: Práctica incorrecta vs. práctica correcta

# Incorrecto: se quedará bloqueado esperando entrada
$ python scripts/deploy.py
Target environment: _

# Correcto: mensaje de error claro y orientación
$ python scripts/deploy.py
Error: --env is required. Options: development, staging, production.
Usage: python scripts/deploy.py --env staging --tag v1.2.3

Proporciona documentación --help

--helpLa salida es la principal forma en que el Agent conoce la interfaz del script.

Incluye una breve descripción, los parámetros disponibles y ejemplos de uso:

Ejemplo: Buena salida de --help

Usage: scripts/process.py [OPTIONS] INPUT_FILE

Procesa los datos de entrada y genera un informe resumido.

Options:
  --formatFORMAT Formato de salida: json, csv, table(Predeterminado: json)
  --outputFILE Escribe la salida a un archivo en lugar de stdout
  --verboseImprime información de progreso en stderr

Examples:
  scripts/process.py data.csv
  scripts/process.py --format csv --output report.csv data.csv

Escribe mensajes de error útiles

Cuando el Agent ve un mensaje de error, ajusta su estrategia en consecuencia; cuanto más específico sea el mensaje, más fácil le resultará al Agent corregirse.

Ejemplo

# Mal mensaje de error
Error: invalid input

# Buen mensaje de error
Error: --format must be one of: json, csv, table.
       Received: "xml"

Usa salida estructurada

Prioriza el uso de formatos estructurados como JSON, CSV, TSV, en lugar de texto libre.

Los formatos estructurados pueden ser consumidos tanto por el Agent como por herramientas estándar (jq, cut, awk), lo que facilita su combinación.

Ejemplo

# No recomendado: texto alineado, difícil de analizar programáticamente
NAME          STATUS    CREATED
my-service    running   2025-01-15

# Recomendado: formato JSON, con límites de campos claros
{"name": "my-service", "status": "running", "created": "2025-01-15"}

Envía los datos estructurados a stdout y los mensajes de progreso y la información de diagnóstico a stderr. De este modo, el Agent obtiene una salida limpia y analizable y, al mismo tiempo, puede consultar los diagnósticos cuando lo necesite.

Más consejos de diseño de scripts

Sugerencia Descripción
Idempotencia El Agent puede reintentar comandos. "Crear si no existe" es más seguro que "crear y mostrar un error al repetir".
Restricciones de entrada Rechaza entradas ambiguas con errores claros, en lugar de adivinar la intención del usuario
Soporte de dry-run Para operaciones destructivas o con estado, proporciona--dry-runun flag para que el Agent previsualice la operación
Códigos de salida significativos Usa códigos de salida diferentes para distintos tipos de error (no encontrado, argumentos no válidos, fallo de autenticación, etc.)
Tamaño de salida predecible Genera un resumen por defecto y ofrece--offsetparámetros como --verbose para que el Agent obtenga más información cuando lo necesite.
Valores predeterminados seguros Las operaciones destructivas deben requerir un flag de confirmación explícito (--confirm、--force）

Ejemplo completo de script de Skill

A continuación se muestra una estructura de directorio de Skill completa con scripts:

Ejemplo

csv-analyzer/
├── SKILL.md              # Archivo de instrucciones principal
├── scripts/
│   ├── overview.py       # Script de descripción general de datos
│   ├── summary.py        # Script de resumen estadístico
│   └── validate.py       # Script de validación de datos
├── references/
│   └── api-errors.md     # Referencia de errores de API
└── assets/
    └── report-template.md  # Plantilla de informe

Contenido correspondiente de SKILL.md:

Ejemplo

---
name: csv-analyzer
description: >
Analiza archivos CSV y de datos tabulares. Úsalo cuando el usuario tenga archivos CSV, TSV o Excel
y quiera explorar, transformar o visualizar los datos.
---

# Análisis de datos CSV

## Scripts disponibles

- **`scripts/overview.py`** — Muestra la descripción general de los datos (número de filas, nombres de columnas, tipos)
- **`scripts/summary.py`** — Genera un resumen estadístico
- **`scripts/validate.py`** — Valida la calidad de los datos

## Flujo de trabajo

1. Primero ejecuta el script de descripción general para entender la estructura de los datos:
   ```bash
   uv run scripts/overview.py input.csv
   ```

2. Genera el resumen estadístico:
   ```bash
   uv run scripts/summary.py input.csv --output summary.json
   ```

3. Valida la calidad de los datos:
   ```bash
   uv run scripts/validate.py input.csv
   ```

## Notas

- Para archivos grandes, usa el parámetro `--chunk-size` para procesarlos por bloques
- Para CSV con caracteres chinos, prueba el parámetro `--encoding gbk`

Distribución de scripts y dependencias

Si los scripts necesitan dependencias externas, tienes varias opciones:

1. Declara las dependencias en SKILL.md

La forma más sencilla es registrar las dependencias necesarias en SKILL.md.

2. Usa entornos virtuales

Para proyectos complejos, puedes crear un entorno virtual.

3. Usa Docker

Si se necesita un entorno de ejecución completo, puedes usar un contenedor Docker.

Nota: asegúrate de que los scripts puedan ejecutarse en el entorno de destino. Antes de escribir scripts, conoce el entorno de ejecución del usuario objetivo.

Resumen

En esta sección hemos aprendido a usar scripts para ampliar las funciones de las Skills:

  • Coloca los scripts en el directorio scripts/
  • Los scripts deben ser autocontenidos y tener un manejo de errores claro
  • Usa rutas relativas al hacer referencia a scripts en SKILL.md
  • Asegúrate de que los scripts puedan ejecutarse en el entorno de destino
Otras extensiones