SimpleEnglish, un Agent Skill que obliga a redactar documentación técnica en inglés simplificado ASD-STE100

 (github.com/AminBlg)
2 puntos por GN⁺ 3 시간 전 | 1 comentarios | Compartir por WhatsApp
  • SimpleEnglish es un Agent Skill que hace que los LLM redacten documentos técnicos breves y sin ambigüedades, ajustados al lenguaje controlado ASD-STE100 usado en el sector aeroespacial desde 1983
  • Aplica 53 reglas como límite de longitud de las oraciones, voz activa, tiempos simples, condiciones antes que instrucciones y una sola instrucción por oración; además, sirve para documentación, mensajes de error, runbooks, reportes de incidentes, notas de lanzamiento, prompts y preparación para traducción
  • En una evaluación de 96 ejecuciones que comparó 6 modelos de Claude y 8 tareas en dos condiciones, las violaciones de STE por cada 100 palabras bajaron en promedio 72.9%, y también se redujeron los tokens de salida en todos los modelos
  • Se puede instalar sin dependencias en Claude Code, Cursor, VS Code Copilot, OpenAI Codex, Gemini CLI y otros entornos compatibles con el estándar Agent Skills; en entornos no compatibles, se puede aplicar con un prompt del sistema o instrucciones del usuario
  • El resultado no es una certificación oficial de ASD y no se aplica a marketing, blogs ni estilo de marca. El modo básico combina reglas estructurales con vocabulario del dominio, y el modo estricto requiere el estándar oficial para validar palabras

El problema que resuelve el proyecto

  • SimpleEnglish es un Agent Skill que convierte frases exageradas y ambiguas de los LLM en redacción técnica más cercana a ASD-STE100 Simplified Technical English
  • ASD-STE100 es un lenguaje controlado usado en el sector aeroespacial desde 1983 para evitar que un técnico cansado interprete mal una instrucción
  • La diferencia entre el texto original generado por Claude y el resultado con el Skill está en la especificidad y la posibilidad de ejecución
    • La frase “aprovecha una arquitectura robusta para sincronizar sin fricción” se cambia por una explicación de que copia una tabla de Postgres a S3 y necesita un archivo de configuración
    • Un mensaje genérico de fallo de conexión se cambia por un error de contraseña del usuario app y la acción de corregir DB_PASSWORD
    • Una frase de incidente que decía que usuarios no especificados pudieron verse afectados se cambia por la hora del fallo, 12% de solicitudes fallidas, la causa del despliegue y la hora del rollback
  • Hay comparaciones adicionales de README, mensajes de error, reportes de incidentes y notas de lanzamiento en examples/before-after.md

Instalación y entornos compatibles

  • Funciona en unos 25 harnesses, incluidos Claude Code, Cursor, VS Code Copilot, OpenAI Codex, Gemini CLI, Goose y OpenCode, que son compatibles con el estándar Agent Skills
  • El proyecto está compuesto por una sola carpeta, no tiene dependencias externas y usa licencia MIT
  • El comando de instalación es el siguiente
npx skills add AminBlg/SimpleEnglish
  • skills CLI detecta los agentes instalados y coloca el Skill en el destino que el usuario elija
  • Antes de instalarlo, se puede probar con el siguiente comando
npx skills use AminBlg/SimpleEnglish@simple-english
  • En entornos que no admiten SKILL.md, se puede usar prompts/system-prompt.md como prompt del sistema, AGENTS.md o .cursorrules
    • También ofrece una versión de unas 60 tokens para entornos con presupuestos de tokens pequeños
    • Se puede usar al pedir redacción técnica o al indicar “rewrite this with simple-english”

Uso en entornos sin terminal

  • Claude.ai de pago admite Skills de forma nativa
    • Guardar SKILL.md
    • Activar la ejecución de código en Settings → Capabilities
    • Subir el archivo en Settings → Customize → Skills → Upload
    • Al activar el Skill, se aplicará a las solicitudes de redacción técnica
  • ChatGPT no admite Skills, así que se usa la versión en prompt
    • Poner el bloque de prompts/system-prompt.md en Settings → Personalization → Custom Instructions, en un Project o en las instrucciones de un Custom GPT
  • En Gemini, crear un Gem y pegar el mismo prompt en las instrucciones
  • En otros chatbots, adjuntar el archivo de prompt o pegar su contenido e indicar que se aplique a toda la salida

Reglas de redacción tomadas de ASD-STE100

  • El Skill aplica a la documentación técnica 53 reglas en 9 secciones creadas en 1983
  • Las reglas principales son las siguientes
    • Limita las instrucciones a 20 palabras como máximo y las oraciones descriptivas a 25
    • Usa una sola acepción por palabra en todo el documento para evitar mezclar expresiones como check, verify, confirm y validate
    • Usa solo tiempos simples y escribe de forma directa quién actualizó qué, en vez de usar frases como “has been updated”
    • No usa formas verbales en -ing ni cláusulas accesorias asociadas
    • Usa voz activa para eliminar expresiones indirectas como “it should be noted that”
    • Prohíbe should, would, may y might, pero permite can, will y must
    • Coloca la condición antes de la instrucción para evitar que el usuario la lea demasiado tarde
    • Pone una sola instrucción por oración
    • Conserva los artículos y that, y no convierte el texto en estilo telegráfico aunque sea breve
  • Las reglas completas de reescritura, incluidos ejemplos de software, están en SKILL.md
  • Como el marketing queda fuera del alcance de STE, no aplica las reglas a frases de marketing del README, y el Skill solo se usa para redacción documental

Alcance fuera de la documentación técnica

  • use-cases.md ofrece reglas adaptadas a varios formatos
    • Los mensajes de error se redactan en el orden: qué pasó, por qué pasó y qué debe hacer el usuario
    • Los runbooks se parecen a manuales de mantenimiento, así que aplican STE de forma directa
    • Los reportes de incidentes usan pasado simple para eliminar expresiones inciertas y atenuadas
    • Los cambios incompatibles en notas de lanzamiento se redactan como advertencias con la instrucción primero y el riesgo después
    • AGENTS.md y los prompts del sistema se tratan como procedimientos para lectores que no pueden hacer preguntas, por lo que se prohíbe should, que el modelo podría interpretar como opcional
    • Antes de traducir, organiza el documento en una forma más fácil de leer para personas no nativas y con menor costo de localización
  • Frases de marketing, estilo de blog y redacción de marca no están cubiertos, y el estilo plano es una característica intencional

Resultados del benchmark

  • La evaluación midió un total de 96 resultados generados al ejecutar 8 tareas de redacción con 6 modelos de Claude antes y después de aplicar el Skill
  • Las violaciones de STE por cada 100 palabras bajaron 72.9% en promedio general
    • claude-opus-4-8: bajó de 1.05 a 0.62, una mejora de 41%
    • claude-opus-4-7: bajó de 2.28 a 0.42, una mejora de 82%
    • claude-opus-4-6: bajó de 2.24 a 0.40, una mejora de 82%
    • claude-opus-4-5: bajó de 2.55 a 0.57, una mejora de 78%
    • claude-sonnet-5: bajó de 2.67 a 0.53, una mejora de 80%
    • claude-sonnet-4-6: bajó de 2.06 a 0.52, una mejora de 75%
  • En todos los modelos, bajó la cantidad de tokens de salida, y la longitud media de las oraciones se redujo de 11.2 a 9.7 palabras
  • Se usó un linter determinista con expresiones regulares que aplicó las mismas reglas en ambas condiciones, y el método completo junto con sus límites está en evals/results/RESULTS.md
  • Se puede reproducir con el siguiente comando si solo se tiene Claude Code CLI con sesión iniciada
python3 evals/run_bench.py

Cómo valida las reglas

  • El Skill no se hizo a partir de resúmenes de blog, sino con un enfoque guiado por pruebas basado en el texto original de Issue 9 de 2025
  • El agente base sin el Skill escribía oraciones de 40 palabras e incluso inventaba números de reglas que no existen
    • En un resultado, citó la regla de oraciones cortas como “Rule 3.1”, pero la Rule 3.1 real trata sobre formas verbales
  • A diferencia de algunas fuentes secundarias, el PDF oficial sí permite can y will
  • Después de registrar cada fallo del baseline, se escribió el Skill para bloquearlos uno por uno y se volvió a probar hasta que el agente los superó; los escenarios y resultados están en evals/pressure-tests.md

Límites de aplicación y estado del estándar

  • El resultado no es documentación certificada STE
    • ASD no certifica ninguna herramienta
    • El modo básico combina reglas estructurales con el vocabulario de dominio del usuario
    • El modo estricto se acerca más al estándar, pero para validar palabra por palabra se necesita el estándar oficial
  • El resultado se redacta de forma plana y difícil de malinterpretar, como un manual de Airbus, y está diseñado para dejar el estilo con personalidad para otros usos como blogs
  • A diferencia de una instrucción subjetiva como “escribe con claridad”, una especificación verificable como “escribe oraciones de 20 palabras o menos” sí puede ser seguida por un agente
  • ASD-STE100 es un estándar de más de 40 años, pero sigue manteniéndose y actualizándose hasta Issue 9 de enero de 2025; además, tiene numeración y se puede probar

Licencia y estatus no oficial

  • Todo el repositorio se distribuye bajo licencia MIT
  • Reexpresa las reglas con fines educativos y no copia el texto de la especificación oficial ni el contenido del diccionario
  • No es un proyecto afiliado ni aprobado por ASD o STEMG, y ASD-STE100 es una marca registrada de ASD

Lecturas relacionadas

1 comentarios

 
GN⁺ 3 시간 전
Comentarios de Hacker News

  • Incluso con solo anteponer a un ejemplo la frase “reescríbelo en inglés técnico simplificado ASD-STE100”, salen resultados bastante decentes. Parece que bastarían una o dos líneas de instrucciones; si ASD-STE100 muy probablemente ya está incluido en los datos de entrenamiento, me pregunto por qué haría falta una skill tan grande

    • Entiendo la expectativa de que el modelo use por sí solo lo que sabe del preentrenamiento, pero parece que en las fases finales de entrenamiento los datos de preentrenamiento se mezclan bastante

  • Hice una skill que aplica la guía de estilo de The Economist a texto generado por LLM: https://github.com/TAJD/economist-style-guide-plugin
    Produce texto con una estructura bastante buena y fácil de editar

  • Esto trata sobre el mal uso de STE y su adopción limitada: https://en.wikipedia.org/wiki/Simplified_Technical_English#M...

    • Me llamó la atención una frase del material crítico: “para escribir correctamente en STE se necesita un dominio excelente del inglés y suficiente conocimiento del tema”. Eso, con o sin STE, no es más que lo necesario para escribir buen inglés en cualquier campo
    • Los LLM son buenos para traducir, así que deberían destacar especialmente en este tipo de escritura. De hecho, lo apliqué a todos mis prompts durante la última semana y fue efectivo para quitarle relleno al estilo, y no vi para nada expresiones modificadoras redundantes excesivas

  • Me gusta la idea, pero no estoy convencido de la skill en sí. En cambio, encontré https://vale.sh y varios linters, así que pienso probarlos

    • STE ya está en los datos de entrenamiento, así que la skill es redundante y solo contamina la ventana de contexto
    • Me pregunto cómo se puede usar Vale en trabajo de documentación con LLM

  • Parece hacer demasiadas cosas, y una sola línea en el prompt del sistema funciona bastante bien: “los tokens de salida son valiosos, así que responde de forma concisa y usa inglés técnico simplificado ASD-STE100”

    • Me pregunto si de verdad sigue funcionando bien de forma consistente. Incluso agregando reglas al perfil del usuario y a CLAUDE.md, el modelo al final se descarriló y llenó los docstrings y las explicaciones de jerga técnica
      Si esto sirve para volver más fácil y simple la explicación del código, estoy dispuesto a probar cualquier cosa, así que esto me genera expectativas

  • Desde el README ya se ve, irónicamente, el estilo típico de LLM intacto, con frases como “9 secciones y 53 reglas escritas en 1983 por gente que podía morir por una sola oración ambigua”. Como skill de escritura, no es una señal muy prometedora

    • Reconozco eso, pero de verdad no me gusta el estilo del README. Cosas como “este README rompe la mitad de las reglas, pero el marketing está explícitamente fuera del alcance de STE y la skill lo sabe y se mantiene dentro de la documentación”, o “rechaza texto de marketing, estilo de blog y escritura de marca, y escribe de forma deliberadamente plana”
      Cada oración además tenía emojis que en HN fueron eliminados
    • Después de usar por un tiempo un prompt normal de ASD-STE100, me gusta un poco más el inglés simplificado del agente, pero no llega a cambiar la estructura general del texto
      Las oraciones se acortan y se reducen las introducciones exageradas o los encabezados vacíos tipo diapositiva, así que la calidad mejora bastante, pero no es revolucionario ni resuelve por completo el problema
    • El README parece conciso y preciso, y al probarlo directamente funcionó bien. Es mejor que muchos README que he visto escribir a gente de mi entorno

  • Ya desde el primer ejemplo del estándar Issue 9 se contradice a sí mismo. Test es un sustantivo aprobado, pero no está aprobado como verbo, y sin embargo el ejemplo STE es “Test B is an alternative to test A”
    Si no conoces las reglas específicas de STE, es una oración claramente ambigua y lejos de ser clara. Como el sitio oficial esconde la descarga detrás de un Google Form, también dejo un enlace directo: https://www.asd-ste100.org/assets/files/ASD-STE100_ISSUE9.pd...

    • No veo qué tiene de ambiguo. Para leer el Test inicial como verbo, habría que asumir que se omitió that en “prueba que B es una alternativa a A”, pero entonces al principio sería verbo y después sustantivo, así que se rompe el paralelismo
      Además, la interpretación misma de que se le esté dando esa instrucción a alguien es muy poco probable

  • Me pregunto si la razón por la que ASD-STE100 está recibiendo tanta atención de repente es un tuit viral. Me enteré por un amigo y subí la especificación hace unos días: https://asd-web-be-prod.azurewebsites.net/media/wunhmi5y/asd...
    La copia del PDF está deshabilitada, y aun así es fácil saltarse eso, así que no entiendo por qué lo hicieron. Para bloquear palabras no permitidas, hace falta un linter tipo ruff para inglés; si no, el agente casi seguro olvidará una instrucción de una sola línea

  • Me pregunto qué efecto tienen estas instrucciones sobre la inteligencia o capacidad de razonamiento del modelo. Si cambian la salida o el proceso de pensamiento, también podrían cambiar las capacidades del modelo, sobre todo si no fue entrenado para usar este lenguaje durante el entrenamiento

    • Parece que sería mejor implementarlo como una capa de posprocesamiento en vez de darlo como instrucción

  • En https://youtu.be/uJblcC4lKYw compararon y evaluaron varias skills y prompts, incluida la skill de STE, frente a las 6 reglas de escritura de George Orwell, y en conjunto Orwell dio los mejores resultados
    Tampoco agrega muchos tokens al contexto de entrada, y al comparar un prompt en prosa con estas reglas aplicadas contra uno sin ellas, me gustó el resultado. La idea es evitar metáforas familiares, no usar una palabra larga si una corta basta, quitar cualquier palabra que pueda quitarse, usar voz activa en vez de pasiva, evitar extranjerismos, términos científicos o jerga si existe una palabra común, y romper estas reglas antes que escribir una oración bárbara

    • No sé si es porque ya leí demasiado texto de IA, pero hasta el guion de la narración del video suena como si lo hubiera escrito Claude sin aplicar ni una de esas reglas
      Hay demasiados lugares comunes y expresiones típicas de IA, como “si soy sincero, la mejora en traducción fue real pero pequeña”, “ahora viene la parte sincera”, “es la misma enfermedad, pero con síntomas distintos” y “ese brutal 3% no era una ley natural, sino una característica de Claude”