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

Capitulo 13: Agent Skills

Por: Artiko
opencodeaiskillsautomatizacionreutilizacion

Capitulo 13: Agent Skills

< Volver al Indice del Tutorial

Que son Agent Skills

Los Agent Skills son instrucciones reutilizables escritas en Markdown que OpenCode descubre y carga automáticamente 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 través de la herramienta nativa skill.

Piensa en los skills como documentación ejecutable. En lugar de repetir las mismas instrucciones en cada conversación, defines un skill una vez y el agente lo consulta cuando enfrenta una tarea relacionada. Es el equivalente a tener un manual de procedimientos que el asistente puede abrir y seguir paso a paso cada vez que necesita realizar una operación específica.

La diferencia clave respecto a otros mecanismos es que los skills se cargan on-demand. No consumen tokens hasta que el agente decide que los necesita. Esto es fundamental porque permite tener decenas de skills definidos sin afectar el rendimiento ni el costo de las sesiones donde no se usan.

Como Funcionan

El flujo completo de un skill es el siguiente:

  1. Defines un archivo SKILL.md en una ubicación reconocida por OpenCode
  2. OpenCode detecta los skills disponibles al iniciar la sesión
  3. Cuando el agente necesita instrucciones específicas, usa la herramienta skill para cargar el contenido del archivo
  4. El skill se inyecta en el contexto del agente como instrucciones adicionales
  5. El agente sigue las instrucciones del skill para completar la tarea
sequenceDiagram
    participant U as Usuario
    participant A as Agente
    participant S as Skill Tool
    participant F as SKILL.md

    U->>A: "Haz un review del PR"
    A->>S: skill("review-pr")
    S->>F: Lee .opencode/skills/review-pr/SKILL.md
    F-->>S: Contenido del skill
    S-->>A: Instrucciones inyectadas
    A->>U: Review siguiendo las instrucciones del skill

Este mecanismo lazy-loading es lo que hace a los skills tan eficientes. Un proyecto puede tener 20 skills definidos, pero si en una sesión particular el agente solo necesita 2, únicamente esos 2 consumirán tokens.

Ubicaciones de Skills

OpenCode busca archivos SKILL.md en múltiples ubicaciones, tanto a nivel de proyecto como a nivel global del usuario. Esto permite compartir skills con el equipo vía repositorio y tener skills personales que aplicas en todos tus proyectos.

Skills del Proyecto

Las ubicaciones reconocidas dentro de un repositorio son:

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

La ubicación principal es .opencode/skills/, pero OpenCode también reconoce .claude/skills/ para compatibilidad con proyectos que migraron desde Claude Code, y .agents/skills/ como convención alternativa. En la práctica, usa .opencode/skills/ para proyectos nuevos y las otras rutas solo si estás migrando desde otra herramienta.

Estos skills son específicos del proyecto. Se comparten con el equipo a través del repositorio y contienen instrucciones relevantes para ese proyecto en particular: convenciones de testing, estándares de documentación, patrones de arquitectura y cualquier otra regla que el equipo haya definido.

Skills Globales

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

Los skills globales están disponibles en todos tus proyectos. Son útiles para convenciones personales o estándares que aplicas en cualquier codebase, como tu estilo preferido de commits, tu checklist personal de code review o las reglas de documentación que siempre sigues.

Formato del Archivo SKILL.md

Cada skill consiste en un archivo SKILL.md que puede incluir un frontmatter YAML opcional seguido del contenido en Markdown. El frontmatter permite definir metadatos que OpenCode usa para gestionar el skill.

Frontmatter

---
name: generar-tests
description: "Convenciones para generacion de tests unitarios con vitest"
license: MIT
compatibility: opencode
metadata:
  version: "1.0"
---

Los campos del frontmatter son:

Si omites el frontmatter, OpenCode usa el nombre del directorio como identificador del skill y no tendrá descripción, lo que reduce la capacidad del agente para decidir cuándo cargarlo.

Cuerpo del Skill

Después del frontmatter, el resto del archivo contiene las instrucciones en Markdown:

---
name: generar-tests
description: "Convenciones para generacion de tests unitarios con vitest"
---

# 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 función
- Assert: verifica resultados

## Mocks
- Usa vi.mock() para módulos externos
- Nunca mockees la función que estás testeando
- Prefiere inyección de dependencias sobre mocks globales

Las instrucciones deben ser claras, específicas y acotadas. El agente las interpreta literalmente, así que incluye nombres de archivos, convenciones y patrones exactos. Evita instrucciones ambiguas como “usa buenas prácticas” y prefiere instrucciones concretas como “usa vitest con patrón AAA”.

Permisos de Skills

OpenCode permite controlar qué skills pueden cargarse y cuáles no a través del sistema de permisos en opencode.json. Esto es especialmente útil cuando trabajas con skills de terceros o cuando quieres restringir skills en ciertos agentes.

Configuración de Permisos

{
  "permission": {
    "skill": {
      "internal-*": "allow",
      "external-*": "ask",
      "blocked-skill": "deny"
    }
  }
}

Los tres niveles de permiso son:

Comodines

Los permisos soportan comodines con *. Por ejemplo, internal-* coincide con cualquier skill cuyo nombre empiece por internal-, como internal-docs, internal-review o internal-deploy. Esto permite gestionar grupos de skills sin listar cada uno individualmente.

Desactivar Skills Completamente

Si quieres que un agente específico no tenga acceso a ningún skill, puedes desactivar la funcionalidad completa en la configuración del agente:

{
  "agent": {
    "build": {
      "skill": false
    }
  }
}

Con "skill": false, el agente build no podrá descubrir ni cargar ningún skill, independientemente de los permisos globales.

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:

---
name: review-pr
description: "Checklist para revisión de Pull Requests"
metadata:
  version: "1.0"
---

# 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 autorización

## Calidad
- Funciones de máximo 30 líneas
- Sin código duplicado
- Nombres descriptivos para variables y funciones
- Sin console.log o debuggers

## Tests
- Cobertura para los cambios nuevos
- Tests de edge cases
- No tests frágiles que dependan de implementación

## Performance
- Sin queries N+1
- Uso apropiado de memoización
- Lazy loading donde aplique

Genera un reporte con:
1. Lista de problemas encontrados (crítico/medio/bajo)
2. Sugerencias de mejora
3. Lo que está bien hecho

Paso 3: Verificar

El skill estará disponible la próxima vez que inicies OpenCode. El agente podrá cargarlo cuando se le pida hacer un review. Puedes verificar que lo detecta pidiéndole al agente que liste los skills disponibles.

Ejemplo: Skill para Documentación

.opencode/skills/docs/SKILL.md
---
name: docs
description: "Reglas para generar documentación de código"
---

# Generar Documentación

Al documentar código en este proyecto:

## Formato
- Usa JSDoc para funciones públicas
- Documenta parámetros con @param y tipos
- Documenta retorno con @returns
- Incluye @example con uso básico

## README de módulos
- Propósito del módulo en una línea
- Instalación si aplica
- Ejemplo de uso mínimo
- API pública con descripción breve

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

Ejemplo: Skill para Migraciones de Base de Datos

.opencode/skills/migrations/SKILL.md
---
name: migrations
description: "Convenciones para crear migraciones de base de datos"
---

# Migraciones de Base de Datos

## Reglas generales
- Cada migración debe ser reversible (incluir up y down)
- Nombres descriptivos: 001_create_users_table.sql
- Nunca modificar una migración ya ejecutada en producción
- Incluir índices para foreign keys

## Tipos de datos preferidos
- Usar UUID para primary keys
- Usar timestamptz para fechas (con timezone)
- Usar text en lugar de varchar sin límite específico
- Usar jsonb para datos semi-estructurados

## Validaciones
- Antes de crear: verificar que la tabla no existe
- Antes de dropear: verificar que no hay dependencias
- Siempre agregar NOT NULL donde corresponda
- Incluir DEFAULT values cuando tenga sentido

Skills vs Agents vs Commands

Estos tres conceptos se complementan pero tienen propósitos distintos:

Skills (instrucciones pasivas)

Agents (entidades activas)

Commands (atajos a prompts)

Cuando usar cada uno

NecesidadUsa
Estandarizar cómo se hacen los testsSkill
Un agente especializado en seguridadAgent
Ejecutar un review rápido con un comandoCommand
Convenciones de código del proyectoSkill
Agente que solo usa herramientas de DBAgent
Generar changelog con un atajoCommand

En la práctica, se combinan. Un command puede disparar un agente que internamente carga un skill para seguir las convenciones del proyecto. Por ejemplo:

flowchart LR
    A["/review"] -->|Command| B["@security-agent"]
    B -->|Agent| C["skill: review-pr"]
    C -->|Skill| D["Instrucciones detalladas"]

El usuario escribe /review, esto activa el agente de seguridad, que carga el skill review-pr con las instrucciones detalladas del checklist.

Buenas Prácticas

Organizacion Recomendada

Para proyectos medianos o grandes, organiza los skills por dominio:

.opencode/skills/
  testing/
    SKILL.md          # Convenciones de testing
  review/
    SKILL.md          # Checklist de code review
  docs/
    SKILL.md          # Estándares de documentación
  migrations/
    SKILL.md          # Reglas para migraciones
  deploy/
    SKILL.md          # Procedimientos de deploy

Cada skill es independiente y cubre un único dominio. El agente puede cargar uno, varios o ninguno según la tarea que esté ejecutando. Esta granularidad permite que el consumo de tokens sea proporcional a la complejidad de la tarea.

Para skills globales, aplica la misma estructura en ~/.config/opencode/skills/. Los skills globales son ideales para convenciones personales como tu estilo de commits, tu checklist de review personal o tus reglas de naming.

Siguiente: Capitulo 14: Comandos Custom —>

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