Agent Skill yang memaksa penulisan dokumen dalam bahasa Inggris teknis sederhana ASD-STE100

 (github.com/AminBlg)
2 poin oleh GN⁺ 3 jam lalu | 1 komentar | Bagikan ke WhatsApp
  • SimpleEnglish adalah Agent Skill yang membuat LLM menulis dokumen teknis yang singkat dan tidak ambigu, mengikuti bahasa terkendali ASD-STE100 yang digunakan di industri dirgantara sejak 1983
  • Menerapkan 53 aturan, seperti batas panjang kalimat, kalimat aktif, tenses sederhana, menempatkan kondisi lebih dulu, dan satu instruksi per kalimat; mendukung dokumen, pesan error, runbook, laporan insiden, catatan rilis, prompt, dan persiapan terjemahan
  • Dalam evaluasi 96 kali yang membandingkan 6 model Claude dan 8 tugas dalam dua kondisi, pelanggaran STE per 100 kata turun rata-rata 72,9%, dan token output juga berkurang di semua model
  • Dapat dipasang tanpa dependensi di Claude Code, Cursor, VS Code Copilot, OpenAI Codex, Gemini CLI, dan lingkungan lain yang mendukung standar Agent Skills; di lingkungan yang belum mendukung, dapat diterapkan sebagai system prompt atau instruksi pengguna
  • Hasilnya bukan sertifikasi resmi dari ASD dan tidak diterapkan untuk pemasaran, blog, atau gaya bahasa merek. Mode default menggabungkan aturan struktur dan kosakata domain, sedangkan penilaian kata dalam mode ketat memerlukan standar resmi

Masalah yang diselesaikan proyek ini

  • SimpleEnglish adalah Agent Skill yang mengubah kalimat LLM yang berlebihan dan ambigu menjadi kalimat teknis yang mendekati ASD-STE100 Simplified Technical English
  • ASD-STE100 adalah bahasa terkendali yang digunakan di industri dirgantara sejak 1983 agar teknisi yang lelah tidak salah menafsirkan instruksi
  • Perbedaan antara teks asli yang dibuat Claude dan hasil setelah Skill diterapkan terletak pada kekonkretan dan kemudahan eksekusi
    • Kalimat seperti “menyinkronkan secara mulus dengan memanfaatkan arsitektur yang tangguh” diubah menjadi isi yang menjelaskan bahwa tabel Postgres disalin ke S3 dan memerlukan satu file konfigurasi
    • Pesan kegagalan koneksi yang umum diubah menjadi error kata sandi untuk pengguna app dan tindakan untuk memperbaiki DB_PASSWORD
    • Frasa insiden bahwa pengguna yang tidak spesifik mungkin terdampak diubah menjadi waktu kegagalan, 12% request gagal, penyebab deployment, dan waktu rollback
  • Perbandingan tambahan untuk README, pesan error, laporan insiden, dan catatan rilis tersedia di examples/before-after.md

Instalasi dan lingkungan yang didukung

  • Berjalan di sekitar 25 harness yang mendukung standar Agent Skills, termasuk Claude Code, Cursor, VS Code Copilot, OpenAI Codex, Gemini CLI, Goose, dan OpenCode
  • Proyek ini terdiri dari satu folder, tidak memiliki dependensi eksternal, dan menggunakan lisensi MIT
  • Perintah instalasinya adalah sebagai berikut
npx skills add AminBlg/SimpleEnglish
  • skills CLI mendeteksi agen yang terpasang dan memasang Skill ke target yang dipilih pengguna
  • Sebelum instalasi, Anda dapat mencobanya dengan perintah berikut
npx skills use AminBlg/SimpleEnglish@simple-english
  • Di lingkungan yang tidak mendukung SKILL.md, prompts/system-prompt.md dapat dimasukkan ke system prompt, AGENTS.md, atau .cursorrules
    • Juga tersedia versi sekitar 60 token untuk lingkungan dengan anggaran token kecil
    • Dapat digunakan dengan meminta penulisan dokumen teknis atau memberi instruksi “rewrite this with simple-english”

Menggunakan di lingkungan tanpa terminal

  • Paket berbayar Claude.ai mendukung Skill secara native
    • Simpan SKILL.md
    • Aktifkan eksekusi kode di Settings → Capabilities
    • Unggah file di Settings → Customize → Skills → Upload
    • Jika Skill diaktifkan, Skill diterapkan pada permintaan penulisan dokumen teknis
  • ChatGPT tidak mendukung Skill, jadi gunakan versi prompt
    • Masukkan blok dari prompts/system-prompt.md ke Settings → Personalization → Custom Instructions, Project, atau instruksi Custom GPT
  • Di Gemini, buat Gem dan tempelkan prompt yang sama ke instruksinya
  • Di chatbot lain, lampirkan file prompt atau tempelkan isinya, lalu instruksikan agar diterapkan ke semua output

Aturan penulisan yang diambil dari ASD-STE100

  • Skill menerapkan 53 aturan dalam 9 bagian yang dibuat pada 1983 ke dokumen teknis
  • Aturan utamanya adalah sebagai berikut
    • Batasi instruksi maksimal 20 kata dan kalimat penjelasan maksimal 25 kata
    • Gunakan satu makna untuk satu kata di seluruh dokumen agar ekspresi seperti check, verify, confirm, dan validate tidak dicampur
    • Gunakan hanya tenses sederhana; alih-alih “has been updated”, tulis langsung siapa memperbarui apa
    • Jangan gunakan bentuk verba -ing dan klausa tambahan yang terhubung dengannya
    • Gunakan kalimat aktif untuk menghapus ekspresi tidak langsung seperti “it should be noted that”
    • Larang should, would, may, dan might, tetapi izinkan can, will, dan must
    • Tempatkan kondisi sebelum perintah agar pengguna tidak terlambat membaca kondisi
    • Masukkan hanya satu instruksi dalam satu kalimat
    • Pertahankan artikel dan that; jangan membuat kalimat bergaya telegram meski pendek
  • Aturan penulisan ulang lengkap, termasuk contoh perangkat lunak, tersedia di SKILL.md
  • Karena pemasaran berada di luar cakupan STE, aturan tidak diterapkan pada copy pemasaran di README, dan Skill juga hanya diterapkan untuk penulisan dokumen

Cakupan di luar dokumen teknis

  • use-cases.md menyediakan aturan untuk berbagai format
    • Pesan error ditulis dengan urutan apa yang terjadi, penyebabnya, dan apa yang harus dilakukan pengguna
    • Runbook mirip dengan manual pemeliharaan, sehingga STE diterapkan langsung
    • Laporan insiden menggunakan simple past untuk menghapus ekspresi yang tidak pasti dan eufemistis
    • Perubahan yang merusak kompatibilitas dalam catatan rilis disusun sebagai peringatan yang menulis perintah lebih dulu dan risiko belakangan
    • AGENTS.md dan system prompt diperlakukan sebagai prosedur untuk pembaca yang tidak dapat bertanya, dan melarang should yang dapat ditafsirkan model sebagai pilihan
    • Dokumen sebelum diterjemahkan dirapikan agar mudah dibaca non-penutur asli dan biaya lokalisasinya lebih rendah
  • Tidak diterapkan pada copy pemasaran, gaya blog, atau penulisan merek, dan gaya yang datar adalah karakteristik yang disengaja

Hasil benchmark

  • Evaluasi mengukur total 96 hasil generasi dengan menjalankan 8 tugas penulisan pada 6 model Claude, sebelum dan sesudah Skill diterapkan
  • Pelanggaran STE per 100 kata turun rata-rata 72,9% secara keseluruhan
    • claude-opus-4-8: turun dari 1,05 ke 0,62, peningkatan 41%
    • claude-opus-4-7: turun dari 2,28 ke 0,42, peningkatan 82%
    • claude-opus-4-6: turun dari 2,24 ke 0,40, peningkatan 82%
    • claude-opus-4-5: turun dari 2,55 ke 0,57, peningkatan 78%
    • claude-sonnet-5: turun dari 2,67 ke 0,53, peningkatan 80%
    • claude-sonnet-4-6: turun dari 2,06 ke 0,52, peningkatan 75%
  • Jumlah token output berkurang di semua model, dan panjang rata-rata kalimat turun dari 11,2 kata menjadi 9,7 kata
  • Menggunakan linter regex deterministik yang menerapkan aturan yang sama pada kedua kondisi; metode lengkap dan batasannya tersedia di evals/results/RESULTS.md
  • Jika Anda memiliki Claude Code CLI yang sudah login, hasil dapat direproduksi dengan perintah berikut
python3 evals/run_bench.py

Cara validasi aturan

  • Skill dibuat dengan pendekatan berbasis pengujian berdasarkan teks asli Issue 9 tahun 2025, bukan ringkasan blog
  • Agen baseline tanpa Skill menulis kalimat 40 kata dan bahkan membuat nomor aturan yang tidak ada
    • Salah satu hasil mengutip aturan kalimat pendek sebagai “Rule 3.1”, tetapi Rule 3.1 yang sebenarnya adalah aturan tentang bentuk verba
  • Berbeda dari beberapa materi sekunder, PDF resmi mengizinkan can dan will
  • Setelah Skill ditulis untuk mencegah kegagalan baseline yang tercatat satu per satu, pengujian diulang sampai agen lolos; skenario dan hasilnya tersedia di evals/pressure-tests.md

Batasan penerapan dan status standar

  • Hasilnya bukan dokumen bersertifikasi STE
    • ASD tidak mensertifikasi alat apa pun
    • Mode default menggabungkan aturan struktur dan kosakata domain pengguna
    • Mode ketat lebih mendekati standar, tetapi penilaian per kata memerlukan standar resmi
  • Hasil ditulis datar seperti manual Airbus dan sulit disalahpahami; gaya yang berkepribadian dirancang untuk tetap digunakan pada tujuan lain seperti blog
  • Berbeda dari instruksi subjektif “tulislah dengan jelas”, “tulis kalimat maksimal 20 kata” adalah spesifikasi yang dapat diverifikasi, sehingga dapat diikuti agen
  • ASD-STE100 adalah standar yang berusia lebih dari 40 tahun, tetapi terus dipelihara dan diperbarui hingga Issue 9 pada Januari 2025, memiliki nomor, dan dapat diuji

Lisensi dan status tidak resmi

  • Seluruh repositori disediakan dengan lisensi MIT
  • Aturan ditulis ulang untuk tujuan edukasi dan tidak menyalin frasa spesifikasi resmi atau isi kamus
  • Proyek ini tidak berafiliasi dengan atau disetujui oleh ASD atau STEMG, dan ASD-STE100 adalah merek dagang terdaftar milik ASD

Bacaan terkait

1 komentar

 
GN⁺ 3 jam lalu
Komentar Hacker News

  • Bahkan jika pada sebuah contoh hanya ditambahkan kalimat “tulis ulang dalam bahasa Inggris teknis sederhana ASD-STE100” di bagian depan, hasilnya sudah cukup bagus. Sepertinya satu-dua kalimat instruksi saja sudah cukup, jadi saya mempertanyakan mengapa perlu skill sebesar itu padahal ASD-STE100 kemungkinan besar sudah termasuk dalam materi pelatihan

    • Saya paham harapan bahwa model seharusnya memanfaatkan pengetahuan prapelatihan dengan sendirinya, tetapi tampaknya data prapelatihan cukup banyak tercampur pada tahap pelatihan akhir

  • Saya membuat skill yang menerapkan panduan gaya The Economist pada kalimat yang dihasilkan LLM: https://github.com/TAJD/economist-style-guide-plugin
    Ini menghasilkan tulisan yang strukturnya relatif baik dan mudah disunting

  • Ini membahas penyalahgunaan STE dan adopsi yang terbatas: https://en.wikipedia.org/wiki/Simplified_Technical_English#M...

    • Kalimat dalam materi kritik yang mengatakan “untuk menulis dengan benar dalam STE, diperlukan kemampuan bahasa Inggris yang sangat baik dan pengetahuan yang memadai tentang topik tersebut” cukup berkesan. Itu pada dasarnya hanyalah syarat untuk menulis bahasa Inggris yang baik di bidang apa pun, terlepas dari apakah memakai STE atau tidak
    • LLM pandai menerjemahkan, jadi seharusnya sangat unggul dalam jenis penulisan ini. Saya benar-benar menerapkannya ke semua prompt selama seminggu terakhir, dan ini efektif untuk menghilangkan gaya yang bertele-tele, serta saya sama sekali tidak melihat ungkapan modifikasi yang berlebihan dan berulang

  • Saya suka idenya, tetapi tidak yakin dengan skill itu sendiri. Sebagai gantinya, saya menemukan https://vale.sh dan beberapa linter, jadi saya berencana mencobanya

    • Karena STE sudah termasuk dalam data pelatihan, skill itu redundan dan hanya mengotori jendela konteks
    • Saya penasaran bagaimana Vale bisa dimanfaatkan dalam pekerjaan dokumentasi LLM

  • Rasanya ini mencoba melakukan terlalu banyak hal, padahal satu baris dalam system prompt sudah bekerja cukup baik: “token output itu berharga, jadi jawablah dengan ringkas dan gunakan bahasa Inggris teknis sederhana ASD-STE100”

    • Saya penasaran apakah ini benar-benar terus bekerja dengan baik. Bahkan setelah menambahkan aturan ke profil pengguna dan CLAUDE.md, model pada akhirnya tetap keluar jalur dan menumpahkan jargon teknis ke docstring dan penjelasan
      Saya bersedia mencoba apa pun yang bisa membuat penjelasan kode jadi lebih mudah dan sederhana, jadi ini juga terlihat menjanjikan

  • Ironisnya, bahkan sejak README sudah terasa kuat gaya khas LLM, seperti “9 bagian, 53 aturan yang ditulis pada 1983 oleh orang-orang yang pembacanya bisa mati karena satu kalimat ambigu”. Sebagai skill menulis, ini bukan pertanda yang terlalu menjanjikan

    • Saya mengakui itu, tetapi saya benar-benar tidak suka gaya README-nya. Misalnya, “README ini melanggar setengah aturan, tetapi pemasaran secara eksplisit berada di luar cakupan STE, dan skill ini tahu untuk tetap berada dalam dokumentasi”, atau “Menolak slogan pemasaran, gaya blog, dan penulisan merek, serta sengaja ditulis datar”
      Setiap kalimat juga disertai emoji yang dihapus di HN
    • Setelah beberapa waktu memakai prompt ASD-STE100 biasa, saya sedikit lebih menyukai bahasa Inggris sederhana dari agen, tetapi itu tidak sampai mengubah struktur keseluruhan tulisan
      Kalimat menjadi lebih pendek, pembukaan yang berlebihan atau judul bagian kosong seperti presentasi berkurang, sehingga kualitasnya cukup membaik, tetapi tidak revolusioner dan tidak sepenuhnya menyelesaikan masalah
    • README itu tampak ringkas dan akurat, dan saat saya mencobanya langsung, hasilnya bekerja dengan baik. Itu lebih baik daripada README yang ditulis banyak orang yang saya lihat di sekitar saya

  • Dari contoh pertama di Issue 9 standar itu sendiri sudah kontradiktif. Test disetujui sebagai nomina, tetapi tidak disetujui sebagai verba, sementara contoh STE-nya adalah “Test B is an alternative to test A”
    Tanpa mengetahui aturan khusus STE, ini jelas kalimat ambigu dan jauh dari jelas. Karena situs resminya menyembunyikan unduhan di balik Google Form, saya juga meninggalkan tautan yang bisa diunduh langsung: https://www.asd-ste100.org/assets/files/ASD-STE100_ISSUE9.pd...

    • Saya tidak tahu bagian mana yang ambigu. Agar Test pertama dibaca sebagai verba, Anda harus menganggap that dihilangkan dari “uji bahwa B adalah alternatif dari A”, dan Test di depan menjadi verba sementara yang belakang menjadi nomina, sehingga paralelismenya rusak
      Selain itu, penafsiran sebagai instruksi agar seseorang melakukan tindakan seperti itu sendiri sangat kecil kemungkinannya

  • Saya penasaran apakah alasan ASD-STE100 tiba-tiba mendapat perhatian adalah karena cuitan viral. Saya mendengarnya dari seorang teman dan mengunggah spesifikasinya beberapa hari lalu: https://asd-web-be-prod.azurewebsites.net/media/wunhmi5y/asd...
    Penyalinan PDF-nya dilarang, tetapi mudah dilewati, jadi saya heran mengapa mereka melakukannya. Untuk memblokir kata yang tidak diizinkan, dibutuhkan linter seperti ruff untuk bahasa Inggris; kalau tidak, agen hampir pasti akan melupakan instruksi satu baris itu

  • Saya penasaran pengaruh instruksi seperti ini terhadap kecerdasan atau kemampuan berpikir model. Jika itu mengubah output atau proses berpikir, kemampuan model juga bisa berubah, terutama jika selama pelatihan model tidak dilatih menggunakan bahasa seperti ini

    • Rasanya ini sebaiknya diimplementasikan sebagai lapisan pascapemrosesan alih-alih diberikan sebagai instruksi

  • Dalam https://youtu.be/uJblcC4lKYw, berbagai skill dan prompt termasuk skill STE dibandingkan dan dievaluasi dengan 6 aturan menulis George Orwell, dan secara keseluruhan Orwell memberikan hasil terbaik
    Jumlah token tambahan yang masuk ke konteks input juga tidak banyak, dan ketika saya membandingkan prompt prosa yang menerapkan aturan ini dengan yang tidak, saya menyukai hasilnya. Isinya adalah menghindari metafora yang sudah terlalu akrab, tidak memakai kata panjang jika kata pendek sudah cukup, membuang kata yang bisa dibuang, memakai kalimat aktif alih-alih pasif, menghindari kata asing atau istilah ilmiah serta jargon jika ada padanan sehari-hari, dan melanggar aturan-aturan ini daripada menulis kalimat yang biadab

    • Mungkin karena saya sudah terlalu banyak membaca tulisan AI, tetapi naskah narasi video itu juga terdengar seperti ditulis Claude tanpa menerapkan satu pun aturan tersebut
      Ada terlalu banyak klise dan ungkapan khas AI seperti “sejujurnya, peningkatan terjemahannya nyata tetapi kecil”, “sekarang bagian yang jujur”, “penyakitnya sama tetapi gejalanya berbeda”, dan “angka 3% yang brutal itu bukan hukum alam, melainkan sifat Claude”