← Volver al listado de tecnologías ← Índice de OpenCode

Capitulo 13: Agent Skills

2 de marzo de 2026 Por: Artiko

opencodeaiskillsautomatizacionreutilizacion

Capitulo 13: Agent Skills

Que son Agent Skills

Los Agent Skills son instrucciones reutilizables escritas en Markdown que OpenCode descubre y carga automaticamente cuando el agente las necesita. A diferencia de los agentes o comandos, los skills son pasivos: el agente los busca y los lee on-demand a traves de la herramienta nativa skill.

Piensa en los skills como documentacion ejecutable. En lugar de repetir las mismas instrucciones en cada conversacion, defines un skill una vez y el agente lo consulta cuando enfrenta una tarea relacionada.

Como Funcionan

El flujo es simple:

Defines un archivo SKILL.md en una ubicacion reconocida
OpenCode detecta los skills disponibles al iniciar
Cuando el agente necesita instrucciones especificas, usa la herramienta skill para cargar el contenido
El skill se inyecta en el contexto del agente como instrucciones adicionales

Los skills se cargan on-demand, lo que significa que no consumen tokens hasta que el agente decide que los necesita.

Ubicaciones de Skills

OpenCode busca skills en dos ubicaciones:

Skills del Repositorio

tu-proyecto/
  .opencode/
    skills/
      mi-skill/
        SKILL.md
      otro-skill/
        SKILL.md

Estos skills son especificos del proyecto. Se comparten con el equipo a traves del repositorio y contienen instrucciones relevantes para ese proyecto en particular.

Skills Globales

~/.config/opencode/
  skills/
    mi-skill-global/
      SKILL.md
    review/
      SKILL.md

Estos skills estan disponibles en todos tus proyectos. Son utiles para convenciones personales o estandares que aplicas en cualquier codebase.

Formato del Archivo SKILL.md

Un skill es simplemente un archivo Markdown con instrucciones claras para el agente:

# Generar Tests

Cuando generes tests para este proyecto, sigue estas reglas:

## Convenciones
- Usa vitest como framework de testing
- Los archivos de test van en `__tests__/` junto al archivo original
- Nombra los archivos como `nombre.test.ts`
- Usa `describe` para agrupar por funcionalidad
- Usa `it` (no `test`) para cada caso

## Estructura
- Arrange: prepara datos y mocks
- Act: ejecuta la funcion
- Assert: verifica resultados

## Mocks
- Usa vi.mock() para modulos externos
- Nunca mockees la funcion que estas testeando
- Prefiere inyeccion de dependencias sobre mocks globales

Las instrucciones deben ser:

Claras: el agente las interpreta literalmente
Especificas: incluye nombres de archivos, convenciones y patrones exactos
Acotadas: cada skill cubre una tarea o dominio especifico

Crear un Skill Propio

Paso 1: Crear la estructura

mkdir -p .opencode/skills/review-pr

Paso 2: Escribir el SKILL.md

Crea .opencode/skills/review-pr/SKILL.md:

# Review de Pull Requests

Al revisar un PR, sigue este checklist:

## Seguridad
- Verificar que no se expongan secretos o credenciales
- Validar inputs del usuario
- Revisar permisos y autorizacion

## Calidad
- Funciones de maximo 30 lineas
- Sin codigo duplicado
- Nombres descriptivos para variables y funciones
- Sin console.log o debuggers

## Tests
- Cobertura para los cambios nuevos
- Tests de edge cases
- No tests fragiles que dependan de implementacion

## Performance
- Sin queries N+1
- Uso apropiado de memoizacion
- Lazy loading donde aplique

Genera un reporte con:
1. Lista de problemas encontrados (critico/medio/bajo)
2. Sugerencias de mejora
3. Lo que esta bien hecho

Paso 3: Verificar

El skill estara disponible la proxima vez que inicies OpenCode. El agente podra cargarlo cuando se le pida hacer un review.

Ejemplo: Skill para Documentacion

.opencode/skills/docs/SKILL.md

# Generar Documentacion

Al documentar codigo en este proyecto:

## Formato
- Usa JSDoc para funciones publicas
- Documenta parametros con @param y tipos
- Documenta retorno con @returns
- Incluye @example con uso basico

## README de modulos
- Proposito del modulo en una linea
- Instalacion si aplica
- Ejemplo de uso minimo
- API publica con descripcion breve

## No documentar
- Funciones privadas obvias
- Getters/setters simples
- Re-exports

Skills vs Agents vs Commands

Estos tres conceptos se complementan pero tienen propositos distintos:

Skills (instrucciones pasivas)

Son documentos que el agente lee cuando necesita
Se cargan on-demand, no consumen tokens por defecto
Definen como hacer algo
No tienen configuracion de herramientas ni modelo

Agents (entidades activas)

Tienen su propio modelo, herramientas y system prompt
Se activan explicitamente con @agente
Definen quien hace algo
Pueden tener acceso restringido a herramientas

Commands (atajos a prompts)

Ejecutan un prompt predefinido con /comando
Son directos e inmediatos
Definen que hacer
No contienen instrucciones detalladas, solo el prompt inicial

Cuando usar cada uno

Necesidad	Usa
Estandarizar como se hacen los tests	Skill
Un agente especializado en seguridad	Agent
Ejecutar un review rapido con un comando	Command
Convenciones de codigo del proyecto	Skill
Agente que solo usa herramientas de DB	Agent
Generar changelog con un atajo	Command

En la practica, se combinan. Un command puede triggear un agente que internamente carga un skill para seguir las convenciones del proyecto.

Buenas Practicas

Un skill por dominio: no mezcles instrucciones de testing con instrucciones de deploy
Se especifico: “usa vitest” es mejor que “usa un framework de testing”
Incluye ejemplos: el agente entiende mejor con ejemplos concretos
Manten skills actualizados: si cambian las convenciones, actualiza el skill
Commitea los skills del proyecto: .opencode/skills/ debe estar en el repositorio
No abuses: demasiados skills pueden confundir al agente si carga multiples al mismo tiempo

Siguiente: Capitulo 14: Comandos Custom —>