Khavel

Posted on Jun 11 • Originally published at devaisemanal.com

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

#spanish #ai #español #automation

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.

Arquitectura base · TL;DR
La keyword importante es Claude Code Skills: la intencion de busqueda suele ser practica. La persona quiere saber que es un Skill, donde se guarda, como se diferencia de CLAUDE.md, slash commands, hooks, subagents y MCP, y que estructura evita gastar tokens inutiles.

Mi postura: empieza con Skills pequenos, de proyecto, con descripcion muy especifica, recursos cargados de forma progresiva y tests/manuales de verificacion. Un Skill grande y ambiguo empeora al agente igual que un README infinito: ocupa contexto, dispara en tareas que no toca y oculta decisiones operativas.

Briefing · Qué es un Claude Code Skill
Un Claude Code Skill es un paquete reutilizable de instrucciones para el agente. En la practica vive en una carpeta como .claude/skills/nombre-del-skill/SKILL.md para un proyecto o ~/.claude/skills/nombre-del-skill/SKILL.md para uso personal. El archivo SKILL.md contiene frontmatter YAML y contenido Markdown con la forma de ejecutar una tarea.

La documentacion de Claude Code explica que la descripcion del frontmatter ayuda a decidir cuando cargar el Skill. Eso es clave: al inicio no deberias meter todo el contenido de todos los Skills en contexto. El agente ve nombres y descripciones; despues carga el cuerpo del Skill cuando la tarea lo justifica.

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.

📩 Recibe una lectura semanal de herramientas IA para devs. Si estas ordenando Claude Code, Skills, hooks, MCP y agentes de repo, DevAI Semanal te resume cada semana lo importante en un email de 5 minutos para devs. → Suscribirme gratis

Checklist · La estructura mínima que sí funciona
Un Skill portable debe empezar por una descripcion accionable. Mala descripcion: Ayuda con backend. Buena descripcion: Usa este Skill cuando el usuario pida disenar, revisar o migrar endpoints FastAPI de este repositorio, especialmente autenticacion, paginacion y errores HTTP.

El cuerpo del SKILL.md deberia tener cinco bloques: objetivo, cuando usarlo, entradas esperadas, procedimiento y verificacion. Si requiere comandos, ponlos claros. Si requiere criterios de salida, define que evidencia debe devolver el agente: tests ejecutados, archivos tocados, riesgos, decisiones pendientes y enlaces a logs.

Los archivos de soporte deben vivir donde el agente pueda cargarlos tarde. La especificacion de Agent Skills habla de references/, scripts/ y assets/. Usa references/ para documentacion larga, scripts/ para utilidades ejecutables y assets/ para plantillas o imagenes. No dejes dumps, lockfiles enormes, builds, PDFs irrelevantes o exportaciones temporales en la raiz del skill.

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.

Puntos a revisar · Lo que conviene comprobar
El procedimiento podria ser: leer rutas modificadas, comprobar dependencias de autenticacion, validar modelos Pydantic, ejecutar pytest tests/api -q, revisar compatibilidad OpenAPI y devolver una tabla con riesgo, evidencia y accion recomendada. Si el proyecto tiene reglas largas, el Skill enlaza references/api-contracts.md en vez de pegarlo entero.

La diferencia frente a un prompt suelto es que el procedimiento queda versionado. Cuando el equipo aprende que siempre se olvida de revisar paginacion o codigos 409, lo corrige una vez en el Skill y todos los agentes que lo carguen heredan la mejora.

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.

Lectura práctica · Seguridad y supply chain
Un Skill puede contener instrucciones, scripts y referencias que influyen en lo que hace el agente. Por eso no deberias instalar Skills de terceros como quien instala temas de editor. Revisa procedencia, licencia, comandos, URLs externas, scripts y cualquier instruccion que intente ampliar permisos o saltarse revision humana.

La regla practica es tratar Skills como dependencias operativas. Versionalos, revisalos en PR, asigna owner y evita autoactualizaciones silenciosas. Si un Skill ejecuta scripts, esos scripts deben pasar el mismo nivel de revision que cualquier herramienta interna con acceso al repo.

En Claude Code SDK hay una diferencia importante: el campo allowed-tools del frontmatter aplica al CLI directo, pero para uso via SDK el control de herramientas se hace en la configuracion principal. No bases seguridad en un campo que tu runtime concreto puede ignorar.

Briefing · Compatibilidad con Copilot, Cursor y Codex
La parte interesante de Agent Skills es que ya no es una idea aislada de Claude. GitHub documenta Agent Skills para Copilot cloud agent, Copilot code review, Copilot CLI y modo agente en VS Code. La especificacion publica lista rutas de proyecto distintas para varias herramientas, como .claude/skills/, .github/skills/, .cursor/skills/ o .codex/skills/.

Eso no significa que todos los campos se comporten igual. Algunas plataformas ignoran metadatos, otras no ejecutan scripts del mismo modo y otras aplican reglas de permisos fuera del Skill. Si quieres portabilidad real, escribe Skills conservadores: instrucciones claras, frontmatter minimo, referencias normales y cero dependencia de una extension propietaria salvo que la declares.

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.

Lectura práctica · Errores comunes
El primer error es convertir Skills en un segundo CLAUDE.md. Si todo aplica siempre, ponlo en memoria de proyecto. Si aplica solo a una tarea, ponlo en un Skill. Mezclar ambas cosas hace que el agente reciba instrucciones duplicadas o contradictorias.

El segundo error es escribir descripciones vagas. La descripcion es el disparador semantico. Si no le dices al agente cuando usar el Skill, no se activara cuando toca o se activara en tareas parecidas pero incorrectas.

El tercer error es confiar en Skills para seguridad. Un Skill puede recordar al agente que pida aprobacion, pero la autorizacion real debe vivir en permisos, hooks, CI, protecciones de rama, allowlists y revision humana.

Conclusión

Claude Code Skills merece atencion porque resuelve un problema real: los equipos estan repitiendo instrucciones a agentes cada dia y perdiendo mejoras que deberian quedar versionadas. Un buen SKILL.md convierte experiencia operativa en procedimiento reutilizable.

Pero el formato no arregla malos procesos. Empieza pequeno, mide activacion y resultado, limita contexto, separa permisos y revisa cualquier Skill de terceros. La ventaja competitiva no sera tener cien Skills; sera tener diez Skills precisos que tu agente use justo cuando importan.

Preguntas frecuentes

¿Qué es Claude Code Skills?
Claude Code Skills es el sistema de Claude Code para cargar paquetes reutilizables de instrucciones, scripts y recursos desde carpetas con un SKILL.md obligatorio.

¿Un Skill reemplaza a CLAUDE.md?
No. CLAUDE.md contiene contexto general del proyecto; un Skill deberia cubrir una tarea repetible y concreta que no aplica a todas las sesiones.

¿Dónde se guardan los Skills de Claude Code?
Los Skills de proyecto suelen vivir en .claude/skills/<nombre>/SKILL.md y los personales en ~/.claude/skills/<nombre>/SKILL.md.

¿Claude Code Skills funciona con GitHub Copilot?
El formato Agent Skills es un estandar abierto y GitHub documenta soporte de Skills en Copilot, pero cada herramienta puede tener rutas, permisos y campos compatibles distintos.

¿Es seguro instalar Skills de terceros?
Solo si los revisas como dependencias de tooling: instrucciones, scripts, permisos, URLs externas, licencia y mantenimiento. Un Skill malicioso o descuidado puede influir en acciones del agente.

Fuentes y referencias

Publicado originalmente en devaisemanal.com.

DEV Community