Según la documentación oficial de Claude Code skills, una skill es una carpeta que contiene un archivo SKILL.md con frontmatter YAML e instrucciones en markdown. Claude carga el nombre y la descripción al iniciarse, luego obtiene el cuerpo completo solo cuando la skill es necesaria. Ese diseño de divulgación progresiva mantiene el contexto limpio. Lo que obtienes aquí: una skill original para auditar enlaces internos, escrita desde cero, con casos de prueba del disparador, una rúbrica de resultados y los pasos de empaque para hacerla repetible.
Un Ejemplo SKILL.md Funcional
Comencemos con el artefacto terminado para que veas hacia dónde nos dirigimos. A continuación hay una skill que audita enlaces internos en un sitio. Cópiala, instálala y luego lee el resto del post para entender cada decisión.
description: >
Audits internal links in a project's HTML or Markdown output.
Use when the user asks to check broken links, find dead anchors,
audit site links, or review internal navigation before a deploy.
``
## Internal Link Audit
``
Run a link audit against the built output or source files.
``
### Steps
``
1. Collect all internal links (href or markdown link targets starting
with / or a relative path).
2. Resolve each link against the project root.
3. Check whether the resolved target file or anchor exists on disk.
4. Report broken links grouped by source file. For each broken link,
show: source file, link text, href, and the reason it fails
(missing file, missing anchor, or redirect loop if detectable).
5. List passing links only in a summary count, not individually.
6. If zero broken links are found, say so explicitly.
``
### Output format
``
- Broken links: grouped table per source file.
- Summary line: "X of Y internal links are broken."
- If scripts/ contains check-links.sh, run it first and append
Claude's analysis below the script output.
Esa es una skill real y funcional. Guárdala en ~/.claude/skills/internal-link-audit/SKILL.md y estará disponible inmediatamente en cada proyecto.
Algo a tener en cuenta: la documentación oficial confirma que los comandos personalizados se han fusionado con las skills. Ambos se pueden invocar con /name. Entonces /internal-link-audit funciona como un comando directo, y Claude también lo hará coincidir automáticamente desde una solicitud en lenguaje natural. Estos no son dos mecanismos separados.
Elige una Tarea Estrecha y Escribe la Descripción
El campo description no es documentación. Es el disparador. Cada palabra en él ayuda a Claude a hacer coincidir la skill con el momento correcto o añade ruido que empeora la coincidencia.
La guía de Hidekazu Konishi lo explica claramente: una descripción vaga es la razón más común por la que una skill nunca se activa. Escríbela en tercera persona. Comienza con el caso de uso principal. Luego enumera las frases reales que escriben los usuarios, porque la coincidencia ocurre contra esas frases, no contra tu idea interna de la skill.
Descripción mala: Ayuda con enlaces y cosas relacionadas en proyectos web.
Mejor: Audita enlaces internos en la salida HTML o Markdown de un proyecto.
Use when the user asks to check broken links, find dead anchors,
audit site links, or review internal navigation before a deploy.
Observa que la segunda versión destaca la acción ("Audita enlaces internos"), nombra los tipos de archivo, y luego proporciona cuatro frases de disparador concretas en la cláusula Use when. Cada frase es algo que un desarrollador escribiría realmente.
Lo estrecho es mejor
Resiste la tentación de construir un "verificador de enlaces general". Una skill que hace una cosa bien se dispara de forma confiable. Una skill que promete verificar enlaces, validar redirecciones e informar sobre la velocidad de la página se dispara de forma poco confiable y produce resultados inconsistentes. Elige el trozo más pequeño y útil. Siempre puedes escribir una segunda skill para el resto.
Para la auditoría de enlaces internos, las decisiones de estrechez fueron:
- Solo enlaces internos, no externos (herramientas diferentes, modos de fallo diferentes)
- Verifica la existencia de archivos y la existencia de anclas, no el estado HTTP
- Reporta enlaces rotos agrupados por archivo fuente, no como una lista plana
Cada decisión de restricción hace que las frases gatillo sean más específicas y el formato de salida más fácil de validar.
Control de Invocación y Archivos de Soporte
Las habilidades se cargan automáticamente cuando Claude coincide con la descripción, y también responden a comandos explícitos /nombre-habilidad. Según la documentación oficial, Claude escanea cuatro ubicaciones al inicio: personal (~/.claude/skills/), proyecto (.claude/skills/), plugin y empresa. La empresa reemplaza a personal, personal reemplaza a proyecto. Conocer la jerarquía importa cuando entregas una habilidad a un equipo donde la personalización local podría entrar en conflicto.
Para la invocación, tienes dos caminos:
- Automático: Claude lee tu solicitud, la compara contra descripciones cargadas, activa la habilidad. No se necesita comando de barra.
- Explícito: Escribes /internal-link-audit. Claude carga el cuerpo completo de
SKILL.mdy la ejecuta. Útil para pruebas y para momentos donde la coincidencia automática no se activa.
Ambos caminos ejecutan las mismas instrucciones. La distinción no es "manual versus automático", es sobre qué señal usa Claude para decidir que la habilidad aplica.
Archivos de soporte
Una carpeta de habilidad puede contener más que solo SKILL.md:
scripts/: Código ejecutable (Bash, Python) que el cuerpo de la habilidad referencia. La habilidad internal-link-audit referenciascripts/check-links.shsi existe, así puedes insertar un script real de verificación de enlaces después sin cambiar las instrucciones.references/: Documentación detallada que Claude carga bajo demanda, no en cada invocación. Bueno para reglas de casos extremos que no quieres desordenando las instrucciones principales.assets/: Plantillas y formatos de salida.
Para una primera habilidad, SKILL.md solo está bien. Añade scripts/ cuando tengas un comando que realmente quieras ejecutar. Añade references/ cuando tus instrucciones empiezan a sentirse largas porque estás manejando una docena de casos extremos en línea.
Si ya estás gestionando un CLAUDE.md para instrucciones de proyecto, las habilidades se alinean con eso, no son un reemplazo. El post Claude.md for agencies cubre cómo estructurar ese archivo por separado; las habilidades manejan tareas estrechas y reutilizables que no pertenecen en un archivo de instrucción global.
Ejecuta Pruebas de Gatillo Positivo y Negativo
La escritura es la parte fácil. Las pruebas son donde la mayoría de las personas se detienen muy pronto. Según la guía de Towards Data Science sobre habilidades de Claude Code listas para producción, "pruebas" aquí significa lanzar indicaciones reales a la habilidad y verificar si se comporta correctamente, no pruebas unitarias en el sentido del software.
Necesitas dos tipos de casos de prueba: positivo (debe activarse) y negativo (no debe activarse).
Casos de gatillo positivo para internal-link-audit
Estos indicaciones deben todos invocar la habilidad automáticamente:
- "Verifica enlaces internos rotos antes de desplegar."
- "Encuentra anclajes muertos en mi salida de markdown."
- "Audita los enlaces del sitio en la carpeta de compilación."
- "¿Hay enlaces rotos en el sitio?"
- "Revisa la navegación interna en todo el proyecto."
Casos de disparo negativo
Estos indicadores NO deberían activar la habilidad. Si lo hacen, tienes un problema de sobre-activación.
- "Verifica si los enlaces externos en mi README aún funcionan." (enlaces externos, territorio de otra habilidad)
- "Valida mi sitemap.xml." (tarea completamente diferente)
- "Encuentra imágenes rotas en la página." (imágenes, no enlaces)
- "Revisa el estado HTTP de mis puntos finales de API." (HTTP, no sistema de archivos)
Rúbrica de resultados
Una buena salida de /internal-link-audit debe cumplir con todos los siguientes:
| Criterio | Condición de aprobación |
|---|---|
| Agrupa los enlaces rotos por archivo de origen | Sí, con una tabla por archivo |
| Muestra archivo de origen, texto del enlace, href y motivo del fallo | Los cuatro campos presentes para cada enlace roto |
| Los enlaces que funcionan aparecen solo en el recuento resumido | Sin lista larga de enlaces que funcionan |
| Mensaje explícito de "cero enlaces rotos" cuando está limpio | Presente cuando corresponda |
| Salida del script colocada al principio si existe check-links.sh | El script se ejecuta primero, análisis adjunto debajo |
| No revisa enlaces externos | Enlaces externos ausentes del reporte |
Ejecuta primero los casos positivos. Si la habilidad se activa en los cinco, pasa a los casos negativos. Si se activa en algún caso negativo, tienes un problema de descripción.
Corregir activaciones excesivas, activaciones perdidas y salidas débiles
Tres modos de fallo, tres soluciones. Son problemas separados y cada uno tiene una solución diferente.
La activación excesiva significa que la skill se ejecuta cuando no debería. Generalmente causada por una descripción demasiado amplia. La solución es añadir lenguaje de exclusión en la cláusula "Usar cuando":
Do NOT use for external link checks, HTTP status checks,
sitemap validation, or image audits.
Añadir exclusiones explícitas reduce la superficie de coincidencia sin eliminar los activadores positivos.
Las activaciones perdidas significan que la skill existe pero nunca se ejecuta automáticamente. La descripción no coincide con el lenguaje real del usuario. La solución es añadir más frases de activación que reflejen cómo la gente realmente pregunta, no cómo describirías formalmente la tarea. "¿Hay enlaces rotos?" es diferente a "auditar navegación interna", ambas deberían ejecutar la misma skill.
La guía de Towards Data Science describe un bucle de optimización: dividir casos de prueba, medir tasa de activación, generar descripciones mejoradas, elegir la mejor puntuación. Puedes hacerlo manualmente con un puñado de prompts, o usar la skill de creador de skills de Anthropic para semi-automatizarlo.
La salida débil significa que la skill se ejecuta pero la salida es inconsistente o incompleta. Este es un problema del cuerpo, no de la descripción. Mira la rúbrica que definiste. ¿Qué criterios están fallando? Añade instrucciones de formato más específicas. Si en la salida falta la columna de razón del fallo, indícalo explícitamente en las instrucciones. Si está listando todos los enlaces que pasan (que no quieres), añade "No listar enlaces que pasan individualmente".
Si estás gestionando un conjunto de automatizaciones Claude Code y quieres la perspectiva general de en qué skills encajan, el post de superpotencias de Claude Code cubre el flujo de trabajo circundante.
Para equipos en crecimiento o agencias que manejan múltiples proyectos de clientes, la página dedicada de configuración de Claude Code para agencias vale la pena revisar, aborda cómo organizar skills en un entorno multi-proyecto.
Empaquetar la Skill y mantenerla
Una vez que la skill pasa todas las pruebas positivas y ninguna de las negativas, empaquétala adecuadamente.
Estructura de carpeta final
~/.claude/skills/internal-link-audit/
├── SKILL.md
├── scripts/
│ └── check-links.sh (optional, referenced in instructions)
└── references/
└── anchor-edge-cases.md (optional, for edge-case rules)
Compartir entre proyectos y personas
Las skills personales en ~/.claude/skills/ están disponibles en todos los proyectos en tu máquina. Para distribución en equipo, mueve la skill a un repositorio compartido y haz que los miembros del equipo creen un symlink o la copien en su carpeta de skills personales, o cómitela en .claude/skills/ en un repositorio de proyecto compartido para acceso con alcance de proyecto.
El formato de skill es un estándar abierto. Según la guía de compilación de freeCodeCamp, la misma estructura SKILL.md funciona en Claude Code, GitHub Copilot, Cursor y Gemini CLI; las rutas de instalación difieren pero el formato de archivo no. Para Claude Code, la ruta es ~/.claude/skills/. Para Copilot, es ~/.copilot/skills/. Mismo archivo, home diferente.
Mantenimiento
Las skills se desvían. La estructura del proyecto cambia, el formato de salida necesita actualización, o las frases de activación dejan de coincidir con cómo el equipo habla sobre la tarea. Trata SKILL.md como cualquier otro documento en tu repositorio: versiona, revisa cuando cambia el flujo de trabajo subyacente, y re-ejecuta las pruebas de activación después de cualquier edición en la descripción.
Una lista de verificación de mantenimiento numerada:
- Re-ejecuta todas las pruebas de activación positivas y negativas después de cualquier cambio de descripción.
- Actualiza la rúbrica de resultados si los requisitos de formato de salida cambian.
- Si añades un script a
scripts/, referencíalo explícitamente en el cuerpo deSKILL.mdpara que Claude sepa que debe usarlo. - Cuando promuevas una skill personal a skill de equipo, revisa las frases de activación; los miembros del equipo pueden usar lenguaje diferente al tuyo.
- Elimina habilidades que ya no uses. Las habilidades obsoletas que se disparan inesperadamente son peor que no tener habilidad alguna.
FAQ
¿Exactamente dónde necesita vivir el archivo SKILL.md?
Para habilidades personales disponibles en todos los proyectos, la ruta es ~/.claude/skills/your-skill-name/SKILL.md. El nombre del directorio se convierte en el comando de barra. Para habilidades con alcance de proyecto (disponibles solo en un repositorio), usa .claude/skills/your-skill-name/SKILL.md dentro de la raíz del proyecto. Las habilidades empresariales siguen una ruta separada gestionada por el administrador de Claude Code de tu organización.
¿La habilidad carga su contenido completo cada vez que Claude inicia?
No. Según la documentación oficial, Claude escanea los directorios de habilidades al iniciar pero carga solo el nombre y la descripción en contexto. El cuerpo completo de SKILL.md se carga solo cuando la habilidad coincide con una solicitud. Es el diseño de divulgación progresiva: las descripciones permanecen en contexto, las instrucciones completas se cargan bajo demanda.
¿Puedo tener más de una habilidad que se dispare para la misma solicitud?
Las habilidades se cotejan individualmente. Si dos habilidades tienen descripciones que coinciden con la misma solicitud, se aplica la jerarquía de prioridades: empresarial anula personal, personal anula proyecto. Dentro del mismo nivel, es recomendable que distingas las descripciones con más cuidado para que solo se dispare la habilidad deseada. Los disparadores duplicados usualmente indican que dos habilidades tienen un alcance superpuesto y deberían fusionarse o delimitarse mejor.
¿Qué sucede si la descripción dice "Usar cuando" pero el usuario escribe el comando de barra directamente?
La habilidad se ejecuta de todas formas. La invocación explícita mediante /skill-name omite completamente la coincidencia automática y carga el cuerpo completo de inmediato. La cláusula "Usar cuando" del campo description se aplica solo a la coincidencia automática. Entonces un comando de barra directo siempre funciona, incluso si la redacción del usuario no habría activado la detección automática.
¿Cómo sé cuándo usar una habilidad en lugar de añadir instrucciones a CLAUDE.md?
CLAUDE.md es para contexto siempre activo: estructura del proyecto, convenciones de código, cosas que Claude debe saber en cada sesión. Las habilidades son para tareas bajo demanda: cosas que haces a veces, no siempre, y para las que quieres un resultado consistente. Si te encuentras añadiendo un flujo de trabajo de varios pasos a CLAUDE.md, probablemente debería estar en una habilidad en su lugar.
El campo description realiza el trabajo que la mayoría de las personas cree que hace el cuerpo. Escribe frases de disparo del vocabulario real de tu equipo, mantén la tarea estrecha, y lo demás sigue.