CommunityRedacción y edicióngithub.com

explicar

Explica un problema o una arquitectura como una cadena causal en las propias palabras del usuario, utilizando términos precisos y adjuntando cada afirmación con su razón.

¿Qué es explicar?

El skill 'explicar' transforma preguntas técnicas complejas en cadenas causales claras y legibles, redactadas en los términos que el usuario ya utiliza. Se activa cuando el usuario pregunta 'por qué' o 'cómo' funciona algo, cuando un error no se comprende, o cuando se necesita entender la arquitectura de un sistema. El flujo de trabajo consta de tres pasos: primero, recopila mensajes previos del usuario para identificar su vocabulario y lagunas de conocimiento; segundo, escribe una breve explicación que comienza por el problema, une cada afirmación con su causa mediante conectores como 'porque' o 'ya que', y se detiene al alcanzar un punto que el usuario ya conoce; y tercero, señala y corrige cualquier error de terminología o suposición incorrecta frente al código real. Está diseñado para Claude Code y similares, manteniendo un tono de prosa hablada (sin tablas ni listas internas) que sobrevive a la conversión texto-a-voz, y que facilita que el usuario entienda exactamente la mecánica subyacente.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NG-Bullseye/explain-skill/tree/main/skills/explain

Installed? Explore more Redacción y edición skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Una explicación aquí es una cadena causal en las palabras del usuario: unas pocas oraciones cortas en las que cada afirmación lleva su razón, construida a partir de los términos que el usuario ya usa, leída de una sola vez, en voz alta si es necesario.

1. Recopilar las palabras del usuario

La explicación se engancha a lo que el usuario sabe, y lo que sabe se ve en las palabras que escribe. Antes de explicar un tema por primera vez en una sesión, lee cómo lo ha tratado:

python3 <carpeta_del_skill>/user_words.py <palabra_clave> [<palabra_clave> ...]
python3 <carpeta_del_skill>/user_words.py --all-projects <palabra_clave> ...

Esto imprime los mensajes que el usuario escribió en sesiones anteriores de Claude que contienen la palabra clave, primero los más recientes, para el proyecto actual o para todos. Elige palabras clave de su pregunta y del tema (nombres de componentes, herramientas, lo que falla). Añade sus mensajes de la conversación actual.

De aquí, anota tres cosas:

  • sus términos: la palabra que usa para cada cosa ("segundo camino SSH", "IP entrante", "proxied"). Úsalos exactamente, incluso si el código o la documentación los llaman de otra forma.
  • terreno conocido: lo que ha afirmado o usado correctamente. Una cadena puede terminar allí.
  • lagunas: términos del tema que nunca ha usado. Cada uno es una palabra nueva.

Terminado cuando cada término que la explicación necesita está clasificado como su término o palabra nueva.

2. Escribir la cadena

  1. Problema primero. La primera oración nombra el problema o la respuesta misma: "El problema es X." Cuando el usuario ha hecho una pregunta directa ("¿para qué sirve la contraseña?"), la primera oración responde exactamente esa pregunta.
  2. Cada afirmación lleva su razón. Adjunta la razón en la misma oración con porque / ya que / mediante. Un efecto expresado solo es un eslabón suelto: "todas las conexiones vienen de 127.0.0.1" no explica nada hasta que "fail2ban bloquea por IP" está al lado.
  3. Encadenar hasta terreno conocido. Sigue los porqués hasta que el último sea terreno conocido para el usuario. Detente allí.
  4. Sus términos, el mecanismo mismo. Expresa el mecanismo real literalmente, en sus términos. Analogías, imágenes y metáforas inventadas quedan fuera.
  5. Palabras nuevas entre paréntesis. Una palabra nueva aparece una vez con palabras clave entre paréntesis justo detrás, luego sola: "HostKeyAlias (opción SSH: verifica la clave del host contra otra entrada en known_hosts)". Palabras clave, no una oración completa.
  6. Prosa hablada. De tres a cinco oraciones declarativas cortas, un eslabón por oración, en orden de causa a efecto. Texto corrido que sobrevive a la conversión texto-a-voz: sin encabezados, tablas ni listas con viñetas dentro de la explicación.

Para arquitectura, la cadena recorre el camino de una petición o un cambio: qué parte actúa, qué entrega a la siguiente, por qué la siguiente puede o no puede cumplir su función con eso.

3. Nombrar las correcciones

Las palabras y suposiciones del usuario se cotejan con el código y los hechos, y cada desviación se nombra — después de la cadena, una línea cada una, como "dices … / lo correcto es … , porque …":

  • palabras que el código no respalda: dice "Passkey", es una entrada del llavero; dice "El Runner se cae", el runner es un contenedor y Docker falla. Dale el nombre que usa el código o la herramienta, para que su siguiente pregunta y su siguiente búsqueda acierten.
  • suposición errónea: algo que da por sentado que no es así ("la contraseña la necesito para la conexión"). Di qué ocurre en su lugar y su porque.

Verifica contra el código o el sistema antes de corregir; una corrección de memoria es una suposición. Sigue usando su término después solo allí donde era correcto.

Modelo

La redacción propia que debería haber recibido un usuario (por qué fail2ban no protege SSH detrás de un túnel de Cloudflare). Los ejemplos aquí están en alemán; explica en el idioma en que escribe el usuario.

El problema es el segundo camino SSH por contraseña. Con el nombre de usuario y la contraseña del Mac, cualquiera puede hacer una conexión por fuerza bruta. fail2ban no protege, porque es bloqueo por IP y a través del túnel todos tienen la misma IP entrante, ya que Cloudflare hace proxy.

Terminado cuando

Antes de enviar, revisa cada oración:

  • la primera oración nombra el problema o responde la pregunta formulada;
  • cada afirmación tiene su porqué en la misma oración;
  • el último porqué es terreno conocido para este usuario;
  • cada término es su término, o una palabra nueva con su paréntesis;
  • cada palabra incorrecta y suposición errónea en su pregunta está nombrada con su corrección.

Cuando el usuario aún no entienda, encuentra el eslabón cuyo porqué falta y añade solo ese eslabón, en una oración. Los valores concretos (dos IPs, una petición) entran solo allí, para cerrar ese eslabón.

Qué hacer a continuación (opciones, comandos, una recomendación) sigue después de la explicación, separado de ella, y solo cuando se pida o sea necesario para actuar.

Skills relacionados