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

La mayoría de los equipos utilizan mal las Claude Skills de una de dos maneras. O convierten SKILL.md en un vertedero de información, o nunca se alejan de los enormes prompts copiados y pegados.

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

Las Claude Skills son directorios anclados por 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 skill, y luego lee las instrucciones completas solo cuando la tarea coincide. Esto permite que un agente mantenga muchas skills disponibles sin inflar cada sesión desde el inicio.

Si también operas Hermes Agent, la misma forma en disco se alinea con la especificación de estilo agentskills que documenta Hermes: la activación condicional, el escaneo del hub y la distinción entre secretos y configuración se detallan en Creación de Skills para Hermes Agent — Estructura de SKILL.md y Mejores Prácticas.

La propia guía de Anthropic deja bastante clara la división de trabajo prevista. CLAUDE.md es para el contexto de proyecto duradero y siempre activo. Las Skills son para conocimiento reutilizable, guiones de actuación (playbooks) y flujos de trabajo invocables que deben cargarse bajo demanda. Esto convierte a las Skills en el lugar natural para codificar un ciclo de desarrollo guiado por especificaciones: especificar, planificar, implementar, validar, cuando se desea más estructura que el “vibe coding” pero menos ceremonia que un andamiaje completo de Spec Kit. Consulta GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows para ver cómo las skills de Claude Code se comparan con alternativas portátiles e integradas en el IDE. Si prefieres instalar ese ciclo preconfigurado y forzado en lugar de crearlo tú mismo, Superpowers empaqueta exactamente este tipo de pila de skills: lluvia de ideas, planificación, revisión por subagentes, TDD, como un plugin instalable.

Claude Code incluso integró los antiguos comandos personalizados en el mismo mecanismo, por lo que los archivos legacy .claude/commands/*.md siguen funcionando, pero las Skills son ahora la mejor forma a largo plazo y el bloque de construcción más reutilizable en cualquier flujo de trabajo de desarrollo impulsado por IA.

Cuándo usar Claude Skills: CLAUDE.md vs Skills vs Hooks

Vale la pena crear una Claude Skill cuando sigas pegando la misma lista de verificación, el mismo guion de despliegue, el mismo criterio de revisión de código o los mismos problemas internos de la API en el chat. Anthropic recomienda explícitamente crear una skill cuando sigas reutilizando el mismo procedimiento, o cuando una sección de CLAUDE.md haya crecido hasta convertirse en un proceso en lugar de un hecho. Esa es la respuesta práctica a la pregunta de la FAQ “¿Qué es una Claude Skill y cuándo debes usar una?”. Usa una Skill 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 Skill 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 de dominio o los procedimientos a Skills precisamente porque la carga bajo demanda mantiene al agente enfocado en la tarea que tiene delante.

Mi regla opinada es simple. Si la instrucción debe aplicarse en cada sesión, pertenece en CLAUDE.md. Si la instrucción es un método, lista de verificación o flujo de trabajo reutilizable que solo importa a veces, pertenece en una Skill. Si la acción debe ocurrir automáticamente en cada evento coincidente, probablemente pertenezca en un hook, no en una Skill. La descripción de funciones de Anthropic enmarca esas herramientas en un modelo de capas casi exactamente igual.

Un indicio práctico para cada una: si te encuentras pegando las mismas instrucciones en cada chat, es una Skill. Si una sección de CLAUDE.md ha crecido hasta convertirse en un proceso paso a paso, extráela a una Skill. Si quieres que algo se dispare silenciosamente cada vez que se guarda un archivo, escribe un hook en su lugar. También hay una cuarta capa que vale la pena conocer: cuando una tarea genera mucha salida intermedia ruidosa que no quieres que ensucie la sesión principal, como la exploración de la base de código o una gran ejecución de pruebas, es un trabajo para un subagente, no para una Skill.

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

Claude Code se ejecuta en 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 una revisión nativa 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 entre las superficies locales, por lo que tu configuración de .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, diffs en línea, soporte para mención 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 actual de IDEs soportados incluye IntelliJ IDEA, PyCharm, Android Studio, WebStorm, PhpStorm y GoLand, con visualización de diffs, compartición de selección, atajos 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 la terminal integrada del IDE, las funciones de integración están activas automáticamente. Si inicias desde una terminal externa, Anthropic documenta el comando /ide para conectar Claude Code de vuelta a la sesión de JetBrains, y recomienda explícitamente iniciar desde la misma raíz de 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 valor predeterminado más seguro en ese entorno.

Ahora el punto más importante. Las Claude Skills no son solo una cosa de Claude Code. Agent Skills es un estándar abierto. El inicio rápido oficial de Agent Skills dice que la misma skill puede funcionar en VS Code con GitHub Copilot, Claude Code y OpenAI Codex, y los propios documentos de Codex de OpenAI dicen que las Skills 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 emergido como la convención 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 solo para Claude Code primero, crea 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 pretendas que esos dos objetivos son idénticos. Están relacionados, no son idénticos.

Referencia rápida de compatibilidad:

Estructura, disposición de carpetas y ubicaciones de almacenamiento del archivo SKILL.md

Una Skill adecuada es una carpeta, no un archivo markdown aleatorio situado en la raíz del repositorio. La especificación central requiere un directorio con un archivo SKILL.md y permite directorios opcionales de scripts/, references/ y assets/. SKILL.md debe contener frontmatter YAML seguido de instrucciones en 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 entre implementaciones.

Claude Code es un poco más flexible que la especificación portable porque puede derivar un nombre del directorio y recurrir al primer párrafo cuando falta description. No deberías depender de 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 skills personalizadas 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 encaje en límites ajustados. Eso responde al tema de la FAQ “¿Qué debe contener un archivo SKILL.md” sin evasivas.

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 Skills importa más que la conveniencia 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 straightforward. Las skills de proyecto viven en .claude/skills/<skill-name>/SKILL.md. Las skills personales viven en ~/.claude/skills/<skill-name>/SKILL.md. Las skills distribuidas por plugins viven bajo <plugin>/skills/<skill-name>/SKILL.md. Anthropic documenta la precedencia entre los alcances integrados como empresa sobre personal sobre proyecto, mientras que las skills 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 alcance de proyecto y el personal es straightforward. Usa .claude/skills/ dentro del repositorio cuando la Skill esté estrechamente acoplada a esa base de código, por ejemplo, un guion de despliegue que conoce tus nombres de clúster específicos o un criterio de revisión ajustado a las convenciones de tu equipo. Usa ~/.claude/skills/ para Skills que viajan contigo entre proyectos: listas de verificación personales, generadores genéricos de changelog, flujos de trabajo de depuración preferidos. Todo lo que pondrías en un repositorio de dotfiles pertenece al alcance personal.

Hay algunos bordes afilados que vale la pena memorizar. SKILL.md debe nombrarse exactamente con esa capitalización. La guía en PDF de Anthropic recomienda nombres de carpetas en kebab-case y dice explícitamente que no se debe colocar un README.md dentro de la carpeta de la skill, 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 las que hacen que las herramientas sean confiables.

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

Mejores prácticas de Claude Skills: descripciones, scripts y alcance

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

Delimita el alcance de la Skill como una buena función, no como una wiki. Anthropic dice que las Skills deben encapsular una unidad de trabajo coherente. Si es demasiado estrecha, obligas a apilar múltiples skills para una sola tarea. Si es demasiado amplia, el agente no puede activarlas con precisión. La guía de mejores prácticas es franca en que las skills demasiado comprehensivas pueden hacer más daño que bien porque el modelo persigue instrucciones irrelevantes y pierde la señal.

La calidad de la descripción no es una cuestió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 el modelo usa para decidir si cargar una Skill o no. Las buenas descripciones dicen qué hace la Skill, cuándo usarla y las frases de activación o tipos de archivos que un usuario mencionaría realmente. Las malas descripciones son vagas, demasiado técnicas o lo bastante amplias para coincidir con tonterías. Esa es la respuesta real a la pregunta de la FAQ “¿Por qué una Claude Skill no se está activando?”. Normalmente el enrutador es malo, no el modelo.

El contraste es claro lado a lado:

Descripciones malas — demasiado vagas para enrutarse de forma fiable:

• 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

Descripciones buenas — lenguaje de activación específico:

• Revisa solicitudes de extracción (pull requests) en busca de problemas de seguridad, riesgo de migración y pruebas faltantes. Úsalo al revisar un PR, un diff de git o un cambio crítico de lanzamiento.
• Genera un changelog a partir de la salida de git log. Úsalo al preparar un lanzamiento, escribir notas de lanzamiento o resumir commits desde la última etiqueta.
• Crea un nuevo manejador HTTP de Go con validación de solicitudes y middleware de errores. Úsalo al agregar un nuevo endpoint o ruta a un servicio de Go.

El patrón es el mismo cada vez: declara qué hace la Skill, nombra las frases exactas del usuario que deberían activarla y opcionalmente nombra tipos de archivos o herramientas que sean relevantes. Si tu descripción coincidiera 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 lo expone directamente. disable-model-invocation: true hace que una Skill 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 Skill del menú de barras, permitiendo que Claude la use como conocimiento de fondo. Eso responde al tema de la FAQ “¿Cuándo debería una skill ser manual en lugar de automática?” en una sola frase: manual para el riesgo, automático para la orientación repetible y segura.

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

Un buen SKILL.md puede permanecer muy plano:

---
name: review-pr
description: Revisa solicitudes de extracción (pull requests) en busca de problemas de seguridad, riesgo de migración y pruebas faltantes. Úsalo al revisar un PR, un diff de git 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
---
# Revisar PR

Lee references/checklist.md antes de ejecutar ningún comando.

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

Usa scripts cuando la determinación importa más que la elocuencia. La guía de scripts de Skills es excelente aquí. Dice que los scripts orientados al agente deben evitar los prompts interactivos, documentar el uso a través de --help, emitir mensajes de error útiles, preferir salidas estructuradas como JSON o CSV en stdout, enviar diagnósticos a stderr y soportar un uso seguro para reintentos. También recomienda fijar versiones de herramientas de un solo uso y describir los requisitos de ejecución explícitamente en SKILL.md o el campo compatibility en lugar de suponer 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 skill 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 analizarla
git diff "${BASE}...${HEAD}" --stat --name-only \
  | jq -Rs '{
      "changed_files": split("\n") | map(select(length > 0))
    }' \
  || { printf '{"error":"git diff failed"}\n' >&2; exit 1; }

Tres cosas hacen que esto sea seguro para el agente. set -euo pipefail asegura que el script salga con estrépito ante cualquier fallo en lugar de continuar silenciosamente. JSON en stdout le da al agente un formato que puede analizar sin adivinar. Los diagnósticos van a stderr para que el flujo de stdout del agente permanezca limpio. Nada de esto es astuto. Todo es necesario.

Una trampa sutil es allowed-tools. En la especificación es experimental y el soporte varía. En Claude Code preaprueba herramientas específicas mientras la Skill está activa, pero no restringe el universo de herramientas invocables, y las reglas de denegación siguen perteneciendo a los permisos de Claude Code. En el SDK de Claude Agent, Anthropic dice explícitamente que el frontmatter allowed-tools en SKILL.md no se aplica, por lo que las aplicaciones del SDK deben aplicar el acceso a herramientas en la configuración principal allowed_tools o allowedTools. Si ignoras esa diferencia, tu Skill se comportará de manera diferente en la CLI y en la automatización impulsada por SDK.

Un patrón avanzado más vale la pena robar. Cuando un flujo de trabajo inundaría tu hilo principal con registros, búsquedas de archivos o salidas de investigación largas, Claude Code permite que una Skill 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 la base de código, ese es un diseño mucho mejor que una Skill en línea gigante que ensucia la sesión principal.

Una Skill bifurcada se ve así en el frontmatter:

---
name: explore-codebase
description: Exploración profunda de una base de código no familiar. Úsalo al incorporarse a un nuevo repositorio, auditar la 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 solo la exploración puede consumir miles de tokens.

Pruebas de Claude Skills: activaciones, corrección y comparaciones de línea base

Una Skill no se prueba porque una demostración de caso feliz funcionó una vez. La guía de Anthropic divide las pruebas en tres capas: pruebas manuales en Claude.ai, pruebas con scripts en Claude Code y pruebas programáticas a través de la API de Skills. Las áreas de evaluación recomendadas son la activación, la corrección funcional y el rendimiento frente a una línea base sin la Skill. Esa también es la mejor respuesta a la pregunta de la FAQ “¿Cómo pruebas si una skill es confiable?”. Pruebas la selección de ruta, la calidad de la salida y la eficiencia, no solo si el modelo sonó confiado.

La guía oficial de evaluación da una estructura limpia para los 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 almacenan esos en evals/evals.json dentro del directorio de la Skill, lo cual es una convención sensata aunque crees 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 este PR en busca de problemas de seguridad y pruebas faltantes",
      "expected_output": "Hallazgos agrupados por severidad con referencias a archivos y al menos una recomendación de prueba.",
      "files": ["evals/files/pr-diff.patch"]
    },
    {
      "id": 2,
      "prompt": "Resume los commits de la semana pasada",
      "expected_output": "La skill no debería activarse.",
      "files": []
    }
  ]
}

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

Si pruebas a través del SDK de Claude Agent, recuerda la plomería. Las Skills son artefactos del 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 Skill. Anthropic incluso recomienda preguntar “¿Qué Skills están disponibles?” como una comprobación directa de descubrimiento.

También prueba en el modelo y el cliente que realmente pretendes desplegar. El inicio rápido abierto de Agent Skills 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 Skill pretende. Eso no es siempre un problema de diseño de la Skill. A veces es un problema de selección de modelo, y tu matriz de pruebas debería exponerlo.

Solución de problemas de Claude Skills: fallos comunes y correcciones

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

• Si la Skill no se encuentra en absoluto, verifica que el archivo se nombre exactamente SKILL.md, con la capitalización correcta, dentro del directorio correcto. La guía de solución de problemas de Anthropic señala explícitamente la capitalización 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 comprobaciones.
• Si el frontmatter es inválido, primero revisa los delimitadores y comillas del YAML. Los ejemplos de Anthropic muestran los errores clásicos: falta de ---, comillas sin cerrar o nombres inválidos con espacios y mayúsculas. Los nombres de las Skills deben ser minúsculas y con guiones.
• Si la Skill 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 Skill aparece cuando preguntas “¿Qué skills están disponibles?” e intentar reformular más cerca de la descripción. La guía en PDF de Anthropic añade un gran truco de diagnóstico: pregunta a Claude cuándo usaría la Skill y escucha cómo parafrasea la descripción de vuelta a ti.
• Si la Skill se activa demasiado a menudo, estrecha el alcance. Anthropic recomienda hacer la descripción más específica, agregar activadores negativos y usar disable-model-invocation: true para flujos de trabajo que quieres solo por comando explícito. La sobre-activación suele ser solo lenguaje de enrutamiento sub-especificado.
• Si la Skill parece perder influencia en sesiones largas, recuerda que las descripciones pueden acortarse en el catálogo de Claude Code cuando hay muchas skills presentes, y las Skills invocadas se llevan luego dentro de los presupuestos de tokens después de la compactación. Anthropic recomienda colocar las palabras clave al principio de la descripción, recortar el texto excesivo y, para Claude Code específicamente, ajustar SLASH_COMMAND_TOOL_CHAR_BUDGET si las listas de descripciones se están comprimiendo demasiado agresivamente.
• Si un script integrado se cuelga o se comporta erráticamente, verifica si espera entrada interactiva. La guía de scripts dice que los agentes se ejecutan en shells no interactivos, por lo que los prompts de TTY, los diálogos de contraseña y los menús de confirmación son errores de diseño. Acepta la entrada a través de flags, variables de entorno o stdin y haz que los fallos sean explícitos.
• Si el SDK no ve tu Skill, confirma que allowed_tools incluye "Skill", que settingSources o setting_sources contiene user y/o project, y que cwd apunta al directorio que realmente contiene .claude/skills/. Sin esa configuración, el sistema de Skills no está habilitado sin importar cuán correcto se vea tu markdown.
• Si una Skill respaldada por MCP se carga pero las llamadas a la herramienta 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 alcances, prueba la herramienta MCP directamente sin la Skill 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 Claude Skills se parecen a una buena ingeniería operativa. Nombres claros. Archivos pequeños. Activadores explícitos. Scripts deterministas donde sea necesario. Pruebas reales. Si tu Skill se lee como un runbook nítido, el agente tiene una oportunidad de lucha. Si se lee como una lluvia de ideas, simplemente has escondido el caos en una carpeta.