MY-AGENT-SKILLS: por qué creé mi propio sistema de agents para opencode

La idea nació de una frustración simple: cada vez que quería hacer algo específico con opencode — gestionar contenedores, revisar un log del sistema, configurar una regla de nftables, o montar un backup con restic — tenía que explicarle el contexto desde cero. El asistente no sabía qué herramientas uso, qué rutas me interesan, ni qué convenciones sigo.

Podría haber escrito prompts cada vez. Pero si hay algo que aprendí en sistemas es que repetir tareas manuales es señal de que falta automatización. El mismo principio que aplico con scripts de bash y systemd timers lo quería aplicar a mi interacción con IA: definir contextos reutilizables que mi agente pudiera cargar bajo demanda.

Así nació MY-AGENT-SKILLS, un directorio en ~/MY-AGENT-SKILLS/SKILLS/ donde cada skill es un subagente especializado con instrucciones detalladas para un dominio concreto.

Qué es opencode y cómo lo uso

opencode es un copilot de terminal. No es un IDE plugin ni un chat web — corre en tu consola, accede a tu filesystem, ejecuta comandos, edita archivos. Le decís "levantame un contenedor de testing" y te lo hace. El problema es que sin contexto suficiente, sus decisiones son genéricas. Y un sysadmin no quiere genérico, quiere predecible.

Lo uso como mi interfaz principal para interactuar con el sistema. En vez de recordar la sintaxis exacta de cada herramienta, describo el objetivo y opencode lo ejecuta. Pero para que funcione bien necesita saber cómo trabajo: qué sistema operativo uso, qué herramientas prefiero, qué estructura de directorios manejo, qué políticas de seguridad sigo.

Skills en vez de prompts

Un skill no es más que un archivo SKILL.md dentro de una carpeta con el nombre del dominio. opencode detecta estos skills automáticamente y los ofrece como opciones cuando arranca una sesión o cuando invocás un agente específico.

Al cargar un skill, el agente obtiene instrucciones precisas sobre cómo comportarse en ese contexto: qué comandos usar, qué convenciones seguir, qué precauciones tomar. No es magia, es documentación ejecutable.

La estructura de un skill es sencilla:

SKILLS/
  docker-manager/
    SKILL.md
  forensic-manager/
    SKILL.md
  arch-manager/
    SKILL.md
  network-manager/
    SKILL.md
  backup-manager/
    SKILL.md
  dotfiles-manager/
    SKILL.md
  hardening-manager/
    SKILL.md
  secret-manager/
    SKILL.md
  monitoring-manager/
    SKILL.md
  automation-manager/
    SKILL.md

Cada SKILL.md incluye una descripción del dominio, ejemplos de uso, comandos frecuentes, enlaces a documentación, y variables de contexto que el agente debe conocer. Abrir uno es entender inmediatamente cómo operar en ese dominio sin tener que adivinar.

Los skills que creé

Algunos son específicos de mi stack, otros son herramientas que cualquier sysadmin usa a diario:

• arch-manager: gestión de paquetes, systemd, kernel, bootloader, configuración de red, usuarios, locale. Todo lo que toco en mi estación Arch Linux.
• docker-manager: contenedores, imágenes, volúmenes, networks, Docker Compose. También lo uso para sandboxing de malware.
• forensic-manager: dd, guymager, sleuthkit, volatility, foremost, análisis de artefactos Windows. Cuando agarro un disco a revisar, este skill me prepara el entorno.
• network-manager: nftables, WireGuard, bridges, VLANs, DNS, resolución de problemas de conectividad.
• backup-manager: restic, borg, rsync, automatización con systemd timers, verificación de restores.
• hardening-manager: CIS benchmarks, lynis, OpenSCAP, hardening de kernel, SSH, firewalls, AppArmor.
• secret-manager: pass, age, sops, GPG, bitwarden-cli, manejo de claves y archivos .env.
• monitoring-manager: health checks, métricas de recursos, alertas, líneas de base de rendimiento.
• automation-manager: systemd timers, cron, scripting, automatización multiplataforma Linux y Windows.
• dotfiles-manager: mantenimiento de mis dotfiles, creación de temas, documentación.
• homelab-manager: VMs con KVM/VirtualBox, snapshots, seguimiento de máquinas HTB/THM, writeups.
• web-security-manager: OWASP Top 10, Burp Suite, ZAP, análisis de CORS/CSP/XXE/SSRF, fuzzing.
• container-security-manager: Trivy, Docker Bench, Grype, cosign, SBOM, hardening de imágenes.
• ci-cd-manager: GitHub Actions, git hooks, pipelines, matrix builds, despliegue automatizado.
• database-manager: SQLite, PostgreSQL, MariaDB, queries, backups, migraciones, optimización.
• threat-intel-manager: MISP, feeds STIX/TAXII, IOCs, OpenCTI, workflows de threat research.
• reverse-engineering-manager: radare2, Ghidra headless, análisis de PE/ELF/Mach-O, GDB, YARA.
• openvpn-manager: conexiones VPN a laboratorios de pentesting, perfiles múltiples, troubleshooting.
• windows-manager: servicios, paquetes, procesos, disco, red, WSL, rendimiento en Windows 11.
• obsidian-manager: gestión de mi vault Personal-Vault, notas diarias, templates, búsqueda.
• ollama-manager: modelos locales, GPU acceleration, integración con opencode, API REST.
• mcp-ollama: herramientas MCP para llamar modelos de Ollama desde agents de opencode.
• learning-manager: roadmaps de aprendizaje, seguimiento de cursos/CTFs, repetición espaciada, skill trees.
• portfolio-manager: actualización de mi landing page en /files/my-web/, secciones, contenido, deploy.
• agent-creator: creación de agents personalizados de opencode con estructura, tipos, permisos y flujo de trabajo.
• orchestrator-manager: orquestación de múltiples subagentes en paralelo para tareas grandes, con protocolo de planificación, manifiesto, workers y reconciliación.

Cada skill está pensado para un momento concreto. No son excluyentes: puedo cargar docker-manager + container-security-manager juntos cuando reviso imágenes, o network-manager + hardening-manager cuando configuro un firewall.

Cómo se escribe un skill

No hay misterio. Un SKILL.md bien escrito tiene:

• Una descripción de una línea del propósito.
• Instrucciones de comportamiento: qué herramientas priorizar, qué evitar.
• Comandos de referencia con ejemplos reales.
• Rutas y variables de contexto del sistema.
• Referencias a documentación oficial o notas propias.

Un fragmento real del skill de backups:

# backup-manager

Use when creating, managing, or restoring backups.
Covers restic, borg, rsync, 3-2-1 strategy, snapshot management,
backup automation with systemd timers/cron, and restore testing.

## Context
- Backup root: /mnt/backup/
- Restic repository: /mnt/backup/restic-repo
- Borg repository: /mnt/backup/borg-repo
- Encryption: age key at ~/.config/age/key.txt

## Common operations
- restic backup /home --tag daily
- restic snapshots
- restic restore latest --target /tmp/restore
- borg create /mnt/backup/borg-repo::{now} /home
- borg list /mnt/backup/borg-repo

## Verification
After every restore, run: diff -r /original/path /tmp/restore

Eso es todo. El agente lee esto y sabe exactamente qué hacer. No necesita preguntar "dónde están tus backups?" porque ya lo sabe.

Por qué esto y no otra cosa

Existen alternativas: prompts guardados, alias de comandos, scripts de bash que envuelven llamadas a la API. Pero ninguna me da el mismo nivel de integración. Al ser parte del sistema de skills de opencode, el contexto se inyecta directamente en el loop de razonamiento del agente. No es un texto que copio y pego, es parte de su estado interno cuando trabaja.

Además, los skills evolucionan. Cuando encuentro un nuevo patrón de uso, lo agrego al SKILL.md correspondiente. Cuando una herramienta cambia, actualizo los ejemplos. Es documentación viva, no un prompt congelado en un archivo de texto.

Resultados

La diferencia es abismal. Antes pasaba los primeros 5-10 minutos de cada sesión estableciendo contexto. Ahora cargo un skill y el agente ya sabe qué sistema operativo uso, qué herramientas tengo instaladas, qué rutas me interesan y qué políticas sigo.

Errores reducidos. Las respuestas son más precisas porque el agente no adivina. Y cuando algo sale mal, puedo depurar porque el skill define explícitamente los pasos esperados.

Si usás opencode y te encontrás repitiendo el mismo contexto una y otra vez, probablemente necesitás skills. No hace falta que sean 27 como los míos. Con dos o tres que cubran tus dominios principales ya notás la diferencia.

El proyecto completo está en ~/MY-AGENT-SKILLS/SKILLS/ y voy agregando skills a medida que encuentro dominios que lo justifican. Si trabajás con opencode, te recomiendo que construyas los tuyos. Arrancá con el dominio que más frecuentes y expandí desde ahí.