Claude Code Skills: cómo escribir SKILL.md útiles sin llenar el contexto de basura

Claude Code Skills convierte instrucciones repetibles en paquetes versionables. Bien usadas reducen contexto y errores; mal usadas son otro directorio que el agente carga sin criterio.

Claude Code Skills son carpetas con un `SKILL.md` obligatorio y archivos opcionales que Claude carga bajo demanda cuando la tarea encaja con la descripcion del skill. Sirven para convertir una forma de trabajar repetible en instrucciones versionables, no para meter toda la documentacion del proyecto en otro sitio.

Dicho de forma citable: un Skill no es una extension magica, es una unidad de procedimiento. Describe cuando activarse, que pasos seguir, que archivos de soporte consultar y que comandos o scripts puede usar si la plataforma lo permite.

Dónde encaja frente a CLAUDE.md, comandos, hooks, subagents y MCP

`CLAUDE.md` es memoria estable del proyecto: stack, convenciones, comandos frecuentes, decisiones de arquitectura y reglas que aplican casi siempre. Un Skill debe ser mas estrecho: una tarea repetible como revisar migraciones, generar changelogs, publicar una release, validar una integracion o preparar un informe tecnico.

Los slash commands antiguos se han acercado mucho a Skills. Claude Code documenta que comandos personalizados y Skills pueden crear invocaciones con `/nombre`, pero Skills aportan mejor empaquetado porque pueden llevar archivos de soporte, scripts y referencias. Si hoy mantienes `.claude/commands/` con procedimientos largos, probablemente algunos deberian migrar a `.claude/skills/`.

Hooks y subagents resuelven otros problemas. Un hook ejecuta control determinista o semiautomatico en eventos del agente, como validar una herramienta antes de usarla o formatear despues de editar. Un subagent separa contexto y permisos para una tarea delegada. MCP conecta herramientas externas. Un Skill orquesta conocimiento y procedimiento; no reemplaza permisos, runtime ni herramientas.

Un ejemplo razonable de SKILL.md

Para un repositorio FastAPI, un Skill `api-review` podria tener frontmatter con `name: api-review` y una descripcion concreta: revisar endpoints FastAPI cuando el cambio toque rutas, autenticacion, validacion o contratos OpenAPI. El cuerpo no necesita explicar todo FastAPI; necesita decir como revisar este proyecto.

Reglas de contexto: el enemigo es el relleno

La razon tecnica para usar Skills no es escribir mas instrucciones; es cargar menos instrucciones en el momento correcto. El informe `Quality in the Agent Skills Ecosystem` encontro mucho desperdicio por archivos no estandar y tokens que no aportan valor al agente. Aunque cada plataforma carga recursos de forma distinta, la leccion es estable: un skill con basura alrededor cuesta contexto y puede degradar decisiones.

Manten el `SKILL.md` como mapa, no como enciclopedia. El frontmatter debe permitir discovery. El cuerpo debe dar instrucciones suficientes para empezar. Las referencias deben cargarse solo cuando la tarea lo pide. Si una referencia se usa en todas las ejecuciones, probablemente debe resumirse dentro del cuerpo; si casi nunca se usa, debe quedarse fuera del camino caliente.

Tambien conviene separar Skills por tarea, no por departamento. `frontend` es demasiado amplio. `migrar-componentes-a-shadcn`, `auditar-accesibilidad-formularios` o `generar-tests-playwright-criticos` activan mejor y ensucian menos el contexto.

Para equipos que usan varios agentes, una buena estrategia es mantener una carpeta fuente `agent-skills/` y sincronizar copias o symlinks a la ruta que usa cada herramienta. Pero no compartas Skills sensibles sin revisar diferencias de permisos entre runtimes.

Checklist de implementación

• Elige una tarea repetible que hoy el agente haga mal o tengas que explicar cada semana.
• Escribe una descripcion estrecha con verbos, contexto y casos de uso concretos.
• Define entradas, pasos, criterios de salida y evidencias que debe devolver el agente.
• Mueve documentacion larga a `references/` y scripts reutilizables a `scripts/`.
• Evita archivos no estandar, builds, lockfiles, exports y datos grandes dentro del Skill.
• Prueba activacion automatica con tres prompts reales y uno que no deberia activar el Skill.
• Versiona el Skill en Git y revisalo como cualquier cambio de tooling interno.
• Documenta permisos fuera del Skill si usas SDK, hooks, MCP o subagents.
• Mide si mejora tiempo de tarea, errores repetidos, tokens y calidad del diff.
• Retira o fusiona Skills que casi nunca se activan o se solapan demasiado.