Construyendo y Registrando Skills Personalizadas

Intermedio⏱45 min📖5 min de lecturaLección 3 de 5

Construyendo y Registrando Skills Personalizadas

Domina el sistema de skills: estructura, manifiestos, instrucciones, herramientas, recursos, parámetros, descubrimiento y registro.

Estructura de la Skill

Una skill es un directorio que contiene un archivo de manifiesto y recursos opcionales:

skills/
  mi-skill-personalizada/
    skill.yaml        # Manifiesto (obligatorio)
    instructions.md   # Instrucciones extendidas (opcional)
    templates/        # Archivos de recurso (opcional)
       scaffold.py
    references/       # Documentos de referencia (opcional)
       api-guide.md

ℹ️Nota

Aunque skill.yaml es el formato convencional, OpenCode también soporta manifiestos JSON (skill.json). YAML es recomendado para legibilidad, especialmente para bloques largos de instrucciones. JSON es preferible cuando necesitas generar manifiestos programáticamente o validarlos con JSON Schema.

Ciclo de Vida de Carga de Skill

Entender cómo se cargan las skills te ayuda a diseñar skills eficientes que no desperdicien la ventana de contexto.

💡 Tip: Use Ctrl + Mouse Wheel to zoom, or click the fullscreen icon

💡Consejo

Las skills con descripciones excesivamente amplias pueden cargarse no intencionalmente, consumiendo ventana de contexto y tokens. Mantén las descripciones específicas y enfocadas. Usa matchPattern para control preciso sobre cuándo se activa una skill.

Manifiesto de la Skill

El manifiesto define la identidad, propósito y componentes de la skill.

yaml

# skill.yaml
name: mi-skill-personalizada
description: Guía al agente en la realización de generación personalizada de scaffolds
author: Nuniversity
version: 1.0.0
instructions: |
  Cuando el usuario pida generar scaffold de un nuevo proyecto Python:
  1. Usa los archivos de plantilla en el directorio `templates/`
  2. Pregunta al usuario el nombre del proyecto y nombre del paquete
  3. Genera la estructura de directorios con pyproject.toml, src/, tests/
  4. Inicializa un repositorio git
tools:
  - bash
  - write
  - read
  - glob
resources:
  - templates/scaffold.py
  - references/api-guide.md

📌Importante

El campo instructions es la parte más crítica de una skill. Se inyecta directamente en el contexto del agente. Mantén las instrucciones concisas y accionables: cada token consumido por la skill es un token no disponible para la conversación. Apunta a no más de 500-1000 palabras por skill.

Comparación: Formatos de Manifiesto YAML vs JSON

Aspecto	YAML (`skill.yaml`)	JSON (`skill.json`)
Legibilidad	Excelente, natural para texto largo	Buena, familiar para devs JS/TS
Comentarios	Soportados (`# comment`)	No soportados
Multi-línea	Nativo (`	`y`>` block scalars)
Validación schema	Herramientas limitadas	JSON Schema, muchos validadores
Mejor para	Skills escritas manualmente	Skills generadas o validadas
Tamaño archivo	Generalmente menor	Ligeramente mayor (comillas, comas)
Herramientas	Linters YAML disponibles	JSON nativo en la mayoría de editores

Escribiendo Instrucciones de Skill

Las instrucciones son el núcleo de una skill. Guían al agente paso a paso.

markdown

# instructions.md

## Objetivo
Generar scaffold de un proyecto Python listo para producción.

## Pasos
1. Pregunta al usuario: nombre del proyecto, nombre del paquete, versión Python
2. Crea directorio: `{nombre_del_proyecto}/`
3. Genera `pyproject.toml` con:
   - Metadatos del proyecto
   - Dependencias (click, pytest, black)
   - Configuración del sistema de build
4. Crea `src/{nombre_del_paquete}/__init__.py` con string de versión
5. Crea `tests/test_{nombre_del_paquete}.py` con prueba placeholder
6. Ejecuta `git init` y `git add -A`

## Restricciones
- No sobrescribas archivos existentes sin preguntar
- Usa los estándares más recientes de empaquetado Python (PEP 621)

bash

# Las instrucciones pueden referenciar scripts empaquetados como recursos
# Ejemplo: ejecutando la plantilla de scaffold
python skills/mi-skill-personalizada/templates/scaffold.py \
  --project-name "$NOMBRE_DEL_PROYECTO" \
  --package-name "$NOMBRE_DEL_PAQUETE"

Herramientas y Recursos de Skill

Las skills pueden declarar herramientas necesarias y empaquetar archivos de recurso:

json

{
  "name": "db-migration-skill",
  "description": "Generación y gestión de migraciones de base de datos",
  "version": "2.1.0",
  "instructions": "Al gestionar migraciones de base de datos...",
  "tools": ["bash", "read", "write", "grep"],
  "resources": [
    "templates/migration_template.sql",
    "templates/rollback_template.sql",
    "config/migration.config.json"
  ],
  "parameters": {
    "db_type": {
      "type": "string",
      "description": "Tipo de base de datos (postgres, mysql, sqlite)",
      "required": true
    },
    "migration_name": {
      "type": "string",
      "description": "Nombre descriptivo para la migración",
      "required": true
    }
  }
}

⚠️Advertencia

Cada archivo de recurso cargado en el contexto consume tokens. Empaqueta solo archivos esenciales. Los documentos de referencia grandes deben ser vinculados en lugar de incrustados. Un archivo de referencia de 100KB consume aproximadamente 25.000 tokens de la ventana de contexto.

Parámetros de Skill

Los parámetros permiten que las skills sean configurables y reutilizables:

yaml

name: api-client-generator
description: Genera bibliotecas de cliente API a partir de especificaciones OpenAPI
version: 1.0.0
instructions: |
  Genera un cliente API basado en la especificación OpenAPI proporcionada.
  Usa el parámetro language para determinar el formato de salida.
parameters:
  language:
    type: string
    description: "Idioma destino (python, typescript, go)"
    required: true
    default: python
  spec_path:
    type: string
    description: "Ruta al archivo de especificación OpenAPI"
    required: true
  output_dir:
    type: string
    description: "Directorio de salida para el cliente generado"
    required: false
    default: "./generated"

💡Consejo

Usa required: false con un valor default sensato para parámetros que tienen valores predeterminados obvios. Esto reduce la fricción al usar la skill mientras aún permite personalización. Los parámetros se pasan cuando la skill se invoca a través de instrucciones del agente.

Flujo de Ejecución de la Skill

💡 Tip: Use Ctrl + Mouse Wheel to zoom, or click the fullscreen icon

Registrando Skills en Config

Las skills deben registrarse en opencode.json para ser descubiertas:

json

{
  "skills": {
    "scaffold-python": {
      "manifest": "skills/scaffold-python/skill.yaml"
    },
    "db-migration": {
      "manifest": "skills/db-migration/skill.json"
    },
    "api-client-gen": {
      "manifest": "skills/api-client-generator/skill.yaml"
    }
  }
}

typescript

// Las skills también pueden registrarse programáticamente
import { OpenCode } from "opencode";

const opencode = new OpenCode();

opencode.registerSkill({
  name: "react-component",
  manifest: "skills/react-component/skill.yaml",
  autoLoad: true,
  matchPattern: "react component|jsx|tsx"
});

await opencode.run();

Descubrimiento de Skills

OpenCode descubre skills a través de registro y coincidencia de patrones. Cuando una consulta del usuario coincide con la descripción de una skill, la skill se carga automáticamente.

⚠️Advertencia

Las skills con descripciones excesivamente amplias pueden cargarse no intencionalmente, consumiendo ventana de contexto y tokens. Mantén las descripciones específicas y enfocadas. Una skill descrita como "ayuda con desarrollo" coincidirá con casi todas las solicitudes.

json

{
  "skills": {
    "react-component": {
      "manifest": "skills/react-component/skill.yaml",
      "autoLoad": true,
      "matchPattern": "react component|jsx|tsx component|react hook"
    }
  }
}

💡Consejo

El campo autoLoad combinado con matchPattern te da control preciso. Sin autoLoad, la skill solo se carga cuando se solicita explícitamente. Esto es útil para skills de nicho que no deberían activarse en cada consulta vagamente relacionada. Usa autoLoad: false para skills usadas raramente para ahorrar contexto.

Comparación: Campos del Manifiesto de Skill

Campo	Tipo	Obligatorio	Descripción
`name`	string	Sí	Identificador único de la skill
`description`	string	Sí	Descripción corta para coincidencia
`version`	string	Sí	Versión semántica (ej.: `1.0.0`)
`instructions`	string	Sí	Guía paso a paso para el agente
`tools`	string[]	No	Lista de herramientas necesarias
`resources`	string[]	No	Rutas de archivos relativas al directorio
`parameters`	object	No	Parámetros configurables con valores pred.
`author`	string	No	Nombre del creador para atribución
`matchPattern`	string	No	Patrón regex para activación automática
`autoLoad`	boolean	No	Si la skill se activa en coincidencia

ℹ️Nota

Una skill puede tener tanto instructions en línea en el manifiesto como un archivo externo instructions.md. Si ambos existen, el archivo externo tiene prioridad. Usa instrucciones en línea para skills cortas y archivos externos para procedimientos complejos de múltiples pasos.