Skills en Claude Code: escríbele el criterio una sola vez

Una skill en Claude Code es un archivo de texto con un criterio tuyo escrito una sola vez. Vive en una carpeta de tu proyecto, y el agente lo lee por su cuenta cuando una petición encaja con lo que ese archivo describe. Le pides «traduce este correo» y, si tienes una skill que dice «las traducciones van en tono jurídico», la traducción sale en tono jurídico sin que lo repitas. Nadie tiene que saber programar para escribir uno.

Es el tercer peldaño de una escalera que empezó con una frase. Una frase que repites cada mes se puede dejar escrita como un script que corre solo, y un script es una licuadora: rápida, tonta, hace una cosa y no se adapta. La skill es la receta. El agente es el cocinero, que lee la receta y decide cuándo encender la licuadora. Con esa imagen se entiende todo lo que viene.

El video enseña la idea en tres minutos y medio con un solo caso, el auditor de contratos. Este artículo trae lo que ahí no cabía: el archivo real, la carpeta exacta, la misma petición contestada con y sin la skill, y lo que no está comprobado todavía.

3:34

Dónde vive una skill, y cómo lo sabemos

Este es el archivo completo del traductor legal, escrito a mano. Las dos vistas son el mismo texto.

---

name: traductor-legal

description: Traduce cualquier documento a un tono formal con términos jurídicos corporativos.

---

Traduce el texto que te pasen usando un tono extremadamente formal y términos

jurídicos corporativos. Termina siempre con la línea "— Traducción jurídica".

Seis líneas. Las tres primeras, entre rayas, son la ficha: el nombre y para qué sirve. Lo demás es la regla.

La ruta es .claude/skills/<nombre>/SKILL.md, dentro de la carpeta del proyecto. La carpeta .claude lleva punto delante, así que el Finder y el Explorador la esconden por defecto; el nombre de la carpeta interior es el nombre de la skill, y el archivo se llama SKILL.md con esas mayúsculas. Un .md es un archivo de texto normal con unos signos de más; si nunca abriste uno, aquí está explicado.

Lo sabemos por dos caminos. La documentación de Claude Code lo dice, y eso sería suficiente en otra casa. Aquí vale más el segundo: se lo pedimos a la herramienta en una sesión real, «crea una skill llamada traductor-legal», y contestó ella misma antes de tocar nada: «Voy a crear la skill a nivel de proyecto en .claude/skills/», con la ruta completa en el intento de escritura. La primera versión del video enseñaba otra carpeta, .agents/skills/, que no existe; se grabó desde un guion sin comprobar y llegó hasta los audios. Por eso el canal captura sesiones en vez de copiar documentación, y por eso cada línea de este artículo sale de una captura.

La prueba: el archivo se carga solo

Sesión nueva, sin mencionar la skill ni el archivo. Solo la petición:

La última línea de la traducción solo existe dentro del archivo. Nadie se la dijo a esta sesión.

El renglón que importa es el segundo: Skill(traductor-legal). La petición no nombra la skill, y el agente la eligió leyendo la ficha del archivo, esa línea de description que dice para qué sirve. Después contesta como manda la regla, y hasta ofrece la versión casual por si no era eso lo que buscabas.

La comparación se ve mejor con las dos respuestas juntas. La misma frase, en una carpeta sin skill, devolvió esto:

Nada cambió entre las dos sesiones salvo un archivo de seis líneas en el disco. Ese es el cobro del video, y ya lo tienes capturado.

El agente te escribe la skill

Una carpeta con un contrato de limpieza adentro y la frase que dicta el video, en una sola petición:

Cinco turnos y 34 segundos. La ruta larga de la carpeta de prueba está acortada con «…».

Lo primero que hizo fue mirar la carpeta, y ahí encontró el contrato. Nadie le pidió que lo leyera. Lo abrió, escribió la skill y, antes de dar por terminado, avisó de que ese contrato no pasaría la revisión que acababa de escribir. Es el detalle que más me gusta de la captura: no se limitó a guardar un archivo, lo probó contra lo que tenía delante.

El video dice «en diez segundos» y en la captura fueron 34; la voz se grabó antes de la captura y se dejó, porque el número no cambia lo que enseña. En otra corrida, con el traductor, el agente quiso crear dos archivos y no uno: el SKILL.md y un glosario de apoyo en references/glosario.md. Una skill puede ser una carpeta con material, no solo una nota.

El archivo que escribió, sin retocar

Este es el contenido exacto que el agente guardó en el Write de arriba:

---

name: auditor-de-contratos

description: Revisa contratos (archivos .txt, .md, .pdf, .docx) en busca de una cláusula de confidencialidad válida antes de aprobarlos. Úsalo cuando el usuario pida revisar, auditar o aprobar un contrato, o mencione "auditor de contratos".

---

# Auditor de Contratos

Tu trabajo es revisar documentos de contrato y asegurarte de que **ningún contrato se apruebe sin una cláusula de confidencialidad**. Actúas como un gate de cumplimiento, no como un asesor legal general: tu único criterio de bloqueo es la presencia y calidad de esta cláusula.

## Cuándo se activa

- El usuario pide revisar, auditar o aprobar uno o varios contratos.

- El usuario pregunta si un contrato "está listo" o "se puede firmar".

- El usuario menciona explícitamente el "auditor de contratos".

## Proceso

1. **Localizar el/los contrato(s).** Si el usuario no especifica un archivo, busca documentos de contrato en el directorio de trabajo (extensiones `.txt`, `.md`, `.pdf`, `.docx`) y confirma con el usuario cuál(es) auditar si hay ambigüedad.

2. **Leer el documento completo.** No te bases solo en el título de las secciones: la cláusula puede estar redactada sin usar la palabra "confidencialidad" (ej. "información reservada", "secreto comercial", "no divulgación", "NDA").

3. **Evaluar la cláusula de confidencialidad** si existe, revisando que cubra al menos:

   - Qué información se considera confidencial.

   - La obligación de no divulgarla a terceros.

   - La duración de la obligación (idealmente incluso después de terminado el contrato).

   - Consecuencias del incumplimiento (deseable, no obligatorio).

4. **Emitir un veredicto claro**, uno de:

   - ✅ **APROBADO** — tiene cláusula de confidencialidad adecuada. Cita la sección/línea donde aparece.

   - ⚠️ **APROBADO CON OBSERVACIONES** — tiene cláusula, pero incompleta (ej. no define duración o alcance). Señala qué falta.

   - ❌ **RECHAZADO** — no existe ninguna cláusula de confidencialidad. Nunca marques un contrato sin esta cláusula como aprobado, sin importar qué tan completas estén las demás secciones.

5. **Si el veredicto es RECHAZADO o con observaciones**, propone un borrador de cláusula de confidencialidad lista para insertar, adaptada al tipo de contrato y las partes involucradas.

6. **Resumen final breve**: documento revisado, veredicto, y (si aplica) el texto sugerido para corregir el problema.

## Reglas duras

- Nunca digas que un contrato está "listo para firmar" o "aprobado" si no tiene cláusula de confidencialidad — incluso si el usuario insiste en que no es necesaria. En ese caso, señala el riesgo y deja la decisión final explícitamente en manos del usuario, sin dar tú la aprobación.

- No emitas juicios legales generales fuera del alcance de confidencialidad (otras cláusulas) a menos que el usuario lo pida explícitamente; si notas algo relevante, puedes mencionarlo brevemente aparte del veredicto principal.

- Si revisas varios contratos a la vez, entrega un veredicto individual por cada uno, no un veredicto agregado.

Escribió más de lo que dijiste. Es normal, y se edita como cualquier texto.

Fíjate en lo que añadió sin que estuviera en la petición: sinónimos de la cláusula por si el contrato la llama de otra manera, tres veredictos en vez de un sí o no, un borrador de cláusula cuando falta, y una regla dura que le prohíbe aprobar aunque insistas. Todo eso salió de una frase tuya. Si algo no te gusta, abres el archivo y lo cambias; la próxima sesión lee la versión nueva, sin avisarle a nadie ni reinstalar nada. Y si quieres que pida menos o más, lo escribes ahí mismo, en tu idioma.

Una sesión nueva lo encuentra sola

Se cierra todo, se vuelve a abrir el agente en la misma carpeta y se le pide, sin nombrar la skill:

Cinco turnos, 11,6 segundos, y la cláusula que falta ya redactada.

«Último contrato» no está en ninguna parte del archivo, y aun así el agente supo qué hacer: la ficha de la skill dice que se activa cuando pides revisar o aprobar un contrato, y el proceso que él mismo escribió dice que si no nombras el archivo, lo busque. Buscó con un comando que excluye la carpeta .claude, para no confundir la skill con un documento, encontró uno y lo rechazó por la razón exacta que le diste el día anterior.

Un detalle que conviene decir: en el informe escribió mal el nombre del archivo, contrato-limpieza-septiembria.txt, aunque lo había leído bien. Los agentes se equivocan en cosas pequeñas y conviene saberlo antes de fiarse de un informe sin abrir el archivo.

Los permisos, sin tranquilizar en falso

La primera versión del guion prometía que el agente «siempre, siempre» se detiene a pedir permiso antes de ejecutar algo. No es cierto, y es el error más peligroso de los que se corrigieron: una falsa sensación de seguridad es justo lo que hace que alguien rompa algo. Que pregunte o no depende del modo en que corre la sesión y de lo que ya esté autorizado. Este mismo canal usa a diario modos que no preguntan.

Lo que sí es cierto, y es más útil: por defecto el agente se detiene antes de tocar tus archivos y te enseña el comando exacto que va a correr, como las cajas que ves en las sesiones de arriba. Las cajas están dibujadas con el comando real de cada captura, porque las capturas corrieron sin diálogo. Y ese freno se puede apagar, por sesión y por proyecto, así que conviene saber dónde está el botón antes de apagarlo. El volante es tuyo explica cada modo con calma.

Un tropiezo real de las capturas, por si te pasa: el modo que autoriza al agente a editar tus archivos no cubre la carpeta .claude. En la primera sesión del traductor pidió permiso cuatro veces para escribir ahí, no lo obtuvo y terminó explicando lo que habría escrito. Si tu agente redacta la skill y no aparece el archivo, mira ahí antes de repetir la petición.

Lo que no está comprobado

Dos cosas que la documentación afirma y este canal no ha visto funcionar, así que no las afirma. La primera: que una skill de proyecto, al subirla al repositorio con el resto del código, queda disponible para quien más trabaje ahí. Suena lógico, es un archivo más en la carpeta, pero no lo probamos en dos máquinas. La segunda: cuántas skills conviven en una carpeta sin estorbarse al elegir. Todas las capturas de aquí tenían una sola. Cuando alguna de las dos se mida, se añade aquí con su captura, igual que todo lo demás.

Por dónde seguir

El reto es de un archivo: piensa en la instrucción que más veces le has repetido a la IA esta semana, la que empieza con «acuérdate de que…», y escríbela una vez en un SKILL.md con su ficha de dos líneas. Después pídele lo de siempre sin la instrucción, y mira si el renglón Skill(…) aparece.

Si llegaste aquí sin saber qué es un agente, el paso anterior es qué es un agente de IA y en qué se diferencia de un chat. La versión de dos minutos de este artículo es el Short Ya sabe cómo lo quiero, con las dos traducciones enfrentadas, y todos los videos del canal, con su página y su transcripción, están en la sección de videos.