Agent Skill que impõe a escrita de documentos em inglês técnico simplificado ASD-STE100

 (github.com/AminBlg)
2 pontos por GN⁺ 2 시간 전 | 1 comentários | Compartilhar no WhatsApp
  • SimpleEnglish é um Agent Skill que faz LLMs escreverem documentos técnicos curtos e sem ambiguidade, seguindo a linguagem controlada ASD-STE100, usada no setor aeroespacial desde 1983
  • Aplica 53 regras, como limite de tamanho de frases, voz ativa, tempos verbais simples, condições antes das instruções e uma instrução por frase, e oferece suporte a documentos, mensagens de erro, runbooks, relatórios de incidentes, notas de lançamento, prompts e preparação para tradução
  • Em 96 avaliações que compararam 6 modelos Claude e 8 tarefas em duas condições, as violações de STE caíram em média 72,9% por 100 palavras, e todos os modelos também reduziram os tokens de saída
  • Pode ser instalado sem dependências em Claude Code, Cursor, VS Code Copilot, OpenAI Codex, Gemini CLI e outros que suportam o padrão Agent Skills; em ambientes sem suporte, pode ser aplicado como prompt de sistema ou instruções do usuário
  • Os resultados não são uma certificação oficial da ASD e não se aplicam a marketing, blogs ou estilo de marca. O modo padrão combina regras estruturais e vocabulário de domínio, e o modo estrito exige o padrão oficial para julgar palavras

Problema que o projeto resolve

  • SimpleEnglish é um Agent Skill que transforma frases exageradas e ambíguas de LLMs em frases técnicas mais próximas do ASD-STE100 Simplified Technical English
  • O ASD-STE100 é uma linguagem controlada usada no setor aeroespacial desde 1983 para que um técnico de manutenção cansado não interprete instruções incorretamente
  • A diferença entre o texto original gerado pelo Claude e o resultado com o Skill está na especificidade e na possibilidade de execução
    • Transforma “sincroniza de forma contínua usando uma arquitetura robusta” em uma explicação de que uma tabela Postgres é copiada para o S3 e que um arquivo de configuração é necessário
    • Transforma uma mensagem genérica de falha de conexão em um erro de senha do usuário app e na ação de corrigir DB_PASSWORD
    • Transforma uma frase de incidente sobre possível impacto a usuários indeterminados em horário da falha, 12% de falhas nas requisições, causa no deploy e horário do rollback
  • Comparações adicionais de README, mensagens de erro, relatórios de incidentes e notas de lançamento estão em examples/before-after.md

Instalação e ambientes compatíveis

  • Funciona em cerca de 25 harnesses que suportam o padrão Agent Skills, como Claude Code, Cursor, VS Code Copilot, OpenAI Codex, Gemini CLI, Goose e OpenCode
  • O projeto é composto por uma única pasta, não tem dependências externas e usa a licença MIT
  • O comando de instalação é:
npx skills add AminBlg/SimpleEnglish
  • O skills CLI detecta agentes instalados e instala o Skill no destino escolhido pelo usuário
  • Antes da instalação, é possível testar com este comando:
npx skills use AminBlg/SimpleEnglish@simple-english
  • Em ambientes que não suportam SKILL.md, é possível colocar prompts/system-prompt.md no prompt de sistema, em AGENTS.md ou em .cursorrules
    • Também é oferecida uma versão de cerca de 60 tokens para ambientes com orçamento de tokens pequeno
    • É possível usar solicitando a escrita de documentação técnica ou instruindo “rewrite this with simple-english”

Uso em ambientes sem terminal

  • Planos pagos do Claude.ai têm suporte nativo a Skills
    • Salve SKILL.md
    • Ative a execução de código em Settings → Capabilities
    • Envie o arquivo em Settings → Customize → Skills → Upload
    • Ao ativar o Skill, ele será aplicado a solicitações de escrita de documentação técnica
  • ChatGPT não suporta Skills, portanto usa a versão em prompt
    • Coloque o bloco de prompts/system-prompt.md em Settings → Personalization → Custom Instructions, em um Project ou nas instruções de um Custom GPT
  • No Gemini, crie um Gem e cole o mesmo prompt nas instruções
  • Em outros chatbots, anexe o arquivo de prompt ou cole o conteúdo e instrua o bot a aplicá-lo a todas as saídas

Regras de escrita trazidas do ASD-STE100

  • O Skill aplica a documentos técnicos 53 regras em 9 seções, criadas em 1983
  • As regras principais são:
    • Limita instruções a no máximo 20 palavras e explicações a no máximo 25 palavras
    • Usa uma só palavra com um só significado em todo o documento, evitando a mistura de expressões como check, verify, confirm e validate
    • Usa apenas tempos verbais simples, escrevendo diretamente quem atualizou o quê em vez de “has been updated”
    • Não usa formas verbais em -ing nem orações adicionais ligadas a elas
    • Usa voz ativa e remove expressões indiretas como “it should be noted that”
    • Proíbe should, would, may e might, mas permite can, will e must
    • Coloca condições antes de comandos para impedir que o usuário leia a condição tarde demais
    • Coloca apenas uma instrução em cada frase
    • Mantém artigos e that, e não cria frases telegráficas mesmo que sejam curtas
  • As regras completas de reescrita, incluindo exemplos de software, estão em SKILL.md
  • Como marketing fica fora do escopo de STE, as regras não são aplicadas ao texto de marketing do README, e o Skill também se aplica apenas à escrita de documentação

Escopo além de documentação técnica

  • use-cases.md oferece regras adaptadas a vários formatos
    • Mensagens de erro são escritas na ordem: o que aconteceu, a causa e o que o usuário deve fazer
    • Runbooks são semelhantes a manuais de manutenção, portanto aplicam STE diretamente
    • Relatórios de incidentes usam passado simples para remover expressões incertas e eufemísticas
    • Mudanças incompatíveis em notas de lançamento são estruturadas como alertas que colocam o comando primeiro e o risco depois
    • AGENTS.md e prompts de sistema são tratados como procedimentos para leitores que não podem fazer perguntas, e proíbem should, que o modelo pode interpretar como opcional
    • Antes da tradução, documentos são organizados em uma forma mais fácil de ler para não nativos e com menor custo de localização
  • Não se aplica a textos de marketing, estilo de blog ou escrita de marca, e o estilo plano é uma característica intencional

Resultados do benchmark

  • A avaliação executou 8 tarefas de escrita em 6 modelos Claude, antes e depois da aplicação do Skill, medindo um total de 96 resultados gerados
  • As violações de STE por 100 palavras caíram 72,9% na média geral
    • claude-opus-4-8: caiu de 1,05 para 0,62, uma melhoria de 41%
    • claude-opus-4-7: caiu de 2,28 para 0,42, uma melhoria de 82%
    • claude-opus-4-6: caiu de 2,24 para 0,40, uma melhoria de 82%
    • claude-opus-4-5: caiu de 2,55 para 0,57, uma melhoria de 78%
    • claude-sonnet-5: caiu de 2,67 para 0,53, uma melhoria de 80%
    • claude-sonnet-4-6: caiu de 2,06 para 0,52, uma melhoria de 75%
  • Em todos os modelos, a contagem de tokens de saída diminuiu, e o tamanho médio das frases caiu de 11,2 para 9,7 palavras
  • Foi usado um linter determinístico baseado em regex que aplica as mesmas regras às duas condições; a metodologia completa e suas limitações estão em evals/results/RESULTS.md
  • É possível reproduzir com o comando abaixo se você tiver apenas a CLI do Claude Code com login:
python3 evals/run_bench.py

Como as regras são verificadas

  • O Skill foi criado de forma guiada por testes com base no texto original da Issue 9 de 2025, não em um resumo de blog
  • Um agente de referência sem o Skill escreveu frases de 40 palavras e até criou números de regras inexistentes
    • Um resultado citou a regra de frases curtas como “Rule 3.1”, mas a Rule 3.1 real trata de formas verbais
  • Ao contrário de alguns materiais secundários, o PDF oficial permite can e will
  • Depois de escrever o Skill para bloquear cada falha de referência registrada, ele foi testado novamente até o agente passar; os cenários e resultados estão em evals/pressure-tests.md

Limites de aplicação e status do padrão

  • O resultado não é um documento certificado em STE
    • A ASD não certifica nenhuma ferramenta
    • O modo padrão combina regras estruturais com o vocabulário de domínio do usuário
    • O modo estrito se aproxima mais do padrão, mas a avaliação palavra por palavra exige o padrão oficial
  • O resultado é escrito de forma plana e difícil de interpretar mal, como um manual da Airbus, e foi projetado para deixar o estilo com personalidade para outros usos, como blogs
  • Ao contrário de uma instrução subjetiva como “escreva com clareza”, “escreva frases com 20 palavras ou menos” é uma especificação verificável, que um agente consegue seguir
  • O ASD-STE100 é um padrão com mais de 40 anos, mas foi mantido e atualizado até a Issue 9 de janeiro de 2025, tem numeração e pode ser testado

Licença e status não oficial

  • Todo o repositório é oferecido sob a licença MIT
  • As regras são reescritas para fins educacionais, sem reproduzir o texto da especificação oficial nem o conteúdo do dicionário
  • O projeto não é afiliado nem aprovado pela ASD ou pelo STEMG, e ASD-STE100 é uma marca registrada da ASD

Leituras relacionadas

1 comentários

 
GN⁺ 2 시간 전
Comentários no Hacker News

  • Mesmo em um exemplo, basta colocar na frente a frase “reescreva em inglês técnico simplificado ASD-STE100” para sair um resultado suficientemente bom. Se uma ou duas frases de instrução bastam, fica a dúvida de por que é necessária uma skill enorme, ainda mais quando ASD-STE100 provavelmente já está incluído no material de treinamento

    • Entendo a expectativa de que o modelo use sozinho o conhecimento de pré-treinamento, mas parece que, nas etapas finais de treinamento, os dados de pré-treinamento acabam bastante embaralhados

  • Criei uma skill que aplica o guia de estilo da The Economist a textos gerados por LLM: https://github.com/TAJD/economist-style-guide-plugin
    Ela produz textos com estrutura relativamente boa e fáceis de editar

  • Isto fala sobre uso indevido do STE e adoção limitada: https://en.wikipedia.org/wiki/Simplified_Technical_English#M...

    • A frase do material crítico “para escrever corretamente em STE é preciso excelente domínio do inglês e conhecimento suficiente sobre o tema” chamou atenção. Isso é apenas uma condição necessária para boa escrita em inglês em qualquer área, independentemente de usar STE ou não
    • Como LLMs traduzem bem, deveriam ser especialmente boas nesse tipo de escrita. De fato, ao aplicar isso a todos os prompts durante a última semana, foi eficaz para remover excessos de estilo, e também não vi nenhuma expressão modificadora redundante

  • Gosto da ideia, mas não estou convencido da skill em si. Em vez disso, descobri https://vale.sh e vários linters, então pretendo testar

    • Como o STE já está incluído nos dados de treinamento, a skill é redundante e só polui a janela de contexto
    • Tenho curiosidade sobre como usar o Vale em trabalho de documentação com LLM

  • Parece fazer coisas demais, e uma linha no prompt do sistema já funciona bem o bastante: “tokens de saída são valiosos, então responda de forma concisa e use inglês técnico simplificado ASD-STE100”

    • Fico curioso se isso realmente continua funcionando bem. Mesmo adicionando regras ao perfil do usuário e ao CLAUDE.md, o modelo acabou saindo dos trilhos e despejando jargão técnico em docstrings e explicações
      Se isso for uma forma de tornar explicações de código mais fáceis e simples, estou disposto a tentar qualquer coisa, então isso também me anima

  • É irônico que, já no README, apareça intacto o estilo típico de LLM tipo “9 seções e 53 regras escritas em 1983 por pessoas que podem morrer por causa de uma frase ambígua”. Como skill de escrita, isso não é um sinal muito promissor

    • Reconheço isso, mas realmente não gosto do estilo do README. Coisas como “este README viola metade das regras, mas marketing está explicitamente fora do escopo do STE, e a skill sabe disso e permanece na documentação” e “recusa copy de marketing, estilo de blog e escrita de marca, e escreve de forma deliberadamente plana”
      Cada frase também vinha com emojis que foram removidos no HN
    • Usei por um tempo um prompt comum de ASD-STE100, e gosto um pouco mais do inglês simplificado do agente, mas isso não muda a estrutura geral do texto
      As frases ficam mais curtas e há menos introduções exageradas ou títulos de seção vazios como em slides de apresentação, então a qualidade melhora bastante, mas não é revolucionário nem resolve o problema por completo
    • O README parece conciso e preciso, e ao testar por conta própria funcionou bem. É melhor do que muitos READMEs escritos por pessoas que já vi por aí

  • O primeiro exemplo do Issue 9 do padrão já é autocontraditório. Test é um substantivo aprovado, mas não é aprovado como verbo, e mesmo assim o exemplo em STE é “Test B is an alternative to test A”
    Sem conhecer as regras específicas do STE, isso é claramente uma frase ambígua e está longe de ser clara. Como o site oficial esconde o download atrás de um Google Form, também deixo um link direto: https://www.asd-ste100.org/assets/files/ASD-STE100_ISSUE9.pd...

    • Não sei o que haveria de ambíguo. Para ler o primeiro Test como verbo, seria preciso assumir que em “teste se B é uma alternativa a A” o that foi omitido, mas aí no começo seria verbo e depois substantivo, então o paralelismo se quebra
      Além disso, a própria interpretação como uma instrução para alguém fazer essa ação é muito pouco provável

  • Fico curioso se o motivo de ASD-STE100 estar recebendo tanta atenção de repente é um tuíte viral. Ouvi falar por um amigo e publiquei a especificação alguns dias atrás: https://asd-web-be-prod.azurewebsites.net/media/wunhmi5y/asd...
    A cópia do PDF está bloqueada, mas é fácil contornar isso, então não entendo por que fizeram assim. Para bloquear palavras não permitidas, seria preciso um linter para inglês tipo ruff; caso contrário, o agente quase certamente vai esquecer uma instrução de uma linha

  • Fico curioso sobre que efeito essas instruções têm na inteligência ou capacidade de raciocínio do modelo. Se elas mudam a saída ou o processo de pensamento, também podem mudar a capacidade do modelo, especialmente se ele não foi treinado para usar esse tipo de linguagem durante o treinamento

    • Parece que isso deveria ser implementado como uma camada de pós-processamento, em vez de ser dado como instrução

  • Em https://youtu.be/uJblcC4lKYw foi feita uma comparação entre várias skills/prompts, incluindo a skill de STE, e as 6 regras de escrita de George Orwell, e no geral Orwell deu os melhores resultados
    Também não adiciona muitos tokens ao contexto de entrada, e ao comparar um prompt de prosa com essas regras aplicadas com outro sem elas, gostei do resultado. A ideia é evitar metáforas familiares, não usar palavra longa quando uma curta basta, cortar palavras que possam ser removidas, usar voz ativa em vez de passiva, evitar termos estrangeiros, científicos ou jargão quando houver palavra comum, e quebrar essas regras antes de escrever algo bárbaro

    • Talvez seja porque li texto demais escrito por IA, mas até o roteiro da narração do vídeo soa como se tivesse sido escrito pelo Claude sem aplicar nenhuma dessas regras
      Há clichês e expressões típicas de IA demais, como “para ser honesto, a melhora na tradução foi real, mas pequena”, “agora vem a parte honesta”, “é a mesma doença, mas com sintomas diferentes” e “esse brutal índice de 3% não era uma lei da natureza, mas uma característica do Claude”