[opensourcedex]

yomiyasu is a free, open source publishing project written in Python and released under MIT. It has 1,589 GitHub stars, 36 forks and 3 open issues, and was last pushed 7 hours ago. On this registry it ranks #28 of 53 tracked projects in Publishing, with 5 head-to-head comparisons available.

What is yomiyasu?

yomiyasu is an Agent Skill that rewrites AI-generated Japanese into natural, readable prose, for writers, engineers and editors who draft technical articles, design documents, pull request descriptions and internal reports with LLMs.

What it is

yomiyasu (よみやす) is a skill designed to be loaded into AI coding and writing environments such as Codex, Claude Code, Cursor, Gemini and Antigravity. It operates inside those agent environments rather than as a standalone application, and it is written in Python under the MIT licence.

The problem it addresses is that AI-generated Japanese contains awkwardness that simple word substitution cannot fix: unnatural metaphors, vague subject-predicate relations, unnecessary decoration, and emphasis placed on formatting instead of content. The skill targets a specific set of failure modes — replacing banned words such as 手触り, 解像度 and 泥臭い with other vague terms, over-applying editing rules to sentences that were already readable, sentences where the actor and action are unclear or inanimate subjects are given human will, and documents where bolding and bullet lists substitute for actual procedures. Instead it revises the places that impose a reading burden while leaving naturally readable passages untouched.

Key capabilities

  • Checks subject and predicate, modifier attachment, and referents of demonstratives, and verifies that conditions, exceptions, negation, parallel structures, quantities and ordering remain traceable after rewriting.
  • Distinguishes the function of each sentence — explanation, request, advice, plan — and corrects only sentence endings that do not match, preserving 常体 or 敬体 unless a change is requested rather than converting everything to 敬体 because the text is a technical article.
  • Resolves metaphorical verbs such as 壊れる, 倒す, 効く and 溶かす into plainer wording while keeping the original nuance and breadth of meaning, and reorganises personification so that objectively describing a tool's behaviour is not mistaken for giving it intent.
  • Adds no information that is not in the source: no new actors, causes, conditions, numbers or emotions, and where meaning cannot be determined it returns a clearly provisional sentence together with the reason for the wording and the points needing confirmation.
  • Applies measurable targets — an average sentence length of 30 to 45 characters and 0 to 2 commas per sentence — and distinguishes unnecessary sentence-final colons from colons that label a value.
  • Adjusts punctuation and decoration: since v1.0.7 it suppresses copy-style fragments ending on a particle such as 「資料を、全員へ。」, removes unnecessary commas directly after subjects or objects, and trims redundant decoration and half-width spaces while keeping bold that renders correctly.
  • Retains evaluation, necessary contrast, transitions from comparison to policy, conditions, negation, quotations and defined technical terms rather than deleting preambles indiscriminately.

Who uses it and how

  • Technical writers and engineers applying it to technical articles, design documents and specifications, pull request descriptions, and internal reports.
  • Developers who load the skill into Codex, Claude Code or Cursor and run it against drafts those environments produce.
  • Users who verify the behaviour against a corpus, as described in the accompanying Zenn article on building the skill and validating it with corpus data.
  • Reviewers comparing before-and-after output on material such as public documents and a distributed queue design memo, checking that claims, emphasis and sentence function are preserved.

Getting started

Load the yomiyasu skill into an AI coding environment such as Codex, Claude Code or Cursor; releases are published on the project's GitHub releases page.

How it compares

No alternative or competing tools are named in the project's own materials, and it stands alone in this registry as a Japanese-language refinement skill for AI-generated prose.

When to use it — and when not

It is aimed at practical Japanese writing where meaning must survive editing, so it fits documents meant to be read closely rather than slogans or marketing copy. The skill carries no service of its own to operate, but it is only useful inside an agent environment, and the README itself notes that its saved comparison outputs are historical and should not be treated as passing examples of the current meaning-preservation rules.

project readme (upstream, from github) — read inline

yomiyasu（よみやす）

License: MIT GitHub release

これは何？

『yomiyasu（よみやす）』は、AIが生成した日本語の不自然な比喩、曖昧な主述関係、不要な装飾を直し、読みやすい文章に整えるスキルです。

主に技術記事、設計書・仕様書、PR説明文、社内レポートなどの実務的な文章を対象として設計されています。

Codex、Claude Code、CursorをはじめとするAIコーディング環境に読み込ませて使用してください。

開発の背景、AI生成文の読みにくさ、コーパスを使った検証については、次の解説記事で紹介しています。

Built with curiosity at ALGO ARTIS

ALGO ARTIS

ALGO ARTISについて

株式会社ALGO ARTISは、社会基盤の最適化に取り組むスタートアップです。

電力・海運・化学プラントといった現場では、膨大な制約が絡み合う複雑な運用計画を、今なお熟練者が手作業で組み立てています。

そうした高度な現場業務を数理モデル化し、実用的なヒューリスティック最適化アルゴリズムと業務システムを一貫して開発しています。

最適化技術を用いた社会インフラの変革に興味がある方は、公式ウェブサイトや採用情報をご覧ください。

背景と課題

AIが生成した文章には、単語を置き換えるだけでは直らない読みにくさがあります。yomiyasuでは、次の点を見直します。

  1. 禁止語の置き換えにとどまる対処
    手触りや解像度、泥臭いを別の曖昧な語へ置き換えるだけでは、何を伝えたい文か分からないままです。
  2. 編集ルールの過剰適用
    読みやすい文にも編集ルールを一律に当てると、不自然な造語や大げさな表現になる場合があります。
  3. 主述関係の曖昧さと非生物主語
    誰が何をどうするのかが曖昧な文や、道具に意志や感情を持たせた文は、読み手が意味を推測する必要があります。
  4. 形式の偏重と情報密度の低下
    太字や箇条書きで強調していても、具体的な手順や処理が説明されていなければ、内容は伝わりません。

本スキルのアプローチ

元の意味を保ち、読み違いや文の関係を追う負担がある箇所を直します。自然に読める部分は残します。

7つの変換原則

  1. 主述・修飾・条件の点検

    主語と述語、修飾語と掛かる先、指示語と指す対象を対応づけます。条件・例外・否定・並列・数量・順序も、書き直す前後で同じように追えるか確かめます。主体や対象を補うのは、原文や提供文脈から確定できる範囲に限ります。

  2. 文の働きと文体の保持

    文ごとの説明・依頼・助言・予定を区別し、働きに合わない文末だけを直します。変更指定がない常体・敬体は保ち、技術記事という分野だけで敬体へ変えません。

  3. 擬人化の整理

    道具や概念に感情や意志を持たせた表現を直します。道具やシステムの客観的な動作を述べる非生物主語は残します。

  4. 比喩を平易な言葉へ

    壊れる、倒す、効く、溶かすなどを、元の含みや意味の広さを保って言い換えます。動詞を替えた後も、主体・対象・修飾先を変えず、語順を追いやすくできるか確かめます。

  5. 前置き・否定対比の役割の確認

    前置きを削るのは、削っても主張や比重が変わらない場合だけです。評価や必要な対比、比較から方針へ移る接続は残します。

  6. 情報を勝手に足さない

    主張・比重・言い切りの強さ・文の働きを保ち、原文にない主体・原因・条件・数値・感情などを足しません。ルールを「契約」、比較の基準を「正本」と大げさに呼ぶ場合は役割に合う語へ直し、文字どおりの意味や定義済みの専門用語は保ちます。意味を確定できない箇所は、未確定と分かる暫定文を返し、書き方を選んだ理由と必要な確認事項を添えます。

  7. 文長・読点・装飾の調整

    平均文長30〜45文字、1文の読点0〜2個を目安にします。読みやすい原文の読点を、数や見た目だけで削りません。不要な文末コロンと、ラベルと値の対応を示すコロンを区別します。過剰な装飾や不要な半角空白を整理し、残す太字は正しく表示される形にします。

v1.0.7の変更

「資料を、全員へ。」のように、読点で間を置き、助詞句で終えるコピー調を抑えます。読点だけを消すのではなく、本文は分かっている動作や判断を述語まで書き、案内用の見出しは内容を見分ける短い語句に整えます。記録先や場面が役立つ場合は、「Issueに残す採用理由」のように具体的な語を残します。

主語や目的語の直後の不要な読点を整理します。進捗報告で別々の作業の完了・未完了を伝える場合は、状態ごとに文を分けます。条件や必要な逆接、引用、確認項目の名称は保ちます。

文脈が明確でない場合は余計なことを書かず、明確な場合は分かりやすく説明します。動作主が切り替わる箇所は、分かっている主体を省いて曖昧にしません。意味や実施方法が未確定なら、暫定文でもその状態を示します。

変換例と検証データ

公的文書をもとにした文章と、検証用に作成した分散キュー設計メモを題材にした、以前の比較記録です。

以下は以前の検証で保存した出力と当時の説明です。現在の版を実行した結果ではなく、現行の意味保持ルールの合格例としては扱いません。

比較例1: 業務・仕様解説

修正前のAI生成文

ここで重要なのは、単なるパーツの共通化ではなく、組織の意思決定OSとしてのガバナンスです。

従来の開発では、画面ごとに手触り感を探りながらパーツを作っていました。しかし、片方だけを見て画面を作ると、もう片方のアクセシビリティが静かに壊れます。そこでデザインシステムという強固な土台を置くことで、開発者の解像度が一段上がります。

デザインシステム導入のメリットは、主に次の3点です。

  • 開発速度の加速: コンポーネントを再利用することで、時間を溶かさずに済みます。
  • 仕様の収斂: 判断に迷うスタイルは、あらかじめ共通側に倒します。
  • アクセシビリティの担保: ガイドラインが規律を要求するため、事故を未然に防ぐことができます。

もちろん、これは「デザイナーが不要になる」ことを意味しません。日々の開発に地味に効いてきます。ぜひ参考にしてみてください！

本スキル適用後

デザインシステムを導入する目的は、ボタンや入力欄などのUIパーツを一から作成する負担を減らし、画面全体の情報設計に集中することにあります。

各コンポーネントの見た目やアクセシビリティ要件があらかじめ定義されていれば、デザイナーと開発者はコードの記述や画面遷移の実装を円滑に進められます。スタイルの指定に迷った場合でも、定義済みの標準コンポーネントを選択すれば表示の不整合を防ぐことが可能です。

導入によってデザイン作業そのものが不要になるわけではありません。しかし、単純なパーツ作成にかかる工数を削減することで、本来注力すべき使い勝手の検証や品質向上に時間を充てられるようになります。結果として、利用者が迷わず操作できる高品質な行政サービスの提供につながります。

当時の変更説明

比喩動詞（静かに壊れる、共通側に倒す、地味に効く、時間を溶かす）を直接的な操作や状態変化へ修正しました。また、手触り感、意思決定OS、解像度といった曖昧な流行語を排除し、具体的な作業内容を記述しています。不要な太字や過度な箇条書きを抑え、前後のつながりが自然な地の文へ再構築しました。

比較例2: 技術解説

修正前のAI生成文

非同期処理における最大の落とし穴は、ネットワークの瞬断です。

依存構造は分割できない。動かしながら引き返す。

単にメッセージを流すだけでは、背後でデータが静かに壊れます。前提を、経路が代わりに添えてくれるわけではありません。

そこで地味に効いてくるのが、以下の3つの原則です。

  • 冪等性の担保: 重複した処理は黙ってスキップします。
  • 安全なリトライ: 指数バックオフを挟むことで、DBの負荷を逃がします。
  • DLQへの退避: 破綻したメッセージは隔離し、原因を1つずつ潰していきます。

デバッグで丸一日時間を溶かさないためにも、この境界線を意識した設計が不可欠です。いかがでしたでしょうか。

本スキル適用後

非同期キューを用いたメッセージ処理では、通信の切断やサーバーの再起動によって処理が中断されるおそれがあります。メッセージの二重送信が発生しても不整合を起こさないよう、受信側のプログラムで冪等性を担保する設計が不可欠です。

具体的な対策として、メッセージの固有IDをデータベースに記録し、同一IDをすでに処理済みであれば追加処理を行わずに終了します。外部APIの呼び出しに失敗した場合は、待機時間を徐々に延ばしながら再試行し、規定回数を超えて失敗したデータはデッドレターキュー（DLQ）へ退避して手動調査に回す構成をとります。エラー時の復旧手順をあらかじめ決めておけば、障害発生時にも迅速な原因究明が可能です。

当時の変更説明

前提を経路が添えるや依存構造は分割できないといった主語のない抽象文を解体し、動作主と対象を明記しました。あわせて黙ってスキップ、潰していく、時間を溶かすを正確な技術用語や操作へ置き換えています。冒頭と末尾にあった不要な煽り文句や定型文（最大の落とし穴、いかがでしたでしょうか）も削除しました。

インストール

1. npx skills add（推奨）

# 新規インストール
npx skills add nanaism/yomiyasu

# 最新版へのアップデート
npx skills update yomiyasu

Claude Codeなどのエージェント設定ディレクトリへインストール・更新します（すでに導入済みの場合は npx skills update yomiyasu で最新版へ更新できます）。

2. npx openskills install（Cursor / Codexなど）

npx openskills install nanaism/yomiyasu
npx openskills sync

AGENTS.mdを経由して各エージェントから利用できるようになります。

3. Claude Code プラグイン

/plugin marketplace add nanaism/yomiyasu
/plugin install yomiyasu@yomiyasu

4. ZIPファイルからの登録（Claude.ai Web版など）

Claudeのカスタムスキル登録機能（Web版など）には、登録専用のZIPを使ってください。GitHubの「Download ZIP」で取得したリポジトリ全体のZIPには、プラグイン設定や重複ファイルも含まれ、登録できない場合があります。

登録専用のZIPには、スキル本体と必要な参照文書・検査ツールだけを含めています。

  1. 専用ZIPのダウンロード
    以下のリンクから、登録専用のZIPファイルをダウンロードします。
    yomiyasu.zip（最新版ダウンロード）
  2. そのままアップロード
    ダウンロードした yomiyasu.zip を解凍せず、Claudeのスキル登録画面にそのままアップロードしてください。

※ 手動で登録用ZIPを作る場合は、SKILL.md、references/、scripts/yomiyasu_lint.py、scripts/yomiyasu_diff.py、LICENSEを含めます。プラグイン設定や比較用の入力・出力は含めません。ZIPの内容確認と、Claudeの登録画面での動作確認は別です。

他の日本語校正スキルとの干渉について

他の日本語校正スキルと併用すると、指示が食い違う場合があります。出力が乱れる場合は、類似スキルを一時的に無効にして使用してください。

使い方

AIチャットやコーディングエージェントに対して、下書きを貼り付けて次のように指示します。

この文章を読みやすくして。
（ここに修正したい文章を貼り付け）

ドメインの指定

用途に特化した文体へ調整したい場合は、プロンプト内でドメインを指定してください。自然な文章で「技術記事向けに」と添えるか、「ドメイン tech」と明記して指示できます（省略時は入力内容から自動判別されます）。

この文章を技術記事向けに読みやすくして。
（ここに修正したい文章を貼り付け）
  • tech（技術記事）
    技術ブログやコード解説向け。手順や仕組みを復元し、箇条書きを抑えます。「技術記事向けに」または「ドメイン tech」と指定してください。
  • business（業務文書）
    仕様書やPR文、提案書向け。比喩表現を排し、境界条件や責任主体を明確にします。「業務仕様向けに」または「ドメイン business」と指定してください。
  • essay（エッセイ）
    個人ブログやnote向け。大げさな教訓化を避け、素直な感情と実感を大切にします。「エッセイ向けに」または「ドメイン essay」と伝えてください。

付属ツール

文章の表現やMarkdownの太字を検査する2つのPythonスクリプトを同梱しています。外部ライブラリは不要で、Python標準ライブラリだけで動作します。

検出結果は見直し候補です。指摘がないことだけでは、意味の保持や文章の使いやすさを保証しません。元の文や提供文脈と照合して判断してください。

1. yomiyasu_lint.py（静的検査リンター）

文章内のAIっぽさ（不自然な比喩動詞、過剰な太字・箇条書き、絵文字、文末コロン、同一文末の連続、不要な半角空白など）に加え、GitHub Flavored MarkdownやCommonMarkで日本語の括弧や句読点に隣接して太字記号（**）がそのまま露出してしまう構文崩れ（bold_not_rendered）を数値化して検査します。複数行にまたがる太字やブロック境界（引用、見出し、リスト、表）も考慮して判定します。

# Markdownファイルを検査
python3 scripts/yomiyasu_lint.py README.md

# 警告があれば終了コード1を返す厳格モード（CIやGitフック用）
python3 scripts/yomiyasu_lint.py article.md --strict

# JSON形式で結果を出力
python3 scripts/yomiyasu_lint.py article.md --json
出力例
============================================================
AIっぽさ 検査レポート (スコア: 100/100)
============================================================
・文字数: 1420 | 行数: 85
・太字頻度: 1,000字あたり 1.4 個 (推奨: 2.0以下 / 警告: 3.0超)
・箇条書き比率: 8.2% (推奨: 15%以下 / 警告: 25%超)
------------------------------------------------------------
[PASS] 設定された検査ルールによる指摘はありません。

2. yomiyasu_diff.py（推敲差分チェッカー）

推敲前と推敲後を比較し、語の増減、文末の種類や立場（勧め／決まり／説明）の変化、太字の表示を点検するツールです。意図しない意味の変化を見直すための候補を出しますが、意味が同じかどうかを自動で確定するものではありません。

# 原文と推敲後の差分を検査（文書の立場を指定）
python3 scripts/yomiyasu_diff.py 元の文.md 書き直した文.md --stance=説明

# 文末の種類（敬体・常体・立場）の分布のみを確認
python3 scripts/yomiyasu_diff.py --endings 対象文.md

リポジトリ構成

.
├── .claude-plugin/                   # Claude Code用プラグイン設定
│   ├── plugin.json
│   └── marketplace.json
├── SKILL.md                          # スキル定義エントリポイント
├── README.md                         # 本ドキュメント
├── LICENSE                           # ライセンス（MIT）
├── scripts/                          # 付属検査ツール群
│   ├── yomiyasu_lint.py             # 静的検査スクリプト（AIっぽさ・太字構文検査）
│   └── yomiyasu_diff.py             # 差分検査スクリプト（推敲前後の意味・文末比較）
├── references/                       # スキル参照ドキュメント
│   ├── gemini-syntax.md              # 構文変換原則
│   ├── slop-catalog.md               # 不自然な語彙・構文カタログ
│   └── domains/                      # ドメイン別指針（tech, business, essay）
├── skills/                           # 配布用パッケージ（エージェントインストール用コピー）
│   └── yomiyasu/
├── tests/                            # 単体テスト・回帰テストスイート
│   ├── test_bold_multiline.py        # 複数行太字・境界検査テストスイート
│   └── fixtures/                     # 回帰テスト用フィクスチャ（50ケース）
└── evals/                            # 評価データ
    └── comparison_benchmark.md       # オープンライセンス文章を用いた比較検証データ

謝辞・参考文献

開発では、社内でのLLM文章に関する議論、先行調査、学術論文、既存の文体調整ツールを参考にしました。各資料から学んだ点を紹介します。スキルの具体的な編集ルールや数値の目安は独自に決めたものであり、引用した研究がその効果を保証するものではありません。

1. コミュニティの先行調査

  • AI臭い文章とは何なのか（Speaker Deck） — nasuvitz氏
    AI特有の読みにくさは単語選び以上に統語構造（SVOCM）の破綻や非生物主語に起因するという指摘を参考にしました。「誰が何をどうした」を1文ごとに完結させる原則の策定に役立てています。
  • Qiitaの7万記事を数えてみた話 — 逆瀬川氏
    AI普及後に生じた形式のインフレ（太字や箇条書きの急増）と手順の希薄化を定量的に示した調査です。技術記事における太字頻度やリスト比率の制限、手順復元指針の根拠として活用しました。
  • Gemini 3.8 Flashこそ日本語執筆の救世主だった（X） — まつにぃ氏（@yugen_matuni）
    自然な助詞配置と主述の結びつきを持つ日本語構造に着目する契機となりました。その統語特性を分析し、プロンプト指示として定式化しています。
  • AI語に親しむ / AI語を受容する — ktrmnm氏
    AI特有の比喩動詞や直訳調の構文パターン分析を参考にしました。比喩動詞の技術的操作化や、不要な否定対比の平文化ルールに反映させています。
  • AIの作文はなぜつまらないのか？ / なぜAI臭さを消したいのか？ — laiso氏
    過剰な包装紙（前置フィラーや定型クロージング）への批評や、型を押し付けることへの注意点を参照しました。前置きの排除や、生活実感・身体性を残す方針に活かしています。

2. 日本語処理・テキスト平易化に関する学術研究

3. 先行する文体調整スキル群

4. 文章の構造を点検するための参考書籍

  • 千早耿一郎『悪文の構造――機能的な文章とは』

    公開図解と確認した本文を参考に、主語・述語・修飾先などの関係を分析し、書き直した後も照合する点検を加えました。意味保持の既存ルールと組み合わせた独自の指示であり、本書の全手順を再現するものではありません。

作者・宛先

開発者: 大賀 愛一郎（oga_aiichiro）@ALGO ARTIS
宛先: @oga_aiichiro

※ 本スキルおよび本リポジトリは個人の研究・創作物であり、所属企業の公式プロダクトや見解を代表するものではありません。

ライセンス

本リポジトリのコードおよびドキュメントは MIT License のもとで公開しています。検証や引用に用いた外部資料の権利は各著作者に帰属し、それぞれの利用規約（CC BY 4.0等）に従うものとします。

最後に

このREADMEは、『yomiyasu』を用いて書かれています。

Frequently asked questions

Is yomiyasu free to use?

yomiyasu is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does yomiyasu do?

AI生成の日本語を自然な日本語へ推敲するAgent Skill / Agent Skill for Refining AI-Generated Japanese into Natural Japanese

What is yomiyasu written in?

yomiyasu is primarily written in Python. Its source is publicly available at https://github.com/nanaism/yomiyasu, and it has 1,589 GitHub stars.