¿Cuando tiene sentido crear un custom skill?
Cuando le pedí por enésima vez a Claude Code que revisara una pull request siguiendo el mismo criterio, arquitectura, seguridad, tests, etc, me dí cuenta que el contexto que estaba gestionando debía vivir en el repositorio, y no en mi cabeza. Ahí es cuando tiene sentido crear un custom skill.
Un skill en Claude Code no es un alias de terminal ni un snippet guardado. Es un contrato: le dices al asistente qué rol adoptar, qué pasos seguir y qué criterios aplicar cada vez que invocas `/tu-comando`. La diferencia con "escribir un prompt largo cada vez" parece pequeña hasta que trabajas en equipo o retomas un proyecto después de tres semanas.
¿Qué es un skill?
Técnicamente, un skill es un fichero Markdown que Claude Code carga cuando detecta el slash command correspondiente. Vive en `~/.claude/` (global, disponible en todos los proyectos) o en `.claude/` dentro del repositorio (específico del proyecto, versionable con git). El nombre del fichero determina el comando: `review.md` → `/review`.
El contenido del fichero es literalmente las instrucciones que Claude seguirá. No hay API especial, no hay sintaxis propia más allá del Markdown estándar. Puedes incluir secciones, listas, ejemplos, condiciones. Puedes referenciar el argumento que el usuario pase al comando con `{{args}}`. Claude lee ese fichero y actúa en consecuencia.
```
~/.claude/
skills/
review.md → /review
deploy-check.md → /deploy-check
.claude/ (en el repo)
skills/
seed-db.md → /seed-db
```
La distinción global/proyecto no es cosmética: un skill de revisión de código puede ser global porque aplica a cualquier proyecto, pero un skill que genera datos de prueba para tu esquema de base de datos concreto no tiene sentido fuera del repositorio.
Un skill que funcione de verdad
El error más común es convertir el skill en un conjunto de instrucciones. Funciona, pero mal. Lo que distingue un skill útil es que captura *decisiones*, no solo pasos.
Tomemos un ejemplo real. Supón que quieres un skill `/blog` para generar borradores. La versión mediocre dice: "Escribe un post de blog sobre el tema que te dé el usuario." La versión útil especifica el tono del blog, la longitud objetivo, qué estructuras evitar (listas interminables, intros tipo resumen), cómo terminar, y dónde guardar el fichero resultante. Esa diferencia es la que hace que el output sea publicable con retoques mínimos en lugar de un punto de partida genérico.
Un buen skill tiene tres partes bien diferenciadas:
Contexto del rol. Quién es Claude en este contexto. No "eres un asistente útil" — eso es el default. Algo concreto: "Eres el revisor de arquitectura del equipo. Tu criterio principal es la mantenibilidad a largo plazo, no la elegancia."
Procedimiento explícito. Los pasos en orden, con condiciones si las hay. Qué hacer cuando el usuario no pasa argumentos. Qué preguntar antes de ejecutar si hay ambigüedad. Si hay pasos destructivos (escribir ficheros, ejecutar comandos), menciona cuáles son para que el usuario tenga contexto antes de aprobar.
Criterios de calidad o restricciones. Qué *no* hacer es tan importante como qué hacer. Si tu skill de revisión de PRs no debe sugerir refactors fuera del scope del cambio, escríbelo. Si el borrador de blog no debe empezar con "En este artículo veremos…", escríbelo. Estas restricciones son el conocimiento tácito del equipo hecho explícito.
Un skill como parte del equipo
Aquí es donde la cosa se pone interesante. Un prompt que guardas en tu head.txt personal muere contigo. Un skill versionado en `.claude/skills/` del repositorio es documentación ejecutable. Cualquier miembro del equipo puede clonar el repo y acceder a los mismos flujos de trabajo, siguiendo los mismos criterios y estandares.
Esto tiene implicaciones a la hora de diseñar los skills. Cuando solo los utilizas tú, puedes ser implícito, tu sabes que cuando lo ejecutes hay pasos que ya se habrán ejecutado cuando lo invoques. Por contra, si lo va a utilizar todo el equipo, hay que ser explícito sobre las precondiciones, sobre lo que hace el skill exactamente y sobre lo que no hace. Como símil de programación seria la diferencia entre documentar una función pública versus una privada.
También significa que los skills evolucionan. La primera versión de tu skill de code review probablemente no cubre todos los casos. Trátalo como código: itera, haz commit de los cambios, pide feedback. El historial de git de un skill es en sí mismo documentación sobre cómo ha cambiado el criterio del equipo con el tiempo.
¿Qué no es un skill?
Un skill no es un agente autónomo. No va a tomar decisiones fuera de las instrucciones que le des, y tampoco debe hacerlo. Cuando el flujo de trabajo requiere genuina adaptación según contexto que no puedes anticipar, es señal de que el skill está asumiendo demasiado o de que el problema no está lo suficientemente definido.
También hay que resistir la tentación de crear un skill para todo. El coste de invocar `/mi-skill` en lugar de escribir una instrucción directa es bajo, pero el coste de mantener un catálogo de skills mediocres o desactualizados no es cero. Crea un skill cuando el flujo de trabajo sea repetible, cuando el contexto necesario sea no trivial, o cuando quieras que otros lo usen. Para una consulta puntual, escribe la instrucción directamente.
Mi primer skill
Seguro que tienes un prompt que copias de un fichero de notas cada vez que quieres hacer algo en concreto, ese es tu candidato a ser tu primer skill. Añade la información necesaria, todo aquello que mentalmente escribes o haces antes de copiar del fichero, y pruebalo hasta que te sientas comodo.
Los skills no son magia, pero sí son una forma de hacer que el conocimiento operacional de un equipo sea reutilizable y consistente. Eso, en proyectos con más de un par de personas o con más de un par de semanas de vida, vale bastante.