English

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

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

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

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

• AI-Slopな日本語を構造レベルで読みやすくするSkill『yomiyasu（よみやす）』を作りました（Zenn）

Built with curiosity at ALGO ARTIS

文章を生成するAIは日常的な道具となりました。 一方で、AIで生成された文章には独特のクセが残りやすく、そのままでは実務や技術発信に使いにくい場面が多くあります。

これまでに様々な文体調整プロンプトやスキルが試されてきましたが、依然として「AI特有の読みにくさ」が残るケースが見られます。

従来のアプローチが抱えていた限界は、主に次の4点でした。

1. 禁止語の置き換えにとどまる対処
   「手触り」「解像度」「泥臭い」といった表層の単語を禁止しても、別の曖昧な語へ置き換わるだけで、不自然な文構造そのものは解消されませんでした。
2. 編集ルールの過剰適用
   修辞の規範を与えすぎると、モデルが指示を過剰に解釈し、かえって不自然な造語や大げさな文体を招いていました。
3. 主述関係の曖昧さと非生物主語
   誰が何をどうするのかが省略されたまま、概念や道具が比喩的な動詞（壊れる、倒す、効くなど）と結びつき、読み手が文脈を大きく補って読む必要がありました。
4. 形式の偏重と情報密度の低下
   太字や箇条書きが増える一方で、手順やコードの仕組みといった核心の部分は抽象的に書かれ、文章の量に比べて実際の情報が少なくなっていました。

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

1. 主述・修飾・条件の点検
   主語と述語、修飾語と掛かる先、指示語と指す対象を対応づけます。条件・例外・否定・並列・数量・順序も、書き直す前後で同じように追えるか確かめます。主体や対象を補うのは、原文や提供文脈から確定できる範囲に限ります。
2. 文の働きと文体の保持
   文ごとに説明・依頼・助言・予定を区別し、働きに合わない文末だけを直します。完了した変更作業、現在の動作や方針、今後の予定を時制と役割に合わせて書き分け、語尾を散らすこと自体を目的にしません。常体・敬体は変更の指定がなければ保ち、技術記事という分野だけを理由に敬体へ変えません。
3. 擬人化の整理
   道具や概念に感情や意志を持たせた表現を直します。道具やシステムの客観的な動作を述べる非生物主語は残します。
4. 比喩を平易な言葉へ
   壊れる、倒す、効く、溶かすなどを、元の含みや意味の広さを保って言い換えます。動詞を替えた後も、主体・対象・修飾先を変えず、語順を追いやすくできるか確かめます。
5. 前置き・否定対比の役割の確認
   前置きを削るのは、削っても主張や比重が変わらない場合だけです。評価や必要な対比、比較から方針へ移る接続は残します。
6. 情報を勝手に足さない
   主張・比重・言い切りの強さ・文の働きを保ち、原文にない主体・原因・条件・数値・感情などを足しません。ルールを「契約」、比較の基準を「正本」と大げさに呼ぶ場合は役割に合う語へ直し、文字どおりの意味や定義済みの専門用語は保ちます。意味を確定できない箇所は、原文にある未確定の状態や既知の動作を本文に残した暫定文とし、推敲の理由や確認事項は本文の後に添え、読者向けの本文には入れません。
7. 文長・読点・装飾の調整
   平均文長30〜45文字、1文の読点0〜2個を目安にします。短い主語や主題のすぐあとに置いて間を作るだけの読点は外し、並べを区切る読点や、外すと掛かり先が変わる読点は残します。箇条書きの頭のラベルとコロンは、値の項目や、物や作業の名前に説明が続く項目では残します。分類の語、出来事を名詞にまとめた語、短い述語のラベルは、外して説明と1文にまとめます。過剰な装飾記号を整理し、英単語や数値の前後の空白は元の書式や指定されたスタイルを保ちます。残す太字は表示される形に整えます。

このバージョンでは次の5つの手順を加えました。7つ目の原則にある読点とラベルの決まりも、このバージョンで足したものです。

• 書き直す前に、yomiyasu は文書の種類（PR説明、障害報告、メール、エッセイ・小説など12種類）と読者の知識（3段階）を決めます。議事録の箇条書きやメールの挨拶のように、その種類で普通の書き方は直しません。決めきれなければ、種類ごとの決まりを当てずに直します。
• 規則に当たった箇所を直す前に、案と原文を6つの点（何について述べるか、何を認め何を否定するか、誰が誰にするか、範囲と条件、言い切りの強さ、数値・固有名詞・時期）で比べます。1つでも変わるなら原文を残します（言い直しテスト）。
• 利用者が依頼で書き手と読み手の関係（「取引先に送るメールです」など）を伝えると、yomiyasu はその関係で人がふつう書く敬語に直します。書き手が自分でした行為で、ほかの人の行為と読み違えやすい文には、原文にある「私」「弊社」などを主語に補います。
• 原稿に抜けた数値や条件があると、yomiyasu は会話や資料から同じことを述べた文を探し、見つかったときだけ補います。見つからなければ本文はそのままにし、読み手が動けなくなる所だけを元の書き手への問いにします。
• 書き直したあとは、付属の yomiyasu_check.py で lint と diff をまとめて実行し、数値、否定、主語と目的語の入れ替えなどの変化を見直し候補として確かめます。返す直前には、最終稿が検査したものと同じかを記録と照らします。

語順や省略、助詞の選び方による読み違いと、仕様書や設計文書での許可・能力・保証の言い方のずれを扱う手順と検査を加えました。

• 目的語を書かない他動詞の前に比較や条件の句が挟まり、前のほうにある別の名詞が目的語に読める文は、文脈にある対象を目的語に書くか、動作を名詞にします。決まらなければ書き手に確かめます。漢語を和語の動詞に替えるのは、替えたあとも目的語が追え、意味の幅が同じときだけです。
• 主題の「〜は」「〜では」が後半の節まで掛かって読める文で、主題が部品や処理の名前で、後半に別の名前（設定、マクロ、ファイルなど）を扱う動作が出てくるときは、後半もその主題の話かを文脈から確かめ、決まらなければ主体を足さずに書き手に尋ねます。尋ねる場面をこれより広げると、ほかの文書でも念のための問いが増える恐れがあります。問いが多いと、書き手はそのたびに答えを考えることになり、本当に答えが要る問いがほかの問いに埋もれます。この釣り合いを見て、尋ねる場面をこの形に絞っています。
• 前置きのない「〜で変わったのは、A、B、C。」は、前の文や見出しに前提がなければ、「〜では、A、B、Cが変わった」のように述語まで書いた形に直します。lint には、この形を見直し候補にする規則（cleft_list_ending）を足しました。
• 「〜してよい」（許可）、「〜できる」（能力）、「必ず〜する」「〜を保証する」（保証）を互いに替えません。diff は、許可の言い方が消えた・増えた書き換えと、常体の「保証する」の足しを --fail-on=meaning-risk で止めます。仕様書や記事など、事実や仕様を述べる7つの文書の種類を指定したときは、「場合がある」を消した言い切りと「必ず」の足しも止めます。
• 「書き手に確かめたい点」は3点までになりました。3点を埋めるために問いを足さず、答えで本文が変わらない提案は入れません。

2.0.0 のスキルで AI の文章を推敲した例です。Claude Code（Claude Opus 5.5）に「draft.md を yomiyasu で読みやすくして、結果を out.md に書いてください。」とだけ頼み、1回目の出力をそのまま載せています。

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

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

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

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

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

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

従来の開発では、画面ごとに操作感を探りながらパーツを作っていました。しかし、片方だけを見て画面を作ると、もう片方のアクセシビリティが気づかないうちに損なわれます。そこでデザインシステムをしっかりした基本として用意すると、開発者の理解が一段深まります。

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

• コンポーネントを再利用することで開発が速くなり、時間を無駄にせずに済みます。
• 判断に迷うスタイルはあらかじめ共通のものに統一し、仕様をそろえます。
• ガイドラインが規律を求めるため、アクセシビリティを保ち、事故を未然に防ぐことができます。

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

yomiyasu は比喩や造語（意思決定OS、静かに壊れます、強固な土台、地味に効いてきます）をふだんの言葉に直し、太字をすべて外しました。箇条書きは太字のラベルとコロンを外し、「開発が速くなり」のようにラベルの意味を説明の文に入れています。結びの「！」は「。」にしました。原文だけでは決められない片方ともう片方は書き換えず、何を指すかを書き手に確かめたい点として報告しています。

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

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

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

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

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

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

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

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

単にメッセージを流すだけでは、気づかないうちにデータがおかしくなります。経路が前提を代わりに添えてくれるわけではありません。

そこで目立たないながらも役立つのが、以下の3つの原則です。

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

デバッグで丸一日を無駄にしないためにも、この境界線を意識した設計が不可欠です。

yomiyasu は太字を外し、比喩の動詞（静かに壊れます、地味に効いてくる、黙ってスキップ、潰していきます、時間を溶かさない）を言い換えました。最後のいかがでしたでしょうかは中身のない決まり文句として消しています。箇条書きは原則の名前に説明が続く形なので、ラベルとコロンを残しました。2行目の依存構造は分割できない。動かしながら引き返す。は何を言っているかが読み取れないので書き換えず、最後の文のこの境界線が何を指すかとあわせて、書き手に尋ねています。

1.1.2 までの README に載せていた After は、原文にない内容（例1の「高品質な行政サービス」、例2の「サーバーの再起動」）を足していました。2.0.0 は原文から決められない所の多くを作り足さずに残すので、After の変化は小さくなっています。ただし例1の意思決定OSは書き手に尋ねずに読みの1つを選んで言い換えています。

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

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

Claude Codeなどのエージェントの設定ディレクトリへ、スキルをインストール・更新します。スキル定義は skills/yomiyasu/SKILL.md の1か所に配置しています。

GitHub CLIの gh skill コマンドからインストールできます。

# 新規インストール
gh skill install nanaism/yomiyasu yomiyasu

# 最新版へのアップデート
gh skill update yomiyasu

導入先のエージェントを指定する場合は、--agent codex や --agent claude-code を追加してください。

# 新規インストールとAGENTS.mdへの反映
npx openskills install nanaism/yomiyasu
npx openskills sync

# 最新版へのアップデートとAGENTS.mdへの反映
npx openskills update yomiyasu
npx openskills sync

AGENTS.mdを経由して各エージェントから利用できるようになります。過去にネストされたパスを明示してインストールした環境では、スキルが自動では配置し直されません。その場合は、元のインストール先やオプションに合わせて npx openskills install nanaism/yomiyasu を実行し直してから、更新や同期をしてください。

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

Claude Code にプラグインで入れたスキルは yomiyasu:yomiyasu という名前になります。名前で呼ぶときは、スラッシュの補完に出るとおり yomiyasu:yomiyasu と書いてください。yomiyasu とだけ書くと「Unknown skill」になり、スキルを読み込まないまま文章を書いたという報告があります（スキルの名前）。

導入済みのプラグインを最新版へ更新する場合は、ターミナルで次のコマンドを実行します。

# マーケットプレイスの情報を更新
claude plugin marketplace update yomiyasu

# プラグインを最新版へ更新
claude plugin update yomiyasu@yomiyasu

更新を反映するには、Claude Codeを再起動してください。

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

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

Codex は作業するリポジトリの .agents/skills/ の下に置いたスキルを読みます。上の入れ方を使わない場合や Codex Cloud で開く場合は、このリポジトリの skills/yomiyasu/ フォルダを中身ごと、作業するリポジトリの .agents/skills/yomiyasu/ にコピーしてください。

# 作業するリポジトリの直下で実行（入れ直すときも同じ手順です）
rm -rf /tmp/yomiyasu .agents/skills/yomiyasu
git clone --depth 1 https://github.com/nanaism/yomiyasu /tmp/yomiyasu
mkdir -p .agents/skills
cp -R /tmp/yomiyasu/skills/yomiyasu .agents/skills/yomiyasu

この置き方では Codex がスキルを yomiyasu:yomiyasu という名前で一覧に載せます。呼ぶときは「/yomiyasu」とだけ送るか、依頼の文に「yomiyasu で」と書いてください。一覧の名前どおり $yomiyasu:yomiyasu と書いても呼べます。コピーしたフォルダは自動では新しくなりません。最新にするには、同じ手順でコピーし直してください。

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

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

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

このように依頼の文に名前を書いたとき、「/yomiyasu」と送ったとき、「日本語を推敲するスキルを使って」のようにスキルでの推敲をはっきり頼んだときに、yomiyasu が使われます。名前を出さずに「読みやすくして」とだけ頼むと、エージェントは yomiyasu を使わずに直します。

「/yomiyasu」とだけ送ると、yomiyasu は直前の返答でAIが書いた本文か、作業フォルダの直下に1つだけある原稿（.md か .txt）を推敲します。原稿のファイルは書き換えず、最終稿を同じフォルダに別の名前で保存します。

AI が書いたり直したりする日本語をいつも yomiyasu に通したいときは、エージェントが毎回読む指示のファイルに、入れ方ごとに下に示す1行を足してください。1行に書くスキルの名前は入れ方によって yomiyasu と yomiyasu:yomiyasu に分かれます。

npx skills add や gh skill install でスキルとして入れた場合は、スキルの名前が yomiyasu なので、次の1行を書きます。

記事、ドキュメント、PR の説明文、コミットメッセージなどの日本語の文章を書いたり直したりするときは、常に yomiyasu スキルで推敲してください。コードを直したあとの作業の報告には使わなくてかまいません。

プラグインで入れた場合は、スキルの名前が yomiyasu:yomiyasu になるので、1行の中の yomiyasu を yomiyasu:yomiyasu に書き換えてください。

1つのリポジトリだけで使うならそのリポジトリの直下の CLAUDE.md に、すべてのリポジトリで使うなら ~/.claude/CLAUDE.md に書きます。書いたあとに始めた会話から有効になります。

この1行があると、名前を出さずに記事や PR の説明文、コミットメッセージ、翻訳を書かせたときも、エージェントは yomiyasu で推敲します。コードを直したあとの作業の報告まで推敲させたいときは、「日本語の文章を書いたり直したりするときは、常に yomiyasu スキルで推敲してください。」とだけ書きます。プラグインで入れた場合は、こちらも yomiyasu を yomiyasu:yomiyasu に書き換えてください。

npx skills add や gh skill install で入れた場合も、作業するリポジトリの .agents/skills/ に置いた場合も、スキルの名前は yomiyasu:yomiyasu です。スキルのフォルダに Codex 用のプラグインの設定 .codex-plugin/plugin.json が入っているためです。次の1行を書きます。

記事、ドキュメント、PR の説明文、コミットメッセージなどの日本語の文章を書いたり直したりするときは、常に yomiyasu:yomiyasu スキルで推敲してください。コードを直したあとの作業の報告には使わなくてかまいません。

1つのリポジトリだけで使うならそのリポジトリの直下の AGENTS.md に、すべてのリポジトリで使うなら ~/.codex/AGENTS.md（CODEX_HOME を設定しているときはその場所の AGENTS.md）に書きます。書いたあとに始めた会話から有効になります。

コードや設定を直したあとの報告まで推敲させたいときは、「日本語の文章を書いたり直したりするときは、常に yomiyasu:yomiyasu スキルで推敲してください。」とだけ書きます。この書き方にすると、Codex は変数の名前を変えるだけの作業でも、最後の報告を書く前に yomiyasu を読みます。

openskills はスキルの一覧を AGENTS.md に書き込み、エージェントは npx openskills read yomiyasu でスキルを読みます。この入れ方でのスキルの名前は yomiyasu です。npx openskills sync は AGENTS.md の <skills_system> から </skills_system> までを書き直すので、1行はその外に書いてください。

記事、ドキュメント、PR の説明文、コミットメッセージなどの日本語の文章を書いたり直したりするときは、常に yomiyasu スキルで推敲してください（npx openskills read yomiyasu で読み込みます）。コードを直したあとの作業の報告には使わなくてかまいません。

2.0.2 に更新したら、npx openskills update yomiyasu のあとに npx openskills sync も実行してください。スキルの description は sync のときに AGENTS.md に写されるので、sync するまで、エージェントは 2.0.1 の description をもとに yomiyasu を使うかどうかを決めます。

openskills は既定でスキルをプロジェクトの .claude/skills/ に置くので、Claude Code はこのスキルを yomiyasu という名前で直接読みます。この場合は Claude Code の節の1行を、そのまま CLAUDE.md に書いてください。

ZIP で登録したスキルの名前は yomiyasu です。すべての会話で使うなら設定（Settings）の「Instructions for Claude」に、1つのプロジェクトだけで使うならそのプロジェクトの指示（project instructions）に、次の1行を書きます。どちらの置き場所も Claude のヘルプの Understanding Claude's personalization features に書かれています。

日本語の文章を書いたり直したりするときは、常に yomiyasu スキルで推敲してください。

文書の種類と読者は依頼の中で伝えられます。伝えなければ、スキルが本文の形から推定します。

この障害報告を yomiyasu で、専門知識のない社外の利用者向けに読みやすくして。
（ここに修正したい文章を貼り付け）

その種類で普通の書き方（表の右の列）は直しません。値は付属ツールの --doc-type に渡すものと同じです。

読者の知識は3段階です。同じ分野の専門家（expert）には用語を残し、分野は違うが技術に詳しい人（informed）か専門知識のない人（general）を指定したときだけ、原文と資料にある説明で言い換えるか、説明を添えます。説明がどこにもない語には説明を作らず、書き手に確かめたい点として返します。

書き手の立場と読み手との関係（上司、同じチーム、取引先、お客さまなど）を依頼の中で伝えると、yomiyasu はその関係に合わせて本文を直します。

draft.md を yomiyasu で読みやすくしてください。取引先の購買の担当者に送るメールです。

上司や社外の相手への依頼は「ご確認ください」「お知らせください」のように、その関係で人がふつう書く敬語にします。書き手が自分でした行為で、ほかの人の行為と読み違えやすい文には、原文にある「私」「弊社」などを主語に補います（原文に一人称がなければ補いません）。頼む中身、期限、選択肢は変えず、担当者やお詫びの文も足しません。関係を伝えなければ、本文の敬語は変えません。

原稿に抜けた数値や条件があると、yomiyasu は原文、依頼、渡された資料、利用者の発言、開いたファイル、コマンドの出力から、同じことを述べた文を探します。根拠の文が見つかったときだけ確度を変えずに補い、見つからなければ本文はそのままにして、読み手が動けなくなる所だけを元の書き手への問いにします。AI 自身の発言や一般の知識は根拠にしません。

書いた日が確かに分かれば、「昨日」のような言い方に括弧で日付を添えます（昨日（10月15日））。

yomiyasu は推敲した本文のあとに、変えたところと確認の記録を付けます。残したAIっぽいところ、書き手に確かめたい点、事実の確かめが付くのは、書くことがあるときだけです。確認の記録には実行した検査と、yomiyasu_check.py の状態の行（yomiyasu-check: で始まる行）を写します。本文だけを返すよう頼めば、説明の欄は省きます（検査は同じように行います）。

推敲だけでなくAIに文章を書かせる前にyomiyasuを読ませる使い方もあります。ai-garageの検証記事（2026年10月11日、v1.1.1で検証）では、Claude Opus 5.5に8種類のメモから文章を書かせ、書かせ方を4通り比べています。先にyomiyasuを読ませた文章は、メモにない内容を書き足したと指摘された回数が2回で、何も付けずに書かせた場合の60回から大きく減りました。

一方で、文章は平均356字と、依頼した500字程度より短くなりました。読みやすさの評価は4通りの中で最も低く、時間と費用も約4倍かかっています。これはAIが採点した、文章の種類ごとの本数も少ない1つの試験の結果です。記事では、この使い方は数字や日付、条件を正確に伝えたい文章（営業メール、障害報告書、手順書など）に向くとしています。エッセイや告知のような読み物には何も付けずに書かせるか、依頼に一言添えるほうが向くという結論です。

2.0.0 で資料から新しく書かせると、yomiyasu は付属の検査で最終稿の数値や名前を資料と照らし合わせ、資料にないものを見直し候補として出します。2.0.2 からは名前を出さずに書かせると yomiyasu は使われません。資料から書かせるときも「notes.md をもとに記事を書いて、最後に yomiyasu で推敲して」のように、依頼に名前を入れてください。

種類ごとの決まり、敬語の上げ方、事実を補う決まり、完了報告の欄の詳しい説明は docs/usage.md にまとめています。

文章の表現と書式を見る yomiyasu_lint.py、推敲の前後を比べる yomiyasu_diff.py、2つをまとめて実行して記録を残す yomiyasu_check.py を同梱しています。設定に貼ったときだけ動く任意のフック yomiyasu_hook.py もあります。どれも外部ライブラリは要らず、Python の標準ライブラリだけで動きます（テストは Python 3.9 と 3.14 で実行しています）。

検査は見直し候補と変わった箇所を出すだけで、意味が保たれたかどうかや、読みやすいかどうかは判定しません。候補が出た所を直すかどうかは、元の文や文脈と照らし合わせて決めてください。

1つの文章について、不自然な比喩動詞、決まり文句、過剰な太字や箇条書き、絵文字、文末コロン、表示されない太字などを、見直し候補として行ごとに出します。2.0.0 からは通常の出力に点数を出しません。点数が読みやすさの合格点のように見えてしまうためです（点数が出なくなった理由）。

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

# warn か error の候補があれば終了コード1を返す（CIやGitフック用）
python3 scripts/yomiyasu_lint.py article.md --fail-on warn

# 文書の種類を指定（その種類で普通の書き方を候補から外す）
python3 scripts/yomiyasu_lint.py minutes.md --doc-type minutes

# JSON形式で結果を出力
python3 scripts/yomiyasu_lint.py article.md --json

2.0.0 で --json の点数のキーを score から rule_penalty_score に、候補の有無のキーを is_clean から no_rule_findings に変えました。前の名前のキーは残していないので、jq .score のように前の名前で読むと null になります。rule_penalty_score は計算も変えたので、score に使っていたしきい値はそのまま使えません。どちらの形式の JSON かは format_version で見分けられます（2.0.0 からは2で、1.1.2 までの JSON にはこのキーがありません）。jq での読み替えの例は JSON を前のキーの名前で読んでいたとき にあります。

表現・書式の検査を実行しました。
見直し候補: 1件
この検査では、意味の保持と読者にとっての分かりやすさは判定していません。

内訳: error 0件、warn 1件、info 0件

L1 [WARN] metaphor_verb: 比喩動詞「壊れる」が検出されました。不自然な比喩動詞であれば、ふだん使う動詞や客観的な表現に書き直してください。ただし、文字どおりの動作や状態変化を表している場合は無理に言い換える必要はありません。
  > 単にメッセージを流すだけでは、背後でデータが静かに壊れます。

推敲の前と後を比べ、変わった箇所をすべて出します。数値、否定、「が」「を」の入れ替え、文の種類（伝聞、推量、依頼など）が変わった所は、意味が変わる恐れとして先に示します。

# 原文と推敲後を比べる
python3 scripts/yomiyasu_diff.py 元の文.md 書き直した文.md

# 数値・否定・入れ替え・文の種類の変化があれば終了コード1を返す
python3 scripts/yomiyasu_diff.py 元の文.md 書き直した文.md --fail-on=meaning-risk

「田中が佐藤を承認した。」と「設定は3日ごとに保存します。」の2つの段落を、「佐藤が田中を承認した。」と「設定は30日ごとに保存しません。」に書き換えると、次のように出ます。

差分の検査を実行しました。
状態: 変更あり（2か所）。見直し候補 3件、うち意味が変わる恐れ 3件
全文差分は変わった箇所を示すだけで、意味が同じだという証明ではありません。この検査では、意味の保持と読者にとっての分かりやすさは判定していません。

■ 意味が変わる恐れ（3件。原文と資料に照らして確かめる）
- 「が」「を」などが入れ替わった（1行目）: 田中 が→を、佐藤 を→が
  元: 田中が佐藤を承認した。
  後: 佐藤が田中を承認した。
- 数値が変わった（3行目）: 3日 → 30日
  元: 設定は3日ごとに保存します。
  後: 設定は30日ごとに保存しません。
- 否定の有無が変わった（3行目）: 保存します → 保存しません
  元: 設定は3日ごとに保存します。
  後: 設定は30日ごとに保存しません。
（このあとに全文差分が続きます）

最終稿に lint を、原文と最終稿に diff をまとめて実行し、記録を残します。スキルは書き直したあとに run を実行し、返す直前に verify で、最終稿が検査したものと同じかを記録と照らし合わせます。

# 原文と最終稿を検査する（資料があれば --material 資料 を足す）
python3 scripts/yomiyasu_check.py run --source 原文.md --final 最終稿.md --doc-type article

# 返す直前に、最終稿が検査したものと同じかを記録と照らす
python3 scripts/yomiyasu_check.py verify --final 最終稿.md

推敲の前と後を比べるときは、run の出力の「見直し候補: 原文 N件 → 最終稿 M件」の行と、そのすぐ下の「■ 直した箇所」に並ぶ元と後を読んでください。候補があるときは、出力の4行目に候補の短い一覧（行番号のある候補は行番号と規則の名前）が出ます。中身は下の節にあるので、出力を切らずに読んでください。件数は lint の規則に当たった数です。記録は git リポジトリの最上位にある .yomiyasu/ に置かれ、git の管理には入りません。同じリポジトリをほかの OS ユーザー（Codex のサンドボックスなど）も使うときは、YOMIYASU_STATE_DIR でユーザーごとに別の場所を指定してください（docs/tools.md）。実行漏れを見つけるための記録なので、合格の証明にはなりません。

Claude Code か Codex の設定に貼ったときだけ動く補助のスクリプトです。このフックは登録された原稿について、AI が返答を終える前と投稿の前に、最終稿が検査の記録と合うかを確かめます。入れなくても yomiyasu はこれまでどおり使えます。

出力の読み方、オプション、終了コード、フックの入れ方は docs/tools.md にまとめています。

付属の検査は決まった形を拾うだけです。候補が出なかった所も元の文と読み比べて確かめてください。

推敲の動作は対話の画面を使わないコマンド（claude -p と codex exec）で macOS の Claude Code と Codex を動かして確かめました。対話の画面、Claude Code のプラグイン・npx skills add・gh skill install・npx openskills install で入れた環境、Codex Cloud、Cursor、Claude.ai へのZIPの登録、Windows での動作は確かめていません。2.0.2 を公開したあとに、GitHub の nanaism/yomiyasu からこの4つの入れ方で入れ、Claude Code と Codex がスキルを読み込むところまでを確かめました（openskills は npx openskills read yomiyasu で読めるところまで）。

検査で拾えない形、正しい推敲にも候補が出る形、測った結果は docs/limitations.md にまとめています。

.
├── .claude-plugin/                   # Claude Code用プラグイン設定
│   ├── plugin.json
│   └── marketplace.json
├── .github/workflows/ci.yml          # 自動の試験（テスト一式と、2か所のファイルが同じかの確かめ）
├── README.md                         # 本ドキュメント
├── README.en.md                      # 英語の短い紹介
├── CHANGELOG.md                      # 変更履歴（2.0.0 から）
├── LICENSE                           # ライセンス（MIT）
├── UNICODE-LICENSE.txt               # Unicodeデータの著作権・許諾通知
├── docs/                             # 詳しい説明
│   ├── usage.md                      # 使い方の詳細
│   ├── tools.md                      # 付属ツールの詳しい使い方
│   └── limitations.md                # 限界と確かめた範囲
├── scripts/                          # 付属検査ツール群
│   ├── yomiyasu_lint.py             # 表現と書式の検査
│   ├── yomiyasu_diff.py             # 推敲の前後の比較（全文差分と意味が変わる恐れ）
│   ├── yomiyasu_check.py            # lint と diff をまとめて実行し、記録を残す
│   ├── yomiyasu_hook.py             # 任意のフック（設定に貼ったときだけ動く）
│   ├── markdown_visibility.py       # Markdown構造・表示判定の共有モジュール
│   └── setup_corpus_static.py など   # 評価用コーパスを作った開発用のスクリプト
├── references/                       # スキル参照ドキュメント
│   ├── gemini-syntax.md              # 構文変換原則
│   ├── slop-catalog.md               # 不自然な語彙・構文カタログ
│   ├── audience.md など              # 種類と読者の決め方、書き手と読み手、出力の見方、言い直しテスト、事実の確かめ
│   ├── doc-types/                    # 文書の種類ごとの注意（12種類）
│   ├── domains/                      # 分野別指針（tech, business, essay）
│   └── lists/                        # 検査に使う語の一覧（名詞化、強める語、気持ちの語、慎重な言い方、事実の穴の候補）
├── skills/                           # 配布用スキル（唯一のSKILL.mdと参照文書・検査ツール）
│   └── yomiyasu/
│       ├── .codex-plugin/plugin.json  # Codex でスキルを yomiyasu:yomiyasu の名前で載せるための設定
│       ├── SKILL.md
│       ├── references/
│       └── scripts/
├── tests/                            # 単体テスト・回帰テストスイート
│   ├── test_*.py                     # 検査ツールとスキルの文書の試験
│   ├── corpus/                       # 評価用コーパス
│   └── fixtures/                     # 回帰テスト用フィクスチャ
└── evals/                            # 評価データ
    └── comparison_benchmark.md       # 過去の比較検証の記録

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

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

• Yamashita et al., Evaluation of Document-Level Text Simplification in Japanese, LREC 2026
  必要情報、意味保持、文の平易さを分けて評価する設計の参考としました。
• Jeong, Park & Yu, Right at My Level: A Unified Multilingual Framework for Proficiency-Aware Text Simplification, ACL 2026
  原文内容の脱落と、根拠のない情報付加を別々に検証するアプローチを参考にしています。
• Ide et al., Towards Automated Lexicography: Generating and Evaluating Definitions for Learner's Dictionaries, 2026
  局所的な問題箇所の特定と修正を通じて、文全体の整合性を保つ手法の参考にしました。
• Nohejl et al., A Japanese Dataset and Efficient Multilingual LLM-Based Methods for Lexical Simplification and Lexical Complexity Prediction, 自然言語処理 32巻4号
  語の平易化における文法性と意味保持のバランスを検討する基礎としています。
• 八木ほか, 多文化共生を目指した『やさしい日本語』における大規模言語モデルのプロンプトデザインの検証, 人間中心設計 22巻1号
  プロンプト内の例示設計とモデルの挙動特性に関する知見を参考にしました。
• Chen, Yue & Davidge, Comparing generative AI with native speakers in terms of request expressions in Japanese, Discover Education 2025
  相手との距離感を保ち、主語や敬語を一律に過剰付加しない判断の参考にしています。
• Zaitsu et al., Stylometry can reveal artificial intelligence authorship, but humans struggle, PLOS One 2025
  AIらしさの検出と読みにくさの判定を区別して扱う論理的根拠としました。
• 三浦・久保山, 生成AIは文体を均質化するのか？, 人工知能学会 2026 / 林・相澤, LLMによる日本語生成におけるモデル固有表現パターンの分析, 言語処理学会 2026
  文体の画一化を避け、書き手らしさや文末の自然な交差を尊重する視点を学びました。
• 李・長谷部, ChatGPTによる日本語ニュースの平易化 生成AIと『やさしい日本語』, 計量国語学 34巻8号
  数値上の単純化と、人間にとって自然な編集の差異を踏まえるための指針としています。
• 書式および語彙の偏りに関する研究群（ACL 2025 書式バイアス研究, COLING 2025 語彙偏り研究, Miklian et al. 2026）
  強調やリストへの評価偏向、英語直訳思考の影響を理解するための補助資料として活用しました。

• natural-japanese, stop-ai-slop-jp, japanese-tech-writing, cognitive-rhythm-writing, humanizer
  読者に応じた編集、専門用語や条件の保持、文の長さや区切り方などを参考にしました。各作者に感謝します。

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

• 「AIっぽい文章を直すスキル」に、うちの日記を通したら、ほとんど直されなかった
  自然な文を不要に変更しないことと、保存済みサンプルの意味を原文と照合することを、検証項目として見直しました。
• 流行りの「AI日本語推敲スキル」を使う前にやっておきたいこと
  説明すると述べた対象や関係が、本文から読み取れるかを確認する観点を参考にしました。

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

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

本リポジトリのコードおよびドキュメントは MIT License のもとで公開しています。同梱しているUnicode由来データの著作権・許諾通知は UNICODE-LICENSE.txt に記載しています。検証や引用に用いた外部資料の権利は各著作者に帰属し、それぞれの利用規約（CC BY 4.0等）に従うものとします。

yomiyasuを記事や動画、SNS、勉強会などで紹介・解説していただけると嬉しいです！ 作者への連絡や許可はいりません。

ただし、yomiyasuは無料で公開しているオープンソースのスキルで、正式な配布元はこのリポジトリだけです。 yomiyasuを紹介・同梱する有料の教材や情報商材、yomiyasuとの関連をうたうトークンや暗号資産に、作者は一切関わっておらず、収益も受け取っていません。

yomiyasuは、多くの先行研究や公開された知見をもとに作っています。 そのため作者は、これまでもこれからも、yomiyasuそのもので利益を得るつもりはありません。

このREADMEの「これは何？」から「限界」までの節は yomiyasu で推敲しています。README の全体は付属の yomiyasu_lint.py に通しています。