Revisa un archivo de recetario de Mistral AI

Revisa un archivo de recetario de Mistral AI para verificar la calidad del contenido, la integridad estructural y el estilo de escritura. Produce una lista priorizada de problemas y soluciones sugeridas.

Cuándo usar esta habilidad

Actívala cuando el usuario pida:

• Revisar, auditar o corregir un archivo de recetario
• Verificar si un recetario sigue el formato estándar
• Obtener retroalimentación sobre un borrador de recetario
• Validar un recetario antes de fusionarlo

Cómo realizar una revisión

1. Lee el archivo objetivo completo usando la herramienta de lectura.
2. Evalúalo según la Lista de verificación de estructura y la Lista de verificación de estilo de escritura a continuación.
3. Genera una revisión estructurada en el formato especificado al final de este documento.

Plantilla de estructura de recetario

Secciones requeridas (deben estar presentes)

Cada archivo de recetario debe incluir estas secciones, en este orden:

# [Title]                          ← H1: concise, task-oriented
[One-sentence description]         ← immediately under title, no heading
> [Status/note callout]            ← blockquote for beta APIs or important constraints

[Introduction text]                ← optional ## Introduction heading, or prose directly under the description

## Prerequisites                   ← H2: "To complete this cookbook, you will need:" + bullet list only

## Environment setup               ← H2

### Install                        ← H3

### Required environment variables ← H3

## [Step heading]                  ← H2: one or more step sections (numbered or unnumbered)
...

## Clean up                        ← H2 (optional but suggested): remove resources created during the tutorial

## Summary                         ← H2: closing summary (required, must be last)

Los encabezados de los pasos son H2 y pueden estar numerados o sin numerar; ambas formas son aceptables:

• ## 1. Create the connector
• ## Create the connector

Cada sección de paso debe comenzar con al menos una oración antes de cualquier bloque de código, tabla o lista (consulta el estándar de contenido de la sección a continuación).

La sección ## Prerequisites debe contener solo la oración "Para completar este recetario, necesitarás:" seguida de una lista con viñetas. Los elementos de la lista deben aparecer en este orden:

1. Tiempo de ejecución y herramientas del lenguaje (por ejemplo, "Python 3.9 o posterior", "Node.js y un gestor de paquetes")
2. Una cuenta de Mistral y una clave de API (casi siempre requeridas)
3. Cualquier otra cuenta, token o servicio externo necesario

Marca como Crítico si ## Prerequisites contiene instrucciones de instalación, configuración de variables de entorno o bloques de código; eso pertenece a ## Environment setup.

La sección ## Environment setup contiene todo lo que el lector necesita para ejecutar el código: instalación de paquetes, configuración de la clave de API y (para scripts independientes) un comando de ejecución. Consulta el estándar de configuración de la clave de API a continuación para la redacción exacta.

La sección ## Summary debe ser la última sección del archivo; ningún contenido, encabezado o sección puede seguirla. Debe contener:

1. Resumen de 1 a 2 oraciones de lo que cubrió el recetario y lo que se construyó o demostró.
2. Lo que construiste (o Lo que cubre este recetario) — una lista con viñetas.
3. Funciones de Mistral utilizadas — una lista con viñetas de las API, productos y herramientas de Mistral a los que se hace referencia (por ejemplo, Connectors, Conversations API, Agents API, Workflows, Chat Completions API, herramientas integradas).
4. Otros servicios (opcional) — una lista con viñetas de herramientas de terceros o servidores MCP utilizados. Omite este encabezado si no hay ninguno.
5. Una CTA — un solo enlace a la documentación relevante o a una página de Studio. Usa uno de:
   • Una URL de Studio conocida (por ejemplo, View your Connectors in [Studio](https://console.mistral.ai/build/connectors).)
   • Una URL de documentación conocida
   • Si no conoces el destino correcto, usa: [View the documentation]() <!-- TODO: add link to relevant documentation -->

Marca como Crítico si la sección ## Summary falta por completo o si no es la última sección del archivo. Marca como Moderado si el enlace de CTA está vacío y no tiene un comentario TODO, o si falta alguno de los cuatro elementos requeridos (resumen, lo que se construyó, funciones de Mistral, CTA).

Secciones opcionales (incluir cuando sea relevante)

Estándar de contenido de sección

Cada encabezado —en cualquier nivel— debe ir seguido de al menos una oración de texto antes de cualquier bloque de código, tabla o lista. La oración debe decirle al lector qué está viendo o qué hacer.

Marca como Moderado si cualquier encabezado es seguido inmediatamente por un bloque de código, tabla o lista sin una oración introductoria.

Ejemplos:

### Install — debe tener una oración introductoria antes del primer bloque de código:

• TypeScript: "Usa uno de los siguientes métodos para instalar el SDK de Mistral TypeScript:"
• Python: "Instala el SDK de Mistral Python:" o "Ejecuta el siguiente comando para instalar el SDK de Mistral Python:"

### Run — debe explicar qué hace el comando antes de mostrarlo:

• "Una vez que tu archivo .env esté en su lugar, ejecuta el script:"

Aplica la misma regla a todos los demás encabezados: ### Required environment variables, encabezados de recetas, encabezados de pasos, etc.

Estándar de configuración de clave de API

Cada recetario que requiera una clave de API de Mistral debe seguir esta redacción y estructura exactas. Marca cualquier desviación como un problema Crítico.

Obteniendo la clave

La sección "Configuración del entorno" debe incluir esta oración base (enlaces de Markdown intactos):

Para completar este recetario, necesitarás una clave de API de Mistral. En Studio, navega a la sección de claves de API y crea una nueva clave de API.

Algunos tutoriales requieren contexto adicional dentro de esta oración, por ejemplo, especificando un ámbito de clave de API. Esto está permitido siempre que se conserven los enlaces base, el nombre de Studio y la estructura general:

Para completar este recetario, necesitarás una clave de API de Mistral. En Studio, navega a la sección de claves de API, elige Private and shared connectors para Connector access scope y crea una nueva clave de API.

Marca estos como Críticos y sugiere la oración estándar:

• Cualquier otra URL para crear una clave de API (por ejemplo, /api-keys, /dashboard, o un enlace console.mistral.ai simple sin el enlace profundo del diálogo de perfil)
• Fraseología que omite el enlace de Studio por completo
• Usar "Mistral AI dashboard", "Mistral Console" o cualquier otro nombre que no sea "Studio" para la consola

Archivo .env (recetarios de Markdown y proyectos de Python)

Cuando el proyecto usa un archivo .env, las instrucciones deben usar esta redacción y formato exactos:

Crea un archivo .env en la raíz de tu proyecto y agrega tu clave de API de Mistral:

MISTRAL_API_KEY=your-mistral-api-key

Si el proyecto requiere claves de API adicionales (por ejemplo, un token de GitHub o una clave de servicio de terceros), lista MISTRAL_API_KEY primero y cualquier clave específica del proyecto debajo:

MISTRAL_API_KEY=your-mistral-api-key
OTHER_SERVICE_API_KEY=your-other-api-key

Marca estos como Críticos:

• Valores entre comillas: MISTRAL_API_KEY="your-key" → elimina las comillas
• Nombre de variable incorrecto: MISTRAL_KEY → debe ser MISTRAL_API_KEY
• Etiqueta de idioma del bloque de código faltante en el contenido .env — usa un bloque cercado simple (sin etiqueta de idioma) para archivos env
• Instrucciones que dicen "establece una variable de entorno" sin mostrar el patrón de archivo .env

Marca como Moderado:

• Instrucciones .env colocadas fuera de la sección de Prerrequisitos

Celda de clave de API de Notebook (.ipynb)

Los notebooks de Jupyter deben usar el siguiente patrón para la clave de API. Primero verifica una variable de entorno existente y, si no la encuentra, recurre a un prompt seguro getpass para que los lectores puedan ingresar su clave directamente en el notebook sin configurar un archivo .env:

import getpass
import os

if not os.environ.get("MISTRAL_API_KEY"):
    os.environ["MISTRAL_API_KEY"] = getpass.getpass("Mistral API key: ")

Luego, el cliente se inicializa con os.environ["MISTRAL_API_KEY"]. getpass es parte de la biblioteca estándar de Python, no se necesita ninguna dependencia adicional. El prompt se enmascara como un campo de contraseña y funciona en Jupyter, Colab y Kaggle.

La sección ## Environment setup del notebook debe explicar ambas opciones:

1. Establece MISTRAL_API_KEY como una variable de entorno antes de ejecutar (para uso local)
2. Déjala sin establecer e ingresa la clave cuando la celda anterior te lo solicite

Marca estos como Críticos:

• Cadenas de clave de API codificadas en cualquier celda
• MISTRAL_KEY en lugar de MISTRAL_API_KEY
• Usar os.getenv("MISTRAL_API_KEY") sin un respaldo — prefiere os.environ["MISTRAL_API_KEY"] o el patrón getpass para que el notebook falle ruidosamente si falta la clave

Marca como Moderado:

• api_key = os.environ["MISTRAL_API_KEY"] definido pero nunca pasado al constructor del cliente

Recetarios de Shell / curl

Los recetarios que se basan principalmente en curl (sin tiempo de ejecución de Python) pueden usar exportaciones de shell en lugar de un archivo .env:

export MISTRAL_API_KEY="your-api-key"

Esto es aceptable para ejemplos solo de curl. No marques este patrón como un error. Aún marca el nombre de variable incorrecto (MISTRAL_KEY) o una instrucción de clave de API faltante.

Secciones a excluir

No incluyas estas en un recetario:

• Lenguaje de marketing — Nada de "la potente IA de Mistral" o "capacidades de vanguardia".
• Introducciones genéricas — Nada de "En el mundo actual de la IA..." o "A medida que la IA se vuelve más importante...".
• Declaraciones promocionales de cierre — Nada de "¡Empieza a construir hoy mismo!" o "Desbloquea todo el potencial".
• Secciones solo teóricas sin código — Los conceptos deben ir acompañados de un ejemplo concreto.
• Prerrequisitos repetidos — Indica las instrucciones de instalación una vez; no las repitas en los pasos individuales.
• Tabla de Contenidos — La interfaz de usuario de la documentación no renderiza los enlaces de la TOC, por lo que añaden ruido sin beneficio. Elimina cualquier sección ## Table of Contents por completo.
• Duplicación de TOC anidada — No listes los subpasos de la receta en una tabla de contenidos.
• Secciones vacías — Elimina cualquier encabezado sin contenido debajo.
• Historial de cambios o versiones — Pertenece a las notas de la versión, no a los recetarios.
• Pautas de contribución — Usa el archivo CONTRIBUTING_GUIDE.md del repositorio en su lugar.

Lista de verificación de estilo de escritura

Basado en la Guía de estilo de escritura de Mistral (consulta los archivos de referencia a continuación).

Voz y tono

• Sé directo. Comienza con lo que el lector necesita hacer o saber. Elimina los preámbulos.
  • Mal: "Antes de sumergirnos en el uso de conectores, vale la pena entender qué son."
  • Bien: "Los conectores permiten que el modelo llame a herramientas externas a través de MCP."
• Escribe como hablas. Usa contracciones (es, harás, no). Evita la fraseología rígida y formal.
  • Mal: "Es necesario asegurar que el cliente esté inicializado."
  • Bien: "Inicializa el cliente antes de hacer solicitudes."
• Dirígete al lector como "tú". No uses "el usuario" o "uno" cuando te refieres a la persona que lee.
• Comienza las oraciones con un verbo. Edita "puedes" cuando no sea necesario.
  • Mal: "También puedes especificar un tiempo de espera opcional."
  • Bien: "Especifica un tiempo de espera opcional."
• Evita los inicios débiles. Reescribe las oraciones que comienzan con hay, existen o hubo.
  • Mal: "Hay dos formas de autenticarse."
  • Bien: "Dos métodos de autenticación están disponibles."

Claridad y brevedad

• Mantén las oraciones cortas. Una idea por oración. De tres a siete líneas por párrafo.
• Elimina cada palabra en exceso. Si una palabra no añade significado, elimínala.
  • Mal: "Con el fin de poder realizar una solicitud..."
  • Bien: "Para realizar una solicitud..."
• Usa palabras sencillas. Prefiere usar en lugar de utilizar, comenzar en lugar de iniciar, mostrar en lugar de visualizar.
• No uses jerga sin definirla. En el primer uso, explica brevemente los términos no obvios.
• Prioriza los encabezados y las oraciones. Pon la palabra o frase más importante primero.

Encabezados

• Usa la capitalización tipo oración. Capitaliza solo la primera palabra y los nombres propios. Para los encabezados de pasos numerados, también capitaliza la primera palabra después de la etiqueta del paso (por ejemplo, ## Step 2 — Set up the environment).
  • Mal: ## Creating A Connector With OAuth Authentication
  • Bien: ## Creating a connector with OAuth authentication
  • Bien: ## Step 3 — Craft the prompt
• No uses punto al final de los encabezados.
• No uses ampersands (&) ni signos de más (+) a menos que te refieras a una interfaz de usuario que los contenga.
• Mantén los encabezados cortos y específicos. Un encabezado debe decirle al lector exactamente lo que encontrará.
• Usa una estructura paralela en los encabezados del mismo nivel.
  • Mezcla incorrecta: ## Create a connector, ## Listing connectors, ## How to delete a connector
  • Correcto: ## Create a connector, ## List connectors, ## Delete a connector
• Evita dos encabezados seguidos sin texto de cuerpo intermedio.
• Nunca abras una sección con un bloque de código, tabla o lista. Cada encabezado debe ir seguido de al menos una oración antes de cualquier código o contenido estructurado. Consulta el estándar de contenido de la sección anterior.

Listas

• Usa listas con viñetas para elementos desordenados; listas numeradas para pasos secuenciales.
• Mantén los elementos de la lista paralelos en gramática y estructura.
• Incluye una coma antes de "y" en una serie de tres o más elementos (coma de Oxford).
  • Mal: "Python, TypeScript y curl"
  • Bien: "Python, TypeScript, y curl"
• No uses punto al final de los elementos de una lista con viñetas de una sola oración, a menos que sean oraciones completas que continúen en varias oraciones.

Puntuación

• Un espacio después de los puntos, no dos.
• Sin espacios alrededor de los guiones largos. Usa — no - para los guiones parentéticos.
• No uses dos puntos al final de los encabezados o introducciones de listas en la mayoría de los casos.
• Usa comillas rectas, no comillas rizadas/inteligentes, en el código y el contenido adyacente al código.

Código y ejemplos de código

• Cada bloque de código debe tener una etiqueta de idioma: ```python, ```typescript, ```bash.
• Nunca codifiques credenciales reales. Usa marcadores de posición como "your-api-key" o os.environ["MISTRAL_API_KEY"].
• Muestra la salida esperada. Siempre sigue un bloque de código con un ejemplo de lo que imprime o devuelve.
• Comenta con moderación. Agrega comentarios solo cuando la lógica no sea evidente por sí misma en el código. No declares lo obvio.
• Compila y prueba todo el código. Verifica que cada ejemplo se ejecute sin errores.
• Prioriza los elementos de uso frecuente. Comienza con el ejemplo útil más simple; avanza hacia lo complejo.
• Los marcadores de posición deben ser obvios. Cualquier valor que el lector deba reemplazar debe estar claramente marcado (por ejemplo, <your-connector-id> o "your-agent-id").
• Haz coincidir el idioma con el tutorial. Un tutorial de TypeScript muestra TypeScript; un notebook de Python muestra Python. No mezcles idiomas dentro del mismo tutorial a menos que el recetario los compare explícitamente.

Accesibilidad y lenguaje inclusivo

Consulta inclusive-language.md para la guía completa.

• Usa lenguaje centrado en la persona al referirte a personas con discapacidades.
  • Mal: "usuarios ciegos", "desarrolladores discapacitados"
  • Bien: "usuarios que son ciegos", "desarrolladores con discapacidades"
• Usa términos de género neutro.
  • Mal: "él", "ella", "mano de obra", "presidente"
  • Bien: "elle", "fuerza laboral", "presidencia"
• Evita los pronombres de género en referencias genéricas. Reescribe en segunda persona o usa el plural.
• Evita términos con sesgos raciales inconscientes.
  • Mal: "maestro/esclavo", "lista negra/lista blanca"
  • Bien: "primario/subordinado", "lista de permitidos/lista de denegados"
• No uses argot que pueda considerarse apropiación cultural.
• Usa la capitalización tipo título para los nombres de grupos raciales y étnicos: Negro, Blanco, Indígena, Hispano, Latinx.

Términos a evitar en el contenido del recetario

Formato de salida de la revisión

Escribe la revisión como un documento Markdown con la siguiente estructura:

## Cookbook review: [filename]

### Summary
[2–4 sentence overview of overall quality and the most critical issues]

### Critical issues
<!-- Must fix before publishing -->
- **[Issue type]** [Line or section reference]: [What's wrong and why it matters]
  - Suggested fix: [Concrete rewrite or action]

### Moderate issues
<!-- Should fix for quality -->
- **[Issue type]** [Line or section reference]: [What's wrong]
  - Suggested fix: [Concrete rewrite or action]

### Minor issues
<!-- Nice to fix, low impact -->
- **[Issue type]** [Line or section reference]: [What's wrong]
  - Suggested fix: [Concrete rewrite or action]

### What's working well
- [Positive observation]
- [Positive observation]

### Structure checklist
| Section | Status | Notes |
|---|---|---|
| H1 title | ✅ / ❌ / ⚠️ | |
| One-sentence description | ✅ / ❌ / ⚠️ | |
| Status/note callout (if applicable) | ✅ / ❌ / N/A | |
| Prerequisites (bullet list only) | ✅ / ❌ / ⚠️ | |
| Environment setup > Install | ✅ / ❌ / ⚠️ | |
| Environment setup > Environment variables | ✅ / ❌ / ⚠️ | |
| Step sections (H2, at least one) | ✅ / ❌ / ⚠️ | |
| Intro sentence before code in each step | ✅ / ❌ / ⚠️ | |
| Code blocks have language tags | ✅ / ❌ / ⚠️ | |
| Clean up section (optional) | ✅ / N/A | |
| Closing summary (last section) | ✅ / ❌ / ⚠️ | |
| No forbidden sections | ✅ / ❌ | |

Clave de estado:

• ✅ Presente y correcto
• ❌ Faltante o incorrecto (crítico)
• ⚠️ Presente pero necesita mejora
• N/A No aplicable para este recetario

Etiquetas de tipo de problema:

• [Missing section] — sección requerida ausente
• [Forbidden section] — sección que no debería existir está presente
• [Style] — violación del estilo de escritura
• [Clarity] — contenido confuso o ambiguo
• [Code] — problema de bloque de código (etiqueta faltante, credencial codificada, sin salida mostrada, etc.)
• [Structure] — problema de nivel, orden o formato de encabezado
• [Accessibility] — problema de lenguaje inclusivo o sesgo
• [Accuracy] — probable error fáctico o técnico (marcar para verificación humana)

Archivos de referencia

Estos archivos residen junto a esta habilidad y contienen la guía completa mencionada anteriormente:

• voice-and-tone.md — Voz de marca, tres principios de voz, los 10 mejores consejos de escritura con ejemplos de recetarios
• checklists.md — Listas de verificación de acrónimos, capitalización, gramática, números, procedimientos, puntuación, contenido responsivo, formato de texto y elección de palabras
• ai-terms.md — Terminología de IA preferida, términos a evitar, reglas de capitalización, descripción del comportamiento del modelo
• developer-content.md — Ejemplos de código (planificación y escritura), formato de elementos de texto para desarrolladores, estructura de documentación de referencia, escritura de procedimientos
• inclusive-language.md — Lenguaje de género neutro, términos de accesibilidad, lenguaje racial y étnico, terminología técnica sin sesgos, lenguaje militarista, ejemplos de código inclusivos