Skills de Claude Code: cómo construirlos + catálogo abierto
Un skill es una de las seis piezas que componen un agente IA — la que orquesta procesos completos. Esta es la guía técnica de cómo construir uno + los 4 skills reales que viven en producción en este sitio, con su SKILL.md abierto.
¿Primera vez con agentes IA? Empieza por la anatomía completa de un agente — modelo, skills, tools, MCPs, comandos y hooks.
Qué es un skill — en profundidad
Un skill es la unidad de proceso de un agente. Mientras un prompt es una instrucción puntual y una tool es una capacidad atómica (leer un archivo, hacer un fetch), un skill orquesta varios prompts + tools en un proceso completo con voz, validaciones y output predecible.
Vive en ~/.claude/skills/<nombre>/SKILL.md (personal, cross-proyecto) o <repo>/skills/<nombre>/SKILL.md (del proyecto). El agente lee ambos automáticamente.
Anatomía del archivo
mi-skill/
SKILL.md # índice corto (≤200 líneas)
steps/
paso-1-investigar.md
paso-2-redactar.md
paso-3-publicar.md
references/
voz-de-marca.md
ejemplos.md
scripts/
deploy.py
sync.shEl SKILL.md es el índice. Cuando el proceso pasa de 3 pasos, mueves el detalle a steps/ y referencias a references/. El agente carga solo lo que necesita en cada paso, no el archivo entero. Eso ahorra tokens y mantiene el contexto limpio.
Frontmatter mínimo
---
name: mi-skill
description: "Una línea: qué hace, para quién, cuándo activarse.
Incluye 3-5 frases-trigger en lenguaje natural."
triggers: ["/mi-skill", "frase 1", "frase 2"]
extends: [voz-gnb] # skills que hereda
related: [skill-a, skill-b]
---extends permite herencia: el skill carrusel-gnb hereda de voz-gnb automáticamente — no repites las reglas de voz en cada skill de contenido.
Cómo construir tu primer skill
Las cuatro reglas que aprendí construyendo y rompiendo skills durante un año. Las prácticas finas vienen después en la siguiente sección.
La regla de las 3 veces
Si escribiste un prompt parecido 3 veces, agentízalo. Antes de eso es prompt — no skill. Después de eso, cada repetición es tiempo perdido.
Modular > monolito
Si tu SKILL.md pasa de 200 líneas, mueve los pasos largos a steps/ o references/. El agente carga solo lo que necesita en cada tarea.
Triggers en lenguaje natural
En el frontmatter pon 3-5 frases-trigger reales: “reescribe este email”, “hazlo más específico”. Así Claude lo invoca aunque no escribas el slash command.
Skill personal vs de proyecto
Skills personales globales en ~/.claude/skills/. Skills de marca o proyecto locales al repo. No contamines proyectos con voces ajenas.
Atajo: en vez de armar un skill desde cero, corre el skill /agentiza — toma tu SOP, transcripción de Loom o “así lo hago a mano” y devuelve un skill modular bien estructurado en 20 minutos. Lo cubrí a detalle en este post:
Mejores prácticas — lo que separa un skill que se invoca de uno que muere
Mis aprendizajes operando con skills propios + la spec oficial de Anthropic y la guía de agentskills.io. Cada apartado es accionable — si tu skill no cumple alguno, sabes dónde tocar.
Para Claude Code en general (contexto, permisos, debugging), ve la página de mejores prácticas de Claude Code.
1. Frontmatter que el router sí entiende
El description es lo único que el LLM ve siempre. Si no convence, tu skill nunca corre.
≤1024 caracteres, tercera persona, dice qué hace + cuándo activarse. “Genera X...” ✅, “Te ayudo con X” ❌.
≤64 chars, solo [a-z0-9-]. Gerundio recomendado (procesando-pdfs). Sin anthropic ni claude.
3-5 frases en lenguaje natural reales. Sirven para que el LLM lo invoque sin slash command.
2. Progressive disclosure — el patrón que escala
Tres niveles de carga. Solo la metadata paga peaje siempre. Todo lo demás carga a demanda.
| Nivel | Cuándo carga | Costo | Contenido |
|---|---|---|---|
| 1. Metadata | Siempre (system prompt) | ~100 tokens / skill | name + description |
| 2. SKILL.md | Cuando el skill se dispara | <5k tokens | Workflow, reglas, anti-patrones |
| 3. References / scripts | A demanda vía bash | Sin costo hasta usarlo | references/*.md, scripts/*.py |
SKILL.md → references/x.md ✅. Nunca anidar más: el LLM hace head -100 en archivos referenciados desde referencias y se pierde info.
Encabezado con índice obligatorio. Si el LLM solo lee preview, al menos sabe qué hay dentro.
Si tu skill cubre varios dominios, sepáralos: references/finance.md, references/sales.md. El LLM solo carga el dominio que pide la tarea.
value-equation.md ✅. doc2.md ❌. El nombre comunica el alcance antes de leer el archivo.
3. Nivel de libertad — match al riesgo
Cuánta interpretación le das al LLM debería depender de qué tan frágil es la tarea.
Instrucciones en prosa
Múltiples caminos válidos. Ej: análisis, copy, exploración. El LLM decide.
Pseudocódigo / script con parámetros
Patrón preferente con variación aceptable. Ej: generar boilerplate, reportes.
Script duro, parámetros mínimos
Operación frágil, secuencia exacta. Ej: migración DB, render visual estricto.
Cuando dudes, sube el nivel de libertad. El sobre-ingeniería degrada más que la libertad confiada.
4. Validación — evals primero, docs después
Si no puedes escribir 3 evals concretos, no entiendes el problema todavía. Esto invierte el orden natural — y por eso funciona.
Checklist obligatorio antes de devolver el output. Si falla un item → regenerar, no entregar.
Input + expected behavior verificable (no “debe ser bueno”). Happy path + caso límite + caso de error.
Generar → validar → si falla, regenerar solo esa pieza → repetir. El patrón canónico para calidad consistente.
Para operaciones destructivas o batch (>10 items): primero plan en archivo intermedio, valida el plan, después ejecuta.
5. Anti-patrones que matan skills
Los más frecuentes en mi propio inventario antes de auditarlo.
Description vaga: “Ayuda con documentos”. El router nunca lo selecciona.
Múltiples opciones sin default: “puedes usar A, B, C o D”. Indecisión. Da un default + escape hatch.
Info time-sensitive suelta: “antes de agosto 2025...”. Envolver en <details>Legacy</details>.
Tools MCP sin prefijo: usar create_issue en vez de GitHub:create_issue. El LLM no las encuentra.
Paths con backslash: scripts\helper.py. Falla en Unix. Siempre /, incluso en Windows.
Scripts que patean errores al LLM: el script resuelve o explica concretamente, no devuelve stack trace y se va.
Magic numbers: TIMEOUT = 47 sin explicación. Si tú no sabes por qué, el LLM tampoco.
Explicar lo que el LLM ya sabe: “PDF es un formato común que contiene texto e imágenes...”. Cada token compite con la conversación.
6. Cómo iterar un skill — con Claude mismo
El patrón recomendado por Anthropic: usar una instancia para diseñar y otra para probar.
- 1.
Resuelve la tarea sin skill con prompting normal. Lo que repites = el skill que falta.
- 2.
Pide al LLM que cree el skill capturando ese patrón. Sin prompt especial — Claude entiende la spec nativamente.
- 3.
Revisa que no infló — quita explicaciones obvias. “Remove lo que Claude ya sabe.”
- 4.
Pruébalo en sesión fresca con tareas reales. Observa dónde batalla o se salta pasos.
- 5.
Refina con base en lo observado, no en lo imaginado. Si olvidó X, hazlo más prominente o usa lenguaje más fuerte (“MUST” en vez de “always”).
- 6.
Repite. Cada iteración con uso real. No anticipar problemas hipotéticos.
Catálogo: skills que uso en producción
Estos skills viven en el repo de gabrielneuman.com y operan a diario. Cada uno tiene su SKILL.md abierto — puedes leerlo, copiarlo y adaptarlo a tu negocio.
Aprendiendo de skills y agentes
Lo último que escribí sobre construir, debuggear y operar con skills, agentes y MCPs. Llevo casi un año iterando — esto son los aprendizajes en bruto.
Cierre de mayo: el mes que dejé de operar a mano y empecé a operar con sistema
296 commits, un puñado de skills nuevos y un sensor financiero que estaba roto sin que yo lo supiera. Mayo fue el mes en que la IA dejó de ayudarme a hacer tareas y empezó a ayudarme a construir el sistema que hace las tareas.
El skill que revisa mi código antes que yo: optimizar-codigo + un loop MAA
Construí un skill que aplica disciplina de actions vs services a cada cambio que toco en el repo. Conectado a un ciclo Medir-Analizar-Actuar, el código mejora solo entre commits.
Lo que el vibe coding te deja sin revisar
Hicimos un análisis de vulnerabilidades completo del sitio y parcheamos los problemas reales. Lo que aprendí sobre seguridad en proyectos vibe-coded.
El prefetch de Next.js que cerraba sesión solo
Un Link de Next.js apuntando a la ruta de logout hacía que el prefetch automático en producción cerrara la sesión apenas cargaba el sidebar.
CodeBurn: por fin una TUI para ver a dónde se van los tokens de Claude, Codex y Cursor
Probé CodeBurn, un dashboard TUI open-source que lee las sesiones de Claude Code, Codex, Cursor, OpenCode, Pi y Copilot desde disco y te dice exactamente en qué se quemó cada dólar. Sin proxy, sin API keys.
Caveman: el skill que ataca el otro lado del pipe para reducir costos de IA
Empecé a usar Caveman, un skill open-source que reduce los tokens de salida del modelo entre 22% y 87% cambiando solo el estilo de respuesta. Complementa a RTK, no lo reemplaza.
¿Construyes tu primer agente conmigo?
Te ayudo a tomar un proceso que ya repites mucho y convertirlo en un agente IA que opere por ti — desde el SOP, ensamblando skills, tools y MCPs, hasta el dogfooding en producción. Una sesión de 60 minutos en vivo.
Agendar diagnóstico¿Listo para automatizar tu negocio?
Ayudo a empresas a escalar mediante automatización inteligente y estrategias de IA. Sin fricción, sin complicaciones, resultados en semanas.