Habilidades de Claude y SKILL.md para desarrolladores: VS Code, JetBrains y Cursor

La mayoría de los equipos utilizan mal las Habilidades de Claude de una de dos formas: o convierten SKILL.md en un vertedero de información, o nunca evolucionan de los gigantescos prompts copiados y pegados.

Ambos enfoques son negligentes. Si quieres que las Habilidades funcionen en un flujo de trabajo real de desarrollo, debes tratarlas como código y lógica de operaciones, no como poesía de prompts.

Las Habilidades de Claude son directorios anclados por un archivo SKILL.md, con scripts, referencias y activos opcionales. Funcionan gracias a la divulgación progresiva. El agente comienza cargando solo metadatos compactos, como el nombre y la descripción de la habilidad, y luego lee las instrucciones completas solo cuando la tarea coincide. Esto permite que un agente mantenga muchas habilidades disponibles sin inflar cada sesión desde el principio.

La propia guía de Anthropic deja claro la división de trabajo prevista. CLAUDE.md es para el contexto del proyecto duradero y siempre activo. Las Habilidades son para conocimiento reutilizable, guías de procedimientos (playbooks) y flujos de trabajo invocables que deben cargarse bajo demanda. Claude Code incluso incorporó los antiguos comandos personalizados en el mismo mecanismo, por lo que los archivos heredados .claude/commands/*.md siguen funcionando, pero las Habilidades son ahora la forma a largo plazo mejor y el bloque de construcción más reutilizable en cualquier flujo de trabajo de desarrollo impulsado por IA.

¿Cuándo usar Habilidades de Claude: CLAUDE.md vs Habilidades vs Hooks

Vale la pena crear una Habilidad de Claude cuando sigues pegando la misma lista de verificación, el mismo plan de despliegue, la misma rúbrica de revisión de código o los mismos errores comunes de la API interna en el chat. Anthropic recomienda explícitamente crear una habilidad cuando reutilizas el mismo procedimiento o cuando una sección de CLAUDE.md ha crecido hasta convertirse en un proceso en lugar de un hecho. Esa es la respuesta práctica a la pregunta frecuente “¿Qué es una Habilidad de Claude y cuándo debes usarla”. Usa una Habilidad para procedimientos repetibles, no para gustos generales o reglas amplias del repositorio.

La verdadera ventaja es el control sobre el costo del contexto y el comportamiento. Una buena Habilidad se carga solo cuando es relevante, mientras que un CLAUDE.md inflado se carga en cada sesión. Anthropic recomienda mantener CLAUDE.md corto y mover el conocimiento del dominio o los procedimientos a Habilidades precisamente porque la carga bajo demanda mantiene al agente enfocado en la tarea que tiene delante.

Mi regla personalista es simple. Si la instrucción debe aplicarse en cada sesión, pertenece en CLAUDE.md. Si la instrucción es un método reutilizable, una lista de verificación o un flujo de trabajo que importa solo a veces, pertenece en una Habilidad. Si la acción debe ocurrir automáticamente en cada evento coincidente, probablemente pertenezca en un gancho (hook), no en una Habilidad. El resumen de características de Anthropic enmarca esas herramientas en un modelo de capas casi exactamente así.

Un indicador práctico para cada uno: si te encuentras pegando las mismas instrucciones en cada chat, eso es una Habilidad. Si una sección de CLAUDE.md ha crecido hasta convertirse en un proceso paso a paso, extráelo en una Habilidad. Si quieres que algo se active silenciosamente cada vez que se guarda un archivo, escribe un gancho en su lugar.

Soporte de IDE para Habilidades de Claude: VS Code, JetBrains, Cursor y Codex

Claude Code funciona a través de CLI, Escritorio, VS Code, JetBrains, web y flujos de control remoto relacionados con móviles. Anthropic describe la CLI como la superficie local más completa, mientras que las integraciones de IDE intercambian algunas capacidades exclusivas de la CLI por revisiones nativas del editor, contexto de archivos y una ergonomía de flujo de trabajo más ajustada. La configuración, la memoria del proyecto y los servidores MCP se comparten a través de las superficies locales, por lo que tu configuración .claude te sigue en lugar de quedar atrapada en un solo editor.

Para VS Code, Anthropic dice que la extensión es la interfaz recomendada dentro del editor. Proporciona revisión de planes, diferencias en línea (inline diffs), soporte para menciones de archivos y acceso integrado a la CLI. El mismo flujo de instalación también expone una ruta directa para Cursor. Para JetBrains, la lista de soporte actual incluye IntelliJ IDEA, PyCharm, Android Studio, WebStorm, PhpStorm y GoLand, con visualización de diferencias, compartición de selección, accesos directos de referencia de archivos y compartición de diagnósticos integrados en el plugin.

El soporte de JetBrains es mejor de lo que muchos desarrolladores se dan cuenta. Si ejecutas claude desde el terminal integrado del IDE, las características de integración están activas automáticamente. Si inicias desde un terminal externo, Anthropic documenta el comando /ide para conectar Claude Code de nuevo a la sesión de JetBrains, y recomienda explícitamente iniciar desde la misma raíz del proyecto para que Claude vea los mismos archivos que tu IDE. Si usas modos de edición automática en JetBrains, Anthropic también advierte que los archivos de configuración del IDE pueden convertirse en parte de la superficie editable, por lo que las aprobaciones manuales son el predeterminado más seguro en ese entorno.

Ahora el punto más importante. Las Habilidades de Claude no son solo una cosa de Claude Code. Agent Skills es un estándar abierto. La guía de inicio rápido oficial de Agent Skills dice que la misma habilidad puede funcionar en VS Code con GitHub Copilot, Claude Code y OpenAI Codex, y los propios documentos de Codex de OpenAI dicen que las Habilidades están disponibles en la CLI de Codex, la extensión de IDE y la aplicación. La guía de implementación de Agent Skills añade un detalle importante de portabilidad: .agents/skills ha surgido como la convención transversal entre clientes, mientras que algunos clientes también escanean .claude/skills por compatibilidad pragmática.

Así que aquí está la regla práctica de compatibilidad que recomiendo. Si estás construyendo primero y solo para Claude Code, autoriza en .claude/skills. Si realmente quieres portabilidad entre clientes, apunta a la forma abierta de Agent Skills y usa .agents/skills como la ruta canónica. No finjas que esos dos objetivos son idénticos. Están relacionados, no son idénticos.

Referencia rápida de compatibilidad:

Estructura de archivo SKILL.md, diseño de carpetas y ubicaciones de almacenamiento

Una Habilidad adecuada es una carpeta, no un archivo markdown aleatorio en la raíz del repositorio. La especificación central requiere un directorio con un archivo SKILL.md y permite directorios opcionales scripts/, references/ y assets/. SKILL.md debe contener metadatos YAML (frontmatter) seguidos de instrucciones markdown. En la especificación, name y description son obligatorios, name está limitado a 64 caracteres usando letras minúsculas, números y guiones, compatibility es solo para requisitos reales del entorno, y allowed-tools es explícitamente experimental en las implementaciones.

Claude Code es un poco más permisivo que la especificación portable porque puede derivar un nombre del directorio y recurrir al primer párrafo cuando falta description. No deberías confiar en eso si te importa la portabilidad o la predictibilidad. Claude.ai requiere que el nombre del directorio coincida con el campo name, y su ruta de carga de habilidades personal limita las descripciones a 200 caracteres, aunque la especificación más amplia permite mucho más. La elección portable es establecer un name explícito, mantener el directorio idéntico y escribir una descripción precisa que quepa en límites ajustados. Eso responde al tema de la pregunta frecuente “¿Qué debería contener un archivo SKILL.md?” sin evadir el tema.

Comienza con una estructura tan aburrida como esta:

repo/
  .claude/
    skills/
      review-pr/
        SKILL.md
        scripts/
          review.sh
        references/
          checklist.md
        assets/
          comment-template.md

Si la portabilidad entre clientes compatibles con Habilidades es más importante que la comodidad de Claude Code, mantén la misma forma interna y cambia .claude/skills/ por .agents/skills/. La estructura de carpetas es la misma idea en cualquier caso.

Para Claude Code, las ubicaciones de almacenamiento son directas. Las habilidades del proyecto viven en .claude/skills/<nombre-habilidad>/SKILL.md. Las habilidades personales viven en ~/.claude/skills/<nombre-habilidad>/SKILL.md. Las habilidades distribuidas por plugins viven bajo <plugin>/skills/<nombre-habilidad>/SKILL.md. Anthropic documenta la precedencia a través de los ámbitos integrados como empresa sobre personal sobre proyecto, mientras que las habilidades de plugin evitan colisiones usando una forma con espacio de nombres como plugin-name:skill-name. En Windows, ~/.claude se resuelve a %USERPROFILE%\.claude, y CLAUDE_CONFIG_DIR puede reubicar todo el directorio base.

La elección entre el ámbito de proyecto y el personal es directa. Usa .claude/skills/ dentro del repositorio cuando la Habilidad esté estrechamente acoplada a esa base de código, por ejemplo, un plan de despliegue que conozca los nombres específicos de tu clúster o una rúbrica de revisión ajustada a las convenciones de tu equipo. Usa ~/.claude/skills/ para Habilidades que viajan contigo entre proyectos: listas de verificación personales, generadores de changelog genéricos, flujos de trabajo de depuración preferidos. Cualquier cosa que pondrías en un repositorio de dotfiles pertenece al ámbito personal.

Unos pocos bordes afilados merecen la pena memorizar. SKILL.md debe nombrarse exactamente con esa capitalización. La guía PDF de Anthropic recomienda nombres de carpetas en kebab-case y dice explícitamente que no se coloque un README.md dentro de la carpeta de la habilidad, porque la documentación operativa debe vivir en SKILL.md o references/. Esa misma guía también enfatiza que el nombre de SKILL.md es sensible a mayúsculas y minúsculas. Estas son restricciones aburridas, pero las restricciones aburridas son lo que hace que las herramientas sean fiables.

Claude Code también hace lo correcto para los monorepositorios. Descubre automáticamente los directorios anidados .claude/skills/ cuando trabajas dentro de subdirectorios, lo cual es ideal para habilidades a nivel de paquete o de servicio. También vigila los directorios de habilidades existentes para cambios en vivo durante la sesión actual. La única trampa de reinicio es crear un directorio de habilidades de nivel superior que no existía cuando comenzó la sesión. Anthropic documenta ese caso como el momento en que necesitas reiniciar para que el nuevo directorio pueda ser vigilado.

Mejores prácticas para Habilidades de Claude: descripciones, scripts y ámbito

La forma más rápida de crear una Habilidad inútil es pedirle a un LLM que invente una a partir de conocimientos de entrenamiento genéricos. La guía de mejores prácticas de Anthropic advierte explícitamente contra eso. Las partes valiosas son las correcciones específicas del dominio, los casos extremos, las elecciones de herramientas y las convenciones que el modelo no inventaría fiablemente por sí solo. El flujo de trabajo correcto es resolver la tarea una vez con el agente, corregirlo hasta que funcione y luego extraer el método en una Habilidad.

Delimita la Habilidad como una buena función, no como una wiki. Anthropic dice que las Habilidades deben encapsular una unidad coherente de trabajo. Si es demasiado estrecho, fuerzas que múltiples habilidades se apilen para una sola tarea. Si es demasiado amplio, el agente no puede activarlas con precisión. La guía de mejores prácticas es contundente: las habilidades excesivamente comprehensivas pueden perjudicar más que ayudar porque el modelo persigue instrucciones irrelevantes y pierde la señal.

La calidad de la descripción no es una preocupación cosmética. Es la capa de enrutamiento. Tanto Anthropic como los documentos de Agent Skills dicen que el campo description es el mecanismo principal que usa el modelo para decidir si cargar una Habilidad o no. Las buenas descripciones dicen qué hace la Habilidad, cuándo usarla y las frases de activación o tipos de archivos que un usuario mencionaría realmente. Las malas descripciones son vagas, excesivamente técnicas o lo suficientemente amplias como para coincidir con tonterías. Esa es la respuesta real a la pregunta frecuente “¿Por qué una Habilidad de Claude no se activa”. Generalmente, el enrutador es malo, no el modelo.

El contraste es claro lado a lado:

Malas descripciones — demasiado vagas para enrutar fiablemente:

• Ayuda con la revisión de código — coincide con todo, no desambigua nada
• Útil para tareas de desarrollo — más amplio que una consulta de búsqueda
• Asiste con la escritura — no es un enrutador, solo una etiqueta de categoría

Buenas descripciones — lenguaje de activación específico:

• Revisar solicitudes de pull para problemas de seguridad, riesgo de migración y pruebas faltantes. Usa cuando revises una PR, un git diff o un cambio crítico de lanzamiento.
• Generar un changelog a partir de la salida de git log. Usa cuando prepares un lanzamiento, escribas notas de lanzamiento o resumas commits desde la última etiqueta.
• Crear un nuevo manejador HTTP de Go con validación de solicitudes y middleware de errores. Usa cuando añadas un nuevo endpoint o ruta a un servicio Go.

El patrón es el mismo cada vez: declara qué hace la Habilidad, nombra las frases exactas del usuario que deberían activarla y, opcionalmente, nombra tipos de archivos o herramientas que son relevantes. Si tu descripción coincidiría con una consulta genérica de Google, no es lo suficientemente específica.

Si un flujo de trabajo tiene efectos secundarios, hazlo manual. Claude Code expone eso directamente. disable-model-invocation: true hace que una Habilidad sea solo invocada por el usuario, lo cual Anthropic recomienda para acciones como despliegues, commits o mensajes salientes. user-invocable: false va en la otra dirección y oculta la Habilidad del menú de barras (/) mientras permite que Claude la use como conocimiento de fondo. Eso responde al tema de la pregunta frecuente “¿Cuándo debe ser una habilidad manual en lugar de automática” en una sola frase: manual para riesgo, automático para guía repetible segura.

Mantén SKILL.md lo suficientemente pequeño para seguir siendo inteligible. Anthropic recomienda mantenerlo por debajo de 500 líneas y alrededor de 5,000 tokens, moviendo luego el material detallado a references/ o archivos similares con instrucciones de carga explícitas. “Lee references/api-errors.md si la API devuelve algo distinto de 200” es un buen patrón. “Ver referencias/” es perezoso. Claude Code también inyecta la Habilidad renderizada en la conversación como un mensaje y no sigue leyendo el archivo en turnos posteriores. Después de la compresión del contexto, solo el contenido reciente de la Habilidad se lleva adelante dentro de los presupuestos de tokens. Las Habilidades gigantes por lo tanto no son solo feas. Son frágiles en sesiones largas.

Una buena SKILL.md puede mantenerse muy simple:

---
name: review-pr
description: Revisar solicitudes de pull para problemas de seguridad, riesgo de migración y pruebas faltantes. Usa cuando revises una PR, un git diff o un cambio crítico de lanzamiento.
compatibility: Diseñado para Claude Code. Requiere git y gh.
disable-model-invocation: true
allowed-tools: Bash(git diff *) Bash(gh pr diff *) Read Grep Glob
---
# Revisión de PR

Lee references/checklist.md antes de ejecutar cualquier comando.

1. Recopila el diff y los archivos cambiados.
2. Señala problemas de corrección, seguridad y cobertura de pruebas.
3. Devuelve hallazgos agrupados por gravedad con referencias de archivos.
4. Sugiere primero la corrección más pequeña y segura.

Usa scripts cuando la determinismo importa más que la elocuencia. La guía de scripts de Habilidades es excelente aquí. Dice que los scripts orientados al agente deben evitar prompts interactivos, documentar el uso a través de --help, emitir mensajes de error útiles, preferir salida estructurada como JSON o CSV en stdout, enviar diagnósticos a stderr y soportar uso seguro de reintento. También recomienda fijar versiones de herramientas de una sola vez y describir los requisitos de tiempo de ejecución explícitamente en SKILL.md o el campo compatibility en lugar de asumir que el entorno tiene los paquetes correctos.

Un script orientado al agente mínimo pero correcto se ve así:

#!/usr/bin/env bash
# scripts/collect-diff.sh — llamado por la habilidad review-pr
# Uso: collect-diff.sh <base-ref> [<head-ref>]
set -euo pipefail

BASE="${1:?Uso: collect-diff.sh <base-ref> [<head-ref>]}"
HEAD="${2:-HEAD}"

# Salida estructurada a stdout para que el agente pueda parsearla
git diff "${BASE}...${HEAD}" --stat --name-only \
  | jq -Rs '{
      "changed_files": split("\n") | map(select(length > 0))
    }' \
  || { printf '{"error":"git diff falló"}\n' >&2; exit 1; }

Tres cosas hacen esto seguro para el agente. set -euo pipefail asegura que el script salga ruidosamente ante cualquier fallo en lugar de proceder silenciosamente. JSON en stdout le da al agente un formato que puede parsear sin adivinar. Los diagnósticos van a stderr para que el flujo stdout del agente se mantenga limpio. Nada de esto es inteligente. Todo es necesario.

Una trampa sutil es allowed-tools. En la especificación es experimental y el soporte varía. En Claude Code pre-aprueba herramientas específicas mientras la Habilidad está activa, pero no restringe el universo de herramientas llamables, y las reglas de denegación aún pertenecen a los permisos de Claude Code. En el SDK de Agentes de Claude, Anthropic dice explícitamente que el frontmatter allowed-tools en SKILL.md no aplica, por lo que las aplicaciones SDK deben hacer cumplir el acceso a herramientas en la configuración principal allowed_tools o allowedTools. Si ignoras esa diferencia, tu Habilidad se comportará de forma distinta en la CLI y en la automatización impulsada por SDK.

Un patrón avanzado más merece ser robado. Cuando un flujo de trabajo inundaría tu hilo principal con registros, búsquedas de archivos o resultados de investigación largos, Claude Code permite que una Habilidad se ejecute en un subagente bifurcado usando context: fork y un agent como Explore. Anthropic muestra esto para flujos de trabajo de investigación, donde el trabajo pesado ocurre en un contexto aislado y la conversación principal recibe el resumen. Para la exploración profunda de bases de código, ese es un diseño mucho mejor que una Habilidad gigante en línea que contamina la sesión principal.

Una Habilidad bifurcada se ve así en el frontmatter:

---
name: explore-codebase
description: Exploración profunda de una base de código desconocida. Usa al incorporarte a un nuevo repositorio, auditar arquitectura o mapear dependencias de módulos.
context: fork
agent: Explore
compatibility: Requiere Claude Code CLI.
---
# Explorar Base de Código

1. Recorre el árbol de directorios y resume los módulos de nivel superior.
2. Identifica los puntos de entrada principales y sus responsabilidades.
3. Mapea el grafo de dependencias entre paquetes.
4. Devuelve un resumen estructurado a la sesión principal, no la lista cruda de archivos.

La línea clave es context: fork. Sin ella, la salida de la exploración cae en línea en tu conversación. Con ella, el subagente se ejecuta en su propia ventana de contexto y devuelve un resumen. La diferencia importa en repositorios grandes donde la exploración por sí sola puede consumir miles de tokens.

Pruebas de Habilidades de Claude: activadores, corrección y comparaciones de línea base

Una Habilidad no está probada porque una demostración de camino feliz funcionó una vez. La guía de Anthropic divide las pruebas en tres capas: pruebas manuales en Claude.ai, pruebas scriptadas en Claude Code y pruebas programáticas vía la API de Habilidades. Las áreas de evaluación recomendadas son activación, corrección funcional y rendimiento contra una línea base sin la Habilidad. Esa es también la mejor respuesta a la pregunta frecuente “¿Cómo pruebas si una habilidad es fiable”. Pruebas la selección de ruta, la calidad de la salida y la eficiencia, no solo si el modelo sonaba confiado.

La guía de evaluación oficial da una estructura limpia para casos de prueba. Cada caso debe incluir un prompt de usuario realista, una descripción legible por humanos de la salida esperada y archivos de entrada opcionales. Los documentos guardan esos en evals/evals.json dentro del directorio de la Habilidad, lo cual es una convención sensata incluso si creas tu propio arnés.

Usa un archivo de fixture y un diseño de evaluación sin rodeos como este:

{
  "skill_name": "review-pr",
  "evals": [
    {
      "id": 1,
      "prompt": "Revisa esta PR por problemas de seguridad y pruebas faltantes",
      "expected_output": "Hallazgos agrupados por gravedad con referencias de archivos y al menos una recomendación de prueba.",
      "files": ["evals/files/pr-diff.patch"]
    },
    {
      "id": 2,
      "prompt": "Resumir los commits de la semana pasada",
      "expected_output": "La habilidad no debería activarse.",
      "files": []
    }
  ]
}

Mi propia regla de prueba es más dura que la que usan la mayoría de los equipos, pero se alinea con la guía oficial. Cada Habilidad seria debe tener consultas que deberían activar, consultas que no deberían activar, al menos una prueba de caso extremo y una comparación de línea base sin la Habilidad. Los ejemplos de Anthropic comparan llamadas a herramientas, llamadas a API fallidas, bucles de aclaración y uso de tokens con y sin la Habilidad porque “funciona” no es lo mismo que “mejora el flujo de trabajo”.

Si pruebas a través del SDK de Agentes de Claude, recuerda la tubería. Las Habilidades son artefactos de sistema de archivos allí, no registros programáticos. Anthropic dice que debes habilitar la herramienta "Skill" y cargar la configuración del sistema de archivos relevante a través de settingSources o setting_sources. Si omites user o project, o apuntas cwd al lugar equivocado, el SDK no descubrirá la Habilidad. Anthropic incluso recomienda preguntar “¿Qué Habilidades están disponibles?” como un chequeo de descubrimiento directo.

También prueba en el modelo y cliente en los que realmente planeas lanzar. El inicio rápido de Agent Skills abierto advierte explícitamente que la fiabilidad del uso de herramientas varía entre modelos, y algunos modelos pueden responder directamente en lugar de ejecutar el comando que la Habilidad intenta. Eso no siempre es un problema de diseño de Habilidad. A veces es un problema de selección de modelo, y tu matriz de pruebas debería exponerlo.

Solución de problemas de Habilidades de Claude: fallos comunes y soluciones

Cuando una Habilidad se comporta mal, asume empaquetado antes que inteligencia. Los fallos más comunes siguen siendo los aburridos.

• Si la Habilidad no se encuentra en absoluto, verifica que el archivo se nombre exactamente SKILL.md, con la mayúscula correcta, dentro del directorio correcto. La guía de solución de problemas de Anthropic señala explícitamente el caso del nombre del archivo, y sus documentos de Claude Code y SDK te dirigen directamente a .claude/skills/*/SKILL.md y ~/.claude/skills/*/SKILL.md como las primeras verificaciones.
• Si el frontmatter es inválido, revisa primero los delimitadores YAML y las comillas. Los ejemplos de Anthropic muestran los errores clásicos: falta ---, comillas no cerradas o nombres inválidos con espacios y mayúsculas. Los nombres de habilidades deben ser minúsculas y con guiones.
• Si la Habilidad existe pero no se activa, la descripción suele ser demasiado vaga. La propia solución de problemas de Claude Code dice incluir palabras clave que los usuarios dirían naturalmente, verificar que la Habilidad aparezca cuando preguntas “¿Qué habilidades están disponibles?” e intentar parafrasear más cerca de la descripción. La guía PDF de Anthropic añade un gran truco de diagnóstico: pídele a Claude cuándo usaría la Habilidad y escucha cómo parafrasea la descripción de vuelta a ti.
• Si la Habilidad se activa demasiado a menudo, estrecha el ámbito. Anthropic recomienda hacer la descripción más específica, añadir activadores negativos y usar disable-model-invocation: true para flujos de trabajo que quieres solo por comando explícito. El sobre-activado suele ser simplemente un lenguaje de enrutamiento sub-especificado.
• Si la Habilidad parece perder influencia en sesiones largas, recuerda que las descripciones pueden acortarse en el catálogo de Claude Code cuando hay muchas habilidades presentes, y las Habilidades invocadas se llevan después dentro de los presupuestos de tokens tras la compresión. Anthropic recomienda colocar palabras clave al frente en la descripción, recortar texto excesivo y, específicamente para Claude Code, ajustar SLASH_COMMAND_TOOL_CHAR_BUDGET si las listas de descripciones se están apretando demasiado agresivamente.
• Si un script empaquetado se cuelga o se comporta erráticamente, revisa si espera entrada interactiva. La guía de scripts dice que los agentes se ejecutan en shells no interactivos, por lo que los prompts TTY, diálogos de contraseña y menús de confirmación son errores de diseño. Acepta entrada a través de banderas, variables de entorno o stdin y haz que los fallos sean explícitos.
• Si el SDK no ve tu Habilidad, confirma que allowed_tools incluya "Skill", que settingSources o setting_sources contenga user y o project, y que cwd apunte al directorio que realmente contiene .claude/skills/. Sin esa configuración, el sistema de Habilidades no está habilitado sin importar lo correcto que parezca tu markdown.
• Si una Habilidad respaldada por MCP se carga pero las llamadas a herramientas fallan, la lista de verificación de solución de problemas de Anthropic es sensata: verifica que el servidor MCP esté conectado, confirma la autenticación y los ámbitos, prueba la herramienta MCP directamente sin la Habilidad y luego revisa los nombres exactos de las herramientas porque son sensibles a mayúsculas y minúsculas.

La verdad aburrida es que las buenas Habilidades de Claude parecen un buen ingeniería operacional. Nombres claros. Archivos pequeños. Activadores explícitos. Scripts deterministas donde se necesiten. Pruebas reales. Si tu Habilidad se lee como un libro de procedimientos conciso, el agente tiene una oportunidad de pelear. Si se lee como una lluvia de ideas, simplemente has escondido el caos en una carpeta.