Tool Integrations22 de septiembre de 2026Flatkey Team

Cómo usar Claude Code con cualquier modelo: configuración de SKILL.md

Instala SKILL.md de Flatkey en Claude Code, descubre IDs de modelos en vivo, ejecuta pruebas de humo seguras y sabe cuándo usar variables de entorno del gateway.

Claude Code puede volverse mucho más útil cuando sabe cómo funciona tu capa de enrutamiento de IA. La configuración de SKILL.md es la forma limpia de enseñarle ese flujo de trabajo: dónde reside el router de Flatkey, cómo descubrir IDs de modelos en vivo, cómo llamar a modelos y herramientas compatibles, y qué reglas de seguridad seguir antes de gastar saldo o tocar sistemas de producción.

Hay una salvedad importante desde el principio. El propio bucle de razonamiento de Claude Code sigue ejecutándose en Claude. La documentación de la pasarela de Anthropic indica que Claude Code puede conectarse a una pasarela LLM, pero no admite enrutar el propio Claude Code a modelos que no sean de Claude a través de una pasarela. Usa esta guía para la versión práctica de Cómo usar Claude Code con cualquier modelo: configuración de SKILL.md: mantén Claude Code como tu agente de codificación y, después, dale una skill de Flatkey para que pueda descubrir y llamar cualquier modelo compatible con Flatkey o herramienta de pago desde tu proyecto cuando la tarea lo requiera.

El SKILL.md público de Flatkey está pensado para ese trabajo. Indica a los agentes que usen https://router.flatkey.ai, la URL base compatible con OpenAI https://router.flatkey.ai/v1, el catálogo de modelos en vivo, el marketplace de herramientas, llamadas iniciales pequeñas, IDs de solicitud y puertas de aprobación para escrituras, envíos, compras, eliminaciones, publicación o cambios de permisos.

Si eres nuevo en el propio router, mantén abierta la guía rápida de la API de Flatkey junto a esta guía. Si estás comparando esto con una migración de proveedor más amplia, las guías de alternativa a la API de OpenAI y flujo de trabajo de API de IA unificada explican el patrón de URL base con más detalle.

La respuesta rápida

Usa esta configuración cuando quieras que Claude Code opere Flatkey desde dentro de tu repositorio:

Crea una clave de API de Flatkey en la consola de Flatkey.
Instala la skill de Flatkey en Claude Code como ~/.claude/skills/flatkey/SKILL.md o .claude/skills/flatkey/SKILL.md.
Guarda FLATKEY_API_KEY en tu shell o en un gestor local de secretos, no en un archivo comprometido al repositorio.
Pide a Claude Code que use la skill de Flatkey, obtenga el catálogo de modelos en vivo y ejecute una llamada de verificación pequeña a través de https://router.flatkey.ai/v1.
Revisa los registros de uso de Flatkey para ver el modelo, el recuento de tokens, la latencia, el estado y el coste.

Si quieres que el tráfico de la familia Claude de Claude Code pase por Flatkey, usa la guía de Claude Code de Flatkey en lugar de la URL base /v1 compatible con OpenAI:

export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_API_KEY="$FLATKEY_API_KEY"

Esa ruta es para el enrutamiento por pasarela de Claude Code. La ruta de SKILL.md es para enseñarle a Claude Code cómo usar modelos y herramientas de Flatkey desde el proyecto.

Qué cambia SKILL.md en Claude Code

Una skill de Claude Code es un directorio con un archivo SKILL.md. Claude Code carga los metadatos de la skill al iniciarse y luego lee el contenido de la skill solo cuando la tarea coincide o cuando invocas la skill directamente. Eso hace que una skill sea un mejor lugar que CLAUDE.md para procedimientos repetibles como "descubrir modelos de Flatkey, seleccionar una ruta compatible, ejecutar una llamada pequeña y verificar los registros de uso".

Con Flatkey, la skill debe hacer que Claude Code haga cinco cosas de forma consistente:

Paso	Qué debería hacer Claude Code	Por qué importa
Leer las reglas de configuración	Cargar el `SKILL.md` de Flatkey antes de llamar al router	Evita IDs de modelo inventados, entradas de herramienta inventadas y filtraciones de secretos
Usar el catálogo en vivo	Llamar a `/v1/models` antes de seleccionar un modelo	La lista de modelos cambia, por lo que los ejemplos estáticos pueden quedar obsoletos
Mantener los secretos locales	Usar `FLATKEY_API_KEY` sin imprimirlo ni confirmarlo en git	Evita la exposición de credenciales en el chat, los logs y git
Empezar en pequeño	Ejecutar una pequeña llamada de prueba antes de un trabajo costoso	Confirma la autenticación, la URL base, la ruta y la forma de la respuesta
Verificar el registro	Revisar Usage Logs o la salida de la solicitud después de una llamada	Da al equipo evidencia del modelo, la latencia, los tokens y el cargo

Ese es el núcleo práctico de Cómo usar Claude Code con cualquier modelo: configuración de SKILL.md. Claude Code sigue siendo el orquestador. Flatkey se convierte en la capa de modelo y herramientas con la que puede operar de forma deliberada.

Paso 1: Elige una instalación personal o de proyecto

Instala la skill globalmente si quieres que esté disponible en todos los repositorios:

mkdir -p ~/.claude/skills/flatkey
curl -fsSL https://flatkey.ai/SKILL.md \
  -o ~/.claude/skills/flatkey/SKILL.md

Instálala dentro de un repositorio si quieres que el equipo comparta el mismo flujo de trabajo de Flatkey:

mkdir -p .claude/skills/flatkey
curl -fsSL https://flatkey.ai/SKILL.md \
  -o .claude/skills/flatkey/SKILL.md

Para una skill de proyecto compartida, revisa el archivo antes de confirmarlo:

sed -n '1,200p' .claude/skills/flatkey/SKILL.md

No conviertas el comando de instalación en un script de shell que se ejecute automáticamente. Una skill es contenido de instrucciones. Trátala como añadir cualquier otro procedimiento de desarrollo a tu repositorio: recógelo, revísalo y confírmalo solo si el equipo está de acuerdo.

Paso 2: Configura la clave de Flatkey de forma segura

Usa una variable de entorno:

export FLATKEY_API_KEY="sk-fk-your-key"

Si necesitas que la variable persista, ponla en el perfil de tu shell, en tu gestor de secretos o en un archivo de entorno local que esté ignorado por git. No coloques la clave en .claude/settings.json, CLAUDE.md, un SKILL.md confirmado en git o un prompt que pegues en un hilo compartido.

La propia regla de la skill de Flatkey es simple: usa un FLATKEY_API_KEY existente cuando ya haya uno configurado, y nunca imprimas, registres, confirmes ni envíes esa clave a ningún lugar excepto router.flatkey.ai o la consola autenticada de Flatkey.

Paso 3: Confirma que Claude Code ve la skill

Inicia Claude Code desde el repositorio o terminal donde la skill esté disponible:

claude

Luego comprueba las skills disponibles:

/skills

Deberías ver flatkey en la lista de habilidades. Si instalaste la habilidad durante una sesión de Claude Code en curso y no aparece, reinicia Claude Code. Claude Code puede detectar muchas ediciones de habilidades durante una sesión, pero reiniciarlo es la forma más sencilla de eliminar la ambigüedad durante la configuración.

Ahora pide una primera tarea inocua:

Usa la habilidad flatkey. Verifica que FLATKEY_API_KEY está disponible sin mostrarlo, obtén el catálogo de modelos en vivo de Flatkey y resume los primeros cinco IDs de modelos capaces de texto que veas. No ejecutes todavía una generación.

Esto prueba el descubrimiento sin gastar presupuesto de generación.

Paso 4: Obtén el catálogo de modelos en vivo

La habilidad Flatkey le indica a Claude Code que obtenga el catálogo de modelos en vivo antes de seleccionar un modelo. El comando directo es:

curl -fsS https://router.flatkey.ai/v1/models \
  -H "Authorization: Bearer $FLATKEY_API_KEY"

Para un flujo de trabajo real, pide a Claude Code que elija solo entre los IDs devueltos:

Usa la habilidad flatkey. Obtén el catálogo de modelos en vivo, elige un modelo de texto de bajo costo devuelto por el catálogo para una prueba rápida de una sola frase y explica por qué lo elegiste antes de ejecutar la solicitud.

Esto evita un error común del agente: usar un nombre de modelo de memoria o de un artículo antiguo. El catálogo es la fuente de verdad sobre lo que tu clave puede llamar en ese momento.

Paso 5: Ejecuta una llamada pequeña de prueba compatible con OpenAI

Una vez que el catálogo devuelva resultados, ejecuta una pequeña solicitud a través de la API compatible con OpenAI de Flatkey:

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "replace-with-a-model-id-from-the-live-catalog",
    "messages": [
      {
        "role": "user",
        "content": "Responde con una frase: la prueba de Flatkey se completó correctamente."
      }
    ],
    "max_tokens": 40
  }'

Mantén la primera llamada simple. Estás comprobando autenticación, ID de modelo, URL base, forma de la respuesta y visibilidad en el registro. Guarda los prompts de contexto largo, las llamadas a herramientas, la generación de imágenes y los trabajos por lotes hasta que funcione la ruta básica.

Paso 6: Deja que Claude Code llame a cualquier modelo compatible desde una tarea

Después de que la prueba rápida se complete correctamente, puedes pedirle a Claude Code que enrute el trabajo a un modelo que se ajuste a la tarea.

Por ejemplo:

Usa la habilidad flatkey. Necesito una revisión por un segundo modelo de esta función. Obtén el catálogo en vivo, selecciona un modelo capaz de programar devuelto por el catálogo, ejecuta una solicitud pequeña de revisión a través de Flatkey e informa el ID del modelo, el resultado de la solicitud y cualquier ID de solicitud o campos de uso devueltos. No muestres secretos.

Usa la habilidad flatkey. Compara dos modelos de texto compatibles con Flatkey en este prompt. Mantén ambas llamadas por debajo de 200 tokens de salida. Muestra las respuestas una al lado de la otra y dime cuál debería usar para esta tarea interna de resumen de bajo riesgo.

Ese es el patrón de "cualquier modelo" que funciona bien con Claude Code: Claude Code coordina la tarea, lee archivos, aplica el contexto del repositorio y usa Flatkey como una ruta externa controlada para modelos cuando un segundo modelo o una familia de modelos diferente es útil.

Para la elección de modelos en producción, combina esto con la guía del catálogo de modelos de IA para que Claude Code revise el tipo de endpoint, el precio por unidad, la disponibilidad y el estado de verificación antes de recomendar una ruta.

Paso 7: usar las herramientas de Flatkey solo después de inspeccionarlas

El SKILL.md de Flatkey también cubre herramientas de medición. La regla importante es que Claude Code debe inspeccionar una herramienta antes de ejecutarla. No debe inventar IDs de herramientas, campos obligatorios, precios, nombres de proveedores ni unidades de facturación.

Un buen primer prompt es:

Usa la skill de flatkey. Abre el marketplace de herramientas de Flatkey en el navegador, inspecciona las herramientas relacionadas con búsquedas disponibles para mi cuenta y resume los campos obligatorios y la unidad de facturación de una herramienta candidata. No ejecutes la herramienta todavía.

Luego, cuando estés listo:

Usa la skill de flatkey. Ejecuta la herramienta inspeccionada con un límite pequeño y una clave de idempotencia. Antes de ejecutar, repite la herramienta exacta, los campos obligatorios, la unidad de facturación esperada y el presupuesto máximo para mi aprobación.

Esto mantiene a Claude Code útil sin permitir que un agente derive hacia llamadas de pago descontroladas.

Paso 8: enruta el tráfico de Claude de Claude Code a través de Flatkey cuando sea necesario

La configuración de SKILL.md no es lo mismo que enrutar Claude Code en sí a través de una pasarela. Si tu objetivo es ejecutar las solicitudes de la familia Claude de Claude Code a través de Flatkey, configura Claude Code como un cliente de pasarela con formato Anthropic:

export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_API_KEY="$FLATKEY_API_KEY"

No uses una ruta final /v1 para este camino. Claude Code y el SDK de Anthropic añaden la ruta requerida. Después de establecer las variables, inicia Claude Code desde la misma shell y ejecuta:

/status

Busca la base URL de Anthropic y la fuente de credenciales. Luego envía un prompt breve y revisa los registros de uso de Flatkey. Si la base URL no aparece, Claude Code no recibió la variable de entorno.

Usa este camino cuando quieras que el uso de Claude por parte de Claude Code se refleje en el saldo y el libro mayor de Flatkey. Usa el camino de skill cuando quieras que Claude Code llame a modelos y herramientas compatibles con Flatkey desde tu repositorio.

Para decisiones de enrutamiento relacionadas, consulta Claude vs GPT API routing. Si tu caso de uso es un agente que llama a herramientas externas, la lista de verificación de Gemini API para agentes de IA es útil incluso cuando cambia la familia de modelos, porque los controles son similares: IDs exactos de modelos, reintentos limitados, validación de herramientas y revisión del uso.

Errores comunes

Error 1: asumir que SKILL.md cambia el cerebro de Claude Code

No lo hace. Una skill le da a Claude Code instrucciones y procedimientos reutilizables. No convierte el propio bucle de agente de Claude Code en GPT, Gemini, DeepSeek, Qwen u otro modelo.

Error 2: usar `/v1` con `ANTHROPIC_BASE_URL`

La URL base compatible con OpenAI de Flatkey es:

https://router.flatkey.ai/v1

El enrutamiento de gateway de Claude Code usa:

https://router.flatkey.ai

Mantenlas separadas.

Error 3: confirmar credenciales en la configuración de Claude

El proyecto .claude/settings.json normalmente se comparte con el repositorio. No pongas claves ahí. Usa exports de shell, un vault o .claude/settings.local.json solo si tu repositorio lo ignora y tu equipo acepta ese flujo de trabajo local.

Error 4: dejar que el agente adivine los IDs de modelo

Obtén siempre primero /v1/models. Si un ID de modelo no está en la respuesta del catálogo en vivo para tu clave, no lo uses.

Error 5: ejecutar herramientas de pago antes de inspeccionarlas

Para Flatkey Tools, inspecciona primero los campos requeridos, los ejemplos, la unidad de facturación y el precio exacto. Luego usa una clave de idempotencia y pide aprobación antes de ejecutar.

Una lista de verificación de configuración que puedes copiar

Usa esta lista de verificación para una sola máquina de desarrollador:

# 1. Instala la skill de Flatkey para Claude Code
mkdir -p ~/.claude/skills/flatkey
curl -fsSL https://flatkey.ai/SKILL.md \
  -o ~/.claude/skills/flatkey/SKILL.md

# 2. Revísala
sed -n '1,200p' ~/.claude/skills/flatkey/SKILL.md

# 3. Exporta tu clave de Flatkey
export FLATKEY_API_KEY="sk-fk-your-key"

# 4. Inicia Claude Code
claude

Luego, escribe:

Use the flatkey skill. Confirm the Flatkey skill is loaded, verify that FLATKEY_API_KEY is available without printing it, fetch the live model catalog, and run one tiny chat-completions smoke test through https://router.flatkey.ai/v1 using a model ID returned by the catalog.

Después de la llamada, abre Flatkey Usage Logs y confirma que la solicitud aparece con el modelo esperado, el estado, los recuentos de tokens, la latencia y el coste.

FAQ

¿Puede Claude Code usar cualquier modelo a través de SKILL.md?

Claude Code en sí mismo sigue ejecutándose sobre Claude. La configuración de SKILL.md permite que Claude Code descubra y llame a modelos y herramientas compatibles con Flatkey desde tu proyecto, de modo que una tarea puede usar otros modelos a través de la API de Flatkey cuando sea apropiado.

¿Es lo mismo que cambiar `ANTHROPIC_BASE_URL`?

No. ANTHROPIC_BASE_URL=https://router.flatkey.ai enruta el tráfico de Claude de Claude Code a través de un gateway. Instalar https://flatkey.ai/SKILL.md enseña a Claude Code cómo operar las APIs y herramientas de Flatkey durante una tarea.

¿Debería instalar la skill de Flatkey globalmente o en el repositorio?

Usa ~/.claude/skills/flatkey/ para uso personal entre proyectos. Usa .claude/skills/flatkey/ cuando el repositorio deba incluir un flujo de trabajo compartido del equipo. Confirma solo el archivo de skill revisado, nunca una credencial.

¿Por qué la guía obtiene primero `/v1/models`?

Porque la disponibilidad de modelos cambia. El catálogo en vivo de Flatkey es más seguro que un nombre de modelo copiado de la memoria, una respuesta de chat o un documento antiguo.

¿Qué debo verificar después de la configuración?

Verifica tres cosas: que Claude Code vea la skill, que la solicitud al catálogo de Flatkey se complete correctamente y que Usage Logs muestre la solicitud de prueba con modelo, estado, tokens, latencia y coste.

Referencias oficiales

Flatkey SKILL.md: https://flatkey.ai/SKILL.md
Flatkey quickstart: https://docs.flatkey.ai/quickstart.md
Guía de Flatkey para Claude Code: https://docs.flatkey.ai/guides/claude-code.md
Guía de Flatkey para el SDK de OpenAI: https://docs.flatkey.ai/guides/openai-sdk.md
Skills de Claude Code de Anthropic: https://code.claude.com/docs/en/skills
Documentación del gateway de Claude Code de Anthropic: https://docs.anthropic.com/en/docs/claude-code/llm-gateway.md
Guía de conexión del gateway de Anthropic: https://docs.anthropic.com/en/docs/claude-code/llm-gateway-connect.md
Resumen de Agent Skills de Anthropic: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview