<p align="center">
<img src="./assets/yomiyasu_logo.jpg" alt="yomiyasu v2.1.1 logo" width="700">
</p>
# yomiyasu（よみやす）
[](./LICENSE)
[](https://github.com/nanaism/yomiyasu/releases)
[English](./README.en.md)
## これは何？
『**yomiyasu（よみやす）**』はAIが生成した日本語の不自然な比喩、曖昧な主述関係、不要な装飾を直し、読みやすい文章に整えるスキルです。
主に技術記事、設計書・仕様書、PR説明文、社内レポートなどの実務的な文章を対象として設計されています。
Claude Code、Codex、CursorをはじめとするAIコーディング環境に読み込ませて使用してください。
開発の背景、AI生成文の読みにくさ、コーパスを使った検証については、次の解説記事で紹介しています。
- [AI-Slopな日本語を構造レベルで読みやすくするSkill『yomiyasu（よみやす）』を作りました（Zenn）](https://zenn.dev/algoartis/articles/0b1c731881b25c)
*Built with curiosity at [ALGO ARTIS](https://www.algo-artis.com/)*
[](https://www.algo-artis.com/)
<details>
<summary>ALGO ARTISについて</summary>
> 株式会社ALGO ARTISは、社会基盤の最適化に取り組むスタートアップです。
>
> 電力・海運・化学プラントといった現場では、膨大な制約が絡み合う複雑な運用計画を、今なお熟練者が手作業で組み立てています。
>
> そうした高度な現場業務を数理モデル化し、実用的なヒューリスティック最適化アルゴリズムと業務システムを一貫して開発しています。
>
> 最適化技術を用いた社会インフラの変革に興味がある方は、[公式ウェブサイト](https://www.algo-artis.com/)や[採用情報](https://www.algo-artis.com/career/)をご覧ください。
</details>
## 背景と課題
文章を生成するAIは日常的な道具となりました。
一方で、AIで生成された文章には独特のクセが残りやすく、そのままでは実務や技術発信に使いにくい場面が多くあります。
これまでに様々な文体調整プロンプトやスキルが試されてきましたが、依然として「AI特有の読みにくさ」が残るケースが見られます。
従来のアプローチが抱えていた限界は、主に次の4点でした。
1. 禁止語の置き換えにとどまる対処
「手触り」「解像度」「泥臭い」といった表層の単語を禁止しても、別の曖昧な語へ置き換わるだけで、不自然な文構造そのものは解消されませんでした。
2. 編集ルールの過剰適用
修辞の規範を与えすぎると、モデルが指示を過剰に解釈し、かえって不自然な造語や大げさな文体を招いていました。
3. 主述関係の曖昧さと非生物主語
誰が何をどうするのかが省略されたまま、概念や道具が比喩的な動詞（壊れる、倒す、効くなど）と結びつき、読み手が文脈を大きく補って読む必要がありました。
4. 形式の偏重と情報密度の低下
太字や箇条書きが増える一方で、手順やコードの仕組みといった核心の部分は抽象的に書かれ、文章の量に比べて実際の情報が少なくなっていました。
## 本スキルのアプローチ
元の意味を保ったまま、読み違えやすい箇所や、文の関係を追うのに負担がかかる箇所を直します。自然に読める部分は残します。
### 7つの変換原則
1. 主述・修飾・条件の点検
主語と述語、修飾語と掛かる先、指示語と指す対象を対応づけます。条件・例外・否定・並列・数量・順序も、書き直す前後で同じように追えるか確かめます。主体や対象を補うのは、原文や提供文脈から確定できる範囲に限ります。
2. 文の働きと文体の保持
文ごとに説明・依頼・助言・予定を区別し、働きに合わない文末だけを直します。完了した変更作業、現在の動作や方針、今後の予定を時制と役割に合わせて書き分け、語尾を散らすこと自体を目的にしません。常体・敬体は変更の指定がなければ保ち、技術記事という分野だけを理由に敬体へ変えません。
3. 擬人化の整理
道具や概念に感情や意志を持たせた表現を直します。道具やシステムの客観的な動作を述べる非生物主語は残します。
4. 比喩を平易な言葉へ
`壊れる`、`倒す`、`効く`、`溶かす`などを、元の含みや意味の広さを保って言い換えます。動詞を替えた後も、主体・対象・修飾先を変えず、語順を追いやすくできるか確かめます。
5. 前置き・否定対比の役割の確認
前置きを削るのは、削っても主張や比重が変わらない場合だけです。評価や必要な対比、比較から方針へ移る接続は残します。
6. 情報を勝手に足さない
主張・比重・言い切りの強さ・文の働きを保ち、原文にない主体・原因・条件・数値・感情などを足しません。ルールを「契約」、比較の基準を「正本」と大げさに呼ぶ場合は役割に合う語へ直し、文字どおりの意味や定義済みの専門用語は保ちます。意味を確定できない箇所は、原文にある未確定の状態や既知の動作を本文に残した暫定文とし、推敲の理由や確認事項は本文の後に添え、読者向けの本文には入れません。
7. 文長・読点・装飾の調整
平均文長30〜45文字、1文の読点0〜2個を目安にします。短い主語や主題のすぐあとに置いて間を作るだけの読点は外し、並べを区切る読点や、外すと掛かり先が変わる読点は残します。箇条書きの頭のラベルとコロンは、値の項目や、物や作業の名前に説明が続く項目では残します。分類の語、出来事を名詞にまとめた語、短い述語のラベルは、外して説明と1文にまとめます。過剰な装飾記号を整理し、英単語や数値の前後の空白は元の書式や指定されたスタイルを保ちます。残す太字は表示される形に整えます。
### 2.0.0 で加わったこと
このバージョンでは次の5つの手順を加えました。7つ目の原則にある読点とラベルの決まりも、このバージョンで足したものです。
- 書き直す前に、yomiyasu は文書の種類（PR説明、障害報告、メール、エッセイ・小説など12種類）と読者の知識（3段階）を決めます。議事録の箇条書きやメールの挨拶のように、その種類で普通の書き方は直しません。決めきれなければ、種類ごとの決まりを当てずに直します。
- 規則に当たった箇所を直す前に、案と原文を6つの点（何について述べるか、何を認め何を否定するか、誰が誰にするか、範囲と条件、言い切りの強さ、数値・固有名詞・時期）で比べます。1つでも変わるなら原文を残します（言い直しテスト）。
- 利用者が依頼で書き手と読み手の関係（「取引先に送るメールです」など）を伝えると、yomiyasu はその関係で人がふつう書く敬語に直します。書き手が自分でした行為で、ほかの人の行為と読み違えやすい文には、原文にある「私」「弊社」などを主語に補います。
- 原稿に抜けた数値や条件があると、yomiyasu は会話や資料から同じことを述べた文を探し、見つかったときだけ補います。見つからなければ本文はそのままにし、読み手が動けなくなる所だけを元の書き手への問いにします。
- 書き直したあとは、付属の `yomiyasu_check.py` で lint と diff をまとめて実行し、数値、否定、主語と目的語の入れ替えなどの変化を見直し候補として確かめます。返す直前には、最終稿が検査したものと同じかを記録と照らします。
### 2.1.0 で加わったこと
語順や省略、助詞の選び方による読み違いと、仕様書や設計文書での許可・能力・保証の言い方のずれを扱う手順と検査を加えました。
- 目的語を書かない他動詞の前に比較や条件の句が挟まり、前のほうにある別の名詞が目的語に読める文は、文脈にある対象を目的語に書くか、動作を名詞にします。決まらなければ書き手に確かめます。漢語を和語の動詞に替えるのは、替えたあとも目的語が追え、意味の幅が同じときだけです。
- 主題の「〜は」「〜では」が後半の節まで掛かって読める文で、主題が部品や処理の名前で、後半に別の名前（設定、マクロ、ファイルなど）を扱う動作が出てくるときは、後半もその主題の話かを文脈から確かめ、決まらなければ主体を足さずに書き手に尋ねます。尋ねる場面をこれより広げると、ほかの文書でも念のための問いが増える恐れがあります。問いが多いと、書き手はそのたびに答えを考えることになり、本当に答えが要る問いがほかの問いに埋もれます。この釣り合いを見て、尋ねる場面をこの形に絞っています。
- 前置きのない「〜で変わったのは、A、B、C。」は、前の文や見出しに前提がなければ、「〜では、A、B、Cが変わった」のように述語まで書いた形に直します。lint には、この形を見直し候補にする規則（`cleft_list_ending`）を足しました。
- 「〜してよい」（許可）、「〜できる」（能力）、「必ず〜する」「〜を保証する」（保証）を互いに替えません。diff は、許可の言い方が消えた・増えた書き換えと、常体の「保証する」の足しを `--fail-on=meaning-risk` で止めます。仕様書や記事など、事実や仕様を述べる7つの文書の種類を指定したときは、「場合がある」を消した言い切りと「必ず」の足しも止めます。
- 「書き手に確かめたい点」は3点までになりました。3点を埋めるために問いを足さず、答えで本文が変わらない提案は入れません。
## Before → After 例
2.0.0 のスキルで AI の文章を推敲した例です。Claude Code（Claude Opus 5.5）に「draft.md を yomiyasu で読みやすくして、結果を out.md に書いてください。」とだけ頼み、1回目の出力をそのまま載せています。
### 例1: 業務・仕様解説
#### Before
> ここで**重要なのは、単なるパーツの共通化ではなく、組織の意思決定OSとしてのガバナンス**です。
>
> 従来の開発では、画面ごとに手触り感を探りながらパーツを作っていました。しかし、片方だけを見て画面を作ると、もう片方のアクセシビリティが**静かに壊れます**。そこでデザインシステムという**強固な土台**を置くことで、開発者の**解像度が一段上がります**。
>
> デザインシステム導入のメリットは、主に次の3点です。
> - **開発速度の加速**: コンポーネントを再利用することで、時間を溶かさずに済みます。
> - **仕様の収斂**: 判断に迷うスタイルは、あらかじめ**共通側に倒します**。
> - **アクセシビリティの担保**: ガイドラインが規律を要求するため、事故を未然に防ぐことができます。
>
> もちろん、これは「デザイナーが不要になる」ことを意味しません。日々の開発に**地味に効いてきます**。ぜひ参考にしてみてください！
#### After
> ここでは、単なるパーツの共通化ではなく組織で意思決定をするときの枠組みとしてのガバナンスが重要です。
>
> 従来の開発では、画面ごとに操作感を探りながらパーツを作っていました。しかし、片方だけを見て画面を作ると、もう片方のアクセシビリティが気づかないうちに損なわれます。そこでデザインシステムをしっかりした基本として用意すると、開発者の理解が一段深まります。
>
> デザインシステム導入のメリットは主に次の3点です。
> - コンポーネントを再利用することで開発が速くなり、時間を無駄にせずに済みます。
> - 判断に迷うスタイルはあらかじめ共通のものに統一し、仕様をそろえます。
> - ガイドラインが規律を求めるため、アクセシビリティを保ち、事故を未然に防ぐことができます。
>
> もちろん、これは「デザイナーが不要になる」ことを意味しません。日々の開発に目立たないながらも役立ってきます。ぜひ参考にしてみてください。
#### 変更説明
yomiyasu は比喩や造語（`意思決定OS`、`静かに壊れます`、`強固な土台`、`地味に効いてきます`）をふだんの言葉に直し、太字をすべて外しました。箇条書きは太字のラベルとコロンを外し、「開発が速くなり」のようにラベルの意味を説明の文に入れています。結びの「！」は「。」にしました。原文だけでは決められない`片方`と`もう片方`は書き換えず、何を指すかを書き手に確かめたい点として報告しています。
### 例2: 技術解説
#### Before
> 非同期処理における**最大の落とし穴**は、ネットワークの瞬断です。
>
> **依存構造は分割できない。動かしながら引き返す。**
>
> 単にメッセージを流すだけでは、背後でデータが**静かに壊れます**。前提を、経路が代わりに添えてくれるわけではありません。
>
> そこで**地味に効いてくる**のが、以下の3つの原則です。
> - **冪等性の担保**: 重複した処理は**黙ってスキップ**します。
> - **安全なリトライ**: 指数バックオフを挟むことで、DBの負荷を逃がします。
> - **DLQへの退避**: 破綻したメッセージは隔離し、原因を1つずつ**潰していきます**。
>
> デバッグで丸一日**時間を溶かさない**ためにも、この境界線を意識した設計が不可欠です。いかがでしたでしょうか。
#### After
> 非同期処理における最大の落とし穴は、ネットワークの瞬断です。
>
> 依存構造は分割できない。動かしながら引き返す。
>
> 単にメッセージを流すだけでは、気づかないうちにデータがおかしくなります。経路が前提を代わりに添えてくれるわけではありません。
>
> そこで目立たないながらも役立つのが、以下の3つの原則です。
> - 冪等性の担保: 重複した処理は表に出さずにスキップします。
> - 安全なリトライ: 指数バックオフを挟むことで、DBの負荷を逃がします。
> - DLQへの退避: 破綻したメッセージは隔離し、原因を1つずつ取り除いていきます。
>
> デバッグで丸一日を無駄にしないためにも、この境界線を意識した設計が不可欠です。
#### 変更説明
yomiyasu は太字を外し、比喩の動詞（`静かに壊れます`、`地味に効いてくる`、`黙ってスキップ`、`潰していきます`、`時間を溶かさない`）を言い換えました。最後の`いかがでしたでしょうか`は中身のない決まり文句として消しています。箇条書きは原則の名前に説明が続く形なので、ラベルとコロンを残しました。2行目の`依存構造は分割できない。動かしながら引き返す。`は何を言っているかが読み取れないので書き換えず、最後の文の`この境界線`が何を指すかとあわせて、書き手に尋ねています。
1.1.2 までの README に載せていた After は、原文にない内容（例1の「高品質な行政サービス」、例2の「サーバーの再起動」）を足していました。2.0.0 は原文から決められない所の多くを作り足さずに残すので、After の変化は小さくなっています。ただし例1の`意思決定OS`は書き手に尋ねずに読みの1つを選んで言い換えています。
## インストール
### 1. `npx skills add`（推奨）
```bash
# 新規インストール
npx skills add nanaism/yomiyasu
# 最新版へのアップデート
npx skills update yomiyasu
```
Claude Codeなどのエージェントの設定ディレクトリへ、スキルをインストール・更新します。スキル定義は `skills/yomiyasu/SKILL.md` の1か所に配置しています。
### 2. `gh skill install`
GitHub CLIの `gh skill` コマンドからインストールできます。
```bash
# 新規インストール
gh skill install nanaism/yomiyasu yomiyasu
# 最新版へのアップデート
gh skill update yomiyasu
```
導入先のエージェントを指定する場合は、`--agent codex` や `--agent claude-code` を追加してください。
### 3. `npx openskills install`
```bash
# 新規インストールと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` を実行し直してから、更新や同期をしてください。
### 4. Claude Code プラグイン
```text
/plugin marketplace add nanaism/yomiyasu
/plugin install yomiyasu@yomiyasu
```
Claude Code にプラグインで入れたスキルは `yomiyasu:yomiyasu` という名前になります。名前で呼ぶときは、スラッシュの補完に出るとおり `yomiyasu:yomiyasu` と書いてください。`yomiyasu` とだけ書くと「Unknown skill」になり、スキルを読み込まないまま文章を書いたという報告があります（[スキルの名前](./docs/usage.md#スキルの名前)）。
導入済みのプラグインを最新版へ更新する場合は、ターミナルで次のコマンドを実行します。
```bash
# マーケットプレイスの情報を更新
claude plugin marketplace update yomiyasu
# プラグインを最新版へ更新
claude plugin update yomiyasu@yomiyasu
```
更新を反映するには、Claude Codeを再起動してください。
### 5. ZIPファイルからの登録（Claude.ai Web版など）
Claudeのカスタムスキル登録機能（Web版など）には登録専用のZIPを使ってください。GitHubの「Download ZIP」で取得したリポジトリ全体のZIPにはプラグイン設定や開発用ファイルも含まれ、登録できない場合があります。専用のZIPにはスキル本体、参照文書、検査スクリプト、ライセンスの35個のファイルだけを入れています。
1. 以下のリンクから、登録専用のZIPファイルをダウンロードします。
[yomiyasu.zip（最新版ダウンロード）](https://github.com/nanaism/yomiyasu/releases/latest/download/yomiyasu.zip)
2. ダウンロードした `yomiyasu.zip` を解凍せず、Claudeのスキル登録画面にそのままアップロードしてください。
### 6. Codex で使うリポジトリに置く（Codex Cloud など）
Codex は作業するリポジトリの `.agents/skills/` の下に置いたスキルを読みます。上の入れ方を使わない場合や Codex Cloud で開く場合は、このリポジトリの `skills/yomiyasu/` フォルダを中身ごと、作業するリポジトリの `.agents/skills/yomiyasu/` にコピーしてください。
```bash
# 作業するリポジトリの直下で実行（入れ直すときも同じ手順です）
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チャットやコーディングエージェントに下書きを貼り付けて、次のように指示します。
```text
この文章を yomiyasu で読みやすくして。
（ここに修正したい文章を貼り付け）
```
このように依頼の文に名前を書いたとき、「/yomiyasu」と送ったとき、「日本語を推敲するスキルを使って」のようにスキルでの推敲をはっきり頼んだときに、yomiyasu が使われます。名前を出さずに「読みやすくして」とだけ頼むと、エージェントは yomiyasu を使わずに直します。
「/yomiyasu」とだけ送ると、yomiyasu は直前の返答でAIが書いた本文か、作業フォルダの直下に1つだけある原稿（`.md` か `.txt`）を推敲します。原稿のファイルは書き換えず、最終稿を同じフォルダに別の名前で保存します。
### 毎回 yomiyasu を使いたいとき
AI が書いたり直したりする日本語をいつも yomiyasu に通したいときは、エージェントが毎回読む指示のファイルに、入れ方ごとに下に示す1行を足してください。1行に書くスキルの名前は入れ方によって `yomiyasu` と `yomiyasu:yomiyasu` に分かれます。
#### Claude Code
`npx skills add` や `gh skill install` でスキルとして入れた場合は、スキルの名前が `yomiyasu` なので、次の1行を書きます。
```text
記事、ドキュメント、PR の説明文、コミットメッセージなどの日本語の文章を書いたり直したりするときは、常に yomiyasu スキルで推敲してください。コードを直したあとの作業の報告には使わなくてかまいません。
```
プラグインで入れた場合は、スキルの名前が `yomiyasu:yomiyasu` になるので、1行の中の `yomiyasu` を `yomiyasu:yomiyasu` に書き換えてください。
1つのリポジトリだけで使うならそのリポジトリの直下の `CLAUDE.md` に、すべてのリポジトリで使うなら `~/.claude/CLAUDE.md` に書きます。書いたあとに始めた会話から有効になります。
この1行があると、名前を出さずに記事や PR の説明文、コミットメッセージ、翻訳を書かせたときも、エージェントは yomiyasu で推敲します。コードを直したあとの作業の報告まで推敲させたいときは、「日本語の文章を書いたり直したりするときは、常に yomiyasu スキルで推敲してください。」とだけ書きます。プラグインで入れた場合は、こちらも `yomiyasu` を `yomiyasu:yomiyasu` に書き換えてください。
#### Codex
`npx skills add` や `gh skill install` で入れた場合も、作業するリポジトリの `.agents/skills/` に置いた場合も、スキルの名前は `yomiyasu:yomiyasu` です。スキルのフォルダに Codex 用のプラグインの設定 `.codex-plugin/plugin.json` が入っているためです。次の1行を書きます。
```text
記事、ドキュメント、PR の説明文、コミットメッセージなどの日本語の文章を書いたり直したりするときは、常に yomiyasu:yomiyasu スキルで推敲してください。コードを直したあとの作業の報告には使わなくてかまいません。
```
1つのリポジトリだけで使うならそのリポジトリの直下の `AGENTS.md` に、すべてのリポジトリで使うなら `~/.codex/AGENTS.md`（`CODEX_HOME` を設定しているときはその場所の `AGENTS.md`）に書きます。書いたあとに始めた会話から有効になります。
コードや設定を直したあとの報告まで推敲させたいときは、「日本語の文章を書いたり直したりするときは、常に yomiyasu:yomiyasu スキルで推敲してください。」とだけ書きます。この書き方にすると、Codex は変数の名前を変えるだけの作業でも、最後の報告を書く前に yomiyasu を読みます。
#### `npx openskills install` で入れたとき
openskills はスキルの一覧を `AGENTS.md` に書き込み、エージェントは `npx openskills read yomiyasu` でスキルを読みます。この入れ方でのスキルの名前は `yomiyasu` です。`npx openskills sync` は `AGENTS.md` の `<skills_system>` から `</skills_system>` までを書き直すので、1行はその外に書いてください。
```text
記事、ドキュメント、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` に書いてください。
#### Claude.ai
ZIP で登録したスキルの名前は `yomiyasu` です。すべての会話で使うなら設定（Settings）の「Instructions for Claude」に、1つのプロジェクトだけで使うならそのプロジェクトの指示（project instructions）に、次の1行を書きます。どちらの置き場所も Claude のヘルプの [Understanding Claude's personalization features](https://support.claude.com/en/articles/10185728-understanding-claude-s-personalization-features) に書かれています。
```text
日本語の文章を書いたり直したりするときは、常に yomiyasu スキルで推敲してください。
```
### 文書の種類と読者
文書の種類と読者は依頼の中で伝えられます。伝えなければ、スキルが本文の形から推定します。
```text
この障害報告を yomiyasu で、専門知識のない社外の利用者向けに読みやすくして。
（ここに修正したい文章を貼り付け）
```
その種類で普通の書き方（表の右の列）は直しません。値は付属ツールの `--doc-type` に渡すものと同じです。
| 値 | 種類 | 直さない書き方の例 |
|---|---|---|
| pr | PR説明 | 変更点の箇条書き |
| article | 技術記事 | なし |
| incident | 障害報告 | 時系列の箇条書き、発生・復旧などの報告の語 |
| proposal | 提案書 | なし |
| minutes | 議事録 | 箇条書き、「〜しました。」の連続、「〜とのこと」 |
| manual | マニュアル | 番号つきの手順 |
| slides | スライド | 箇条書き、体言止めの項目、箇条の「〜のは、A、B、C」 |
| essay | エッセイ・小説 | 読み取れる比喩 |
| formal | 公用文、規程、契約書、仕様書 | 正式な語としての漢語、「〜を行う」 |
| promo | 紹介記事・宣伝文 | 見出しのキャッチコピー、「！」、絵文字 |
| mail | メール・チャット | 宛名、挨拶、結び、署名、クッション言葉 |
| paper | 論文・研究レポート | 慎重な言い方、専門用語、「である」調 |
読者の知識は3段階です。同じ分野の専門家（`expert`）には用語を残し、分野は違うが技術に詳しい人（`informed`）か専門知識のない人（`general`）を指定したときだけ、原文と資料にある説明で言い換えるか、説明を添えます。説明がどこにもない語には説明を作らず、書き手に確かめたい点として返します。
### 書き手と読み手
書き手の立場と読み手との関係（上司、同じチーム、取引先、お客さまなど）を依頼の中で伝えると、yomiyasu はその関係に合わせて本文を直します。
```text
draft.md を yomiyasu で読みやすくしてください。取引先の購買の担当者に送るメールです。
```
上司や社外の相手への依頼は「ご確認ください」「お知らせください」のように、その関係で人がふつう書く敬語にします。書き手が自分でした行為で、ほかの人の行為と読み違えやすい文には、原文にある「私」「弊社」などを主語に補います（原文に一人称がなければ補いません）。頼む中身、期限、選択肢は変えず、担当者やお詫びの文も足しません。関係を伝えなければ、本文の敬語は変えません。
### 文脈から事実を補う
原稿に抜けた数値や条件があると、yomiyasu は原文、依頼、渡された資料、利用者の発言、開いたファイル、コマンドの出力から、同じことを述べた文を探します。根拠の文が見つかったときだけ確度を変えずに補い、見つからなければ本文はそのままにして、読み手が動けなくなる所だけを元の書き手への問いにします。AI 自身の発言や一般の知識は根拠にしません。
書いた日が確かに分かれば、「昨日」のような言い方に括弧で日付を添えます（昨日（10月15日））。
### 完了報告
yomiyasu は推敲した本文のあとに、変えたところと確認の記録を付けます。残したAIっぽいところ、書き手に確かめたい点、事実の確かめが付くのは、書くことがあるときだけです。確認の記録には実行した検査と、`yomiyasu_check.py` の状態の行（`yomiyasu-check:` で始まる行）を写します。本文だけを返すよう頼めば、説明の欄は省きます（検査は同じように行います）。
### 書く前に読ませる使い方
推敲だけでなくAIに文章を書かせる前にyomiyasuを読ませる使い方もあります。[ai-garageの検証記事](https://ai-garage.jp/column/yomiyasu-claude-writing/)（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](./docs/usage.md) にまとめています。
## 付属ツール
文章の表現と書式を見る `yomiyasu_lint.py`、推敲の前後を比べる `yomiyasu_diff.py`、2つをまとめて実行して記録を残す `yomiyasu_check.py` を同梱しています。設定に貼ったときだけ動く任意のフック `yomiyasu_hook.py` もあります。どれも外部ライブラリは要らず、Python の標準ライブラリだけで動きます（テストは Python 3.9 と 3.14 で実行しています）。
検査は見直し候補と変わった箇所を出すだけで、意味が保たれたかどうかや、読みやすいかどうかは判定しません。候補が出た所を直すかどうかは、元の文や文脈と照らし合わせて決めてください。
### 1. yomiyasu_lint.py（表現と書式の検査）
1つの文章について、不自然な比喩動詞、決まり文句、過剰な太字や箇条書き、絵文字、文末コロン、表示されない太字などを、見直し候補として行ごとに出します。2.0.0 からは通常の出力に点数を出しません。点数が読みやすさの合格点のように見えてしまうためです（[点数が出なくなった理由](./docs/tools.md#点数が出なくなった理由)）。
```bash
# 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 を前のキーの名前で読んでいたとき](./docs/tools.md#json-を前のキーの名前で読んでいたとき) にあります。
#### 出力例
```text
表現・書式の検査を実行しました。
見直し候補: 1件
この検査では、意味の保持と読者にとっての分かりやすさは判定していません。
内訳: error 0件、warn 1件、info 0件
L1 [WARN] metaphor_verb: 比喩動詞「壊れる」が検出されました。不自然な比喩動詞であれば、ふだん使う動詞や客観的な表現に書き直してください。ただし、文字どおりの動作や状態変化を表している場合は無理に言い換える必要はありません。
> 単にメッセージを流すだけでは、背後でデータが静かに壊れます。
```
### 2. yomiyasu_diff.py（推敲の前後の比較）
推敲の前と後を比べ、変わった箇所をすべて出します。数値、否定、「が」「を」の入れ替え、文の種類（伝聞、推量、依頼など）が変わった所は、意味が変わる恐れとして先に示します。
```bash
# 原文と推敲後を比べる
python3 scripts/yomiyasu_diff.py 元の文.md 書き直した文.md
# 数値・否定・入れ替え・文の種類の変化があれば終了コード1を返す
python3 scripts/yomiyasu_diff.py 元の文.md 書き直した文.md --fail-on=meaning-risk
```
#### 出力例
「田中が佐藤を承認した。」と「設定は3日ごとに保存します。」の2つの段落を、「佐藤が田中を承認した。」と「設定は30日ごとに保存しません。」に書き換えると、次のように出ます。
```text
差分の検査を実行しました。
状態: 変更あり（2か所）。見直し候補 3件、うち意味が変わる恐れ 3件
全文差分は変わった箇所を示すだけで、意味が同じだという証明ではありません。この検査では、意味の保持と読者にとっての分かりやすさは判定していません。
■ 意味が変わる恐れ（3件。原文と資料に照らして確かめる）
- 「が」「を」などが入れ替わった（1行目）: 田中 が→を、佐藤 を→が
元: 田中が佐藤を承認した。
後: 佐藤が田中を承認した。
- 数値が変わった（3行目）: 3日 → 30日
元: 設定は3日ごとに保存します。
後: 設定は30日ごとに保存しません。
- 否定の有無が変わった（3行目）: 保存します → 保存しません
元: 設定は3日ごとに保存します。
後: 設定は30日ごとに保存しません。
（このあとに全文差分が続きます）
```
### 3. yomiyasu_check.py（検査をまとめて実行して記録を残す）
最終稿に lint を、原文と最終稿に diff をまとめて実行し、記録を残します。スキルは書き直したあとに `run` を実行し、返す直前に `verify` で、最終稿が検査したものと同じかを記録と照らし合わせます。
```bash
# 原文と最終稿を検査する（資料があれば --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 の管理には入りません。実行漏れを見つけるための記録なので、合格の証明にはなりません。
### 4. yomiyasu_hook.py（任意のフック）
Claude Code か Codex の設定に貼ったときだけ動く補助のスクリプトです。このフックは登録された原稿について、AI が返答を終える前と投稿の前に、最終稿が検査の記録と合うかを確かめます。入れなくても yomiyasu はこれまでどおり使えます。
出力の読み方、オプション、終了コード、フックの入れ方は [docs/tools.md](./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](./docs/limitations.md) にまとめています。
## リポジトリ構成
```text
.
├── .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文章に関する議論、先行調査、学術論文、既存の文体調整ツールを参考にしました。各資料から学んだ点を紹介します。スキルの具体的な編集ルールや数値の目安は独自に決めたものであり、引用した研究がその効果を保証するものではありません。
### 1. コミュニティの先行調査
- [AI臭い文章とは何なのか（Speaker Deck）](https://speakerdeck.com/nasuvitz/ai-kusai-bunshou-toha-nanina-no-ka)（nasuvitz氏）
AI特有の読みにくさは単語選び以上に統語構造（SVOCM）の破綻や非生物主語に起因するという指摘を参考にしました。「誰が何をどうした」を1文ごとに完結させる原則の策定に役立てています。
- [Qiitaの7万記事を数えてみた話](https://nyosegawa.com/posts/qiita-writing-before-after-ai/)（逆瀬川氏）
AI普及後に生じた形式のインフレ（太字や箇条書きの急増）と手順の希薄化を定量的に示した調査です。技術記事における太字頻度やリスト比率の制限、手順復元指針の根拠として活用しました。
- [Gemini 3.8 Flashこそ日本語執筆の救世主だった（X）](https://x.com/yugen_matuni/status/2095293937686900995)（まつにぃ氏、@yugen_matuni）
自然な助詞配置と主述の結びつきを持つ日本語構造に着目する契機となりました。その統語特性を分析し、プロンプト指示として定式化しています。
- [AI語に親しむ](https://ktrmnm.jp/blog/2026-08-29-what-is-ai-ism-jp/) / [AI語を受容する](https://ktrmnm.jp/blog/2026-08-29-accept-ai-ism/)（ktrmnm氏）
AI特有の比喩動詞や直訳調の構文パターン分析を参考にしました。比喩動詞の技術的操作化や、不要な否定対比の平文化ルールに反映させています。
- [AIの作文はなぜつまらないのか？](https://sizu.me/laiso/posts/c1h12v4v0zr5) / [なぜAI臭さを消したいのか？](https://sizu.me/laiso/posts/mcerekex7091)（laiso氏）
過剰な包装紙（前置フィラーや定型クロージング）への批評や、型を押し付けることへの注意点を参照しました。前置きの排除や、生活実感・身体性を残す方針に活かしています。
### 2. 日本語処理・テキスト平易化に関する学術研究
- Yamashita et al., [Evaluation of Document-Level Text Simplification in Japanese](https://aclanthology.org/2026.lrec-1.85/), LREC 2026
必要情報、意味保持、文の平易さを分けて評価する設計の参考としました。
- Jeong, Park & Yu, [Right at My Level: A Unified Multilingual Framework for Proficiency-Aware Text Simplification](https://aclanthology.org/2026.acl-long.1086/), ACL 2026
原文内容の脱落と、根拠のない情報付加を別々に検証するアプローチを参考にしています。
- Ide et al., [Towards Automated Lexicography: Generating and Evaluating Definitions for Learner's Dictionaries](https://arxiv.org/abs/2601.01842), 2026
局所的な問題箇所の特定と修正を通じて、文全体の整合性を保つ手法の参考にしました。
- Nohejl et al., [A Japanese Dataset and Efficient Multilingual LLM-Based Methods for Lexical Simplification and Lexical Complexity Prediction](https://www.jstage.jst.go.jp/article/jnlp/32/4/32_1129/_article), 自然言語処理 32巻4号
語の平易化における文法性と意味保持のバランスを検討する基礎としています。
- 八木ほか, [多文化共生を目指した『やさしい日本語』における大規模言語モデルのプロンプトデザインの検証](https://www.jstage.jst.go.jp/article/hcd/22/1/22_9/_article/-char/ja), 人間中心設計 22巻1号
プロンプト内の例示設計とモデルの挙動特性に関する知見を参考にしました。
- Chen, Yue & Davidge, [Comparing generative AI with native speakers in terms of request expressions in Japanese](https://link.springer.com/article/10.1007/s44217-025-00920-w), Discover Education 2025
相手との距離感を保ち、主語や敬語を一律に過剰付加しない判断の参考にしています。
- Zaitsu et al., [Stylometry can reveal artificial intelligence authorship, but humans struggle](https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0335369), PLOS One 2025
AIらしさの検出と読みにくさの判定を区別して扱う論理的根拠としました。
- 三浦・久保山, [生成AIは文体を均質化するのか？](https://www.jstage.jst.go.jp/article/pjsai/JSAI2026/0/JSAI2026_5YinA18/_article/-char/ja/), 人工知能学会 2026 / 林・相澤, [LLMによる日本語生成におけるモデル固有表現パターンの分析](https://www.anlp.jp/proceedings/annual_meeting/2026/pdf_dir/B9-17.pdf), 言語処理学会 2026
文体の画一化を避け、書き手らしさや文末の自然な交差を尊重する視点を学びました。
- 李・長谷部, [ChatGPTによる日本語ニュースの平易化 生成AIと『やさしい日本語』](https://www.jstage.jst.go.jp/article/mathling/34/8/34_563/_article/-char/ja), 計量国語学 34巻8号
数値上の単純化と、人間にとって自然な編集の差異を踏まえるための指針としています。
- 書式および語彙の偏りに関する研究群（[ACL 2025 書式バイアス研究](https://aclanthology.org/2025.acl-long.1308/), [COLING 2025 語彙偏り研究](https://arxiv.org/abs/2412.11385), [Miklian et al. 2026](https://arxiv.org/abs/2606.12073)）
強調やリストへの評価偏向、英語直訳思考の影響を理解するための補助資料として活用しました。
### 3. 先行する文体調整スキル群
- [natural-japanese](https://github.com/coji/natural-japanese), [stop-ai-slop-jp](https://github.com/iKora128/stop-ai-slop-jp), [japanese-tech-writing](https://gist.github.com/k16shikano/fd287c3133457c4fd8f5601d34aa817d), [cognitive-rhythm-writing](https://gist.github.com/k16shikano/eb2929f13ed19c97188393d297be8432), [humanizer](https://github.com/blader/humanizer)
読者に応じた編集、専門用語や条件の保持、文の長さや区切り方などを参考にしました。各作者に感謝します。
### 4. 文章の構造を点検するための参考書籍
- 千早耿一郎『[悪文の構造 機能的な文章とは](https://www.chikumashobo.co.jp/product/9784480512635/)』
公開図解と確認した本文を参考に、主語・述語・修飾先などの関係を分析し、書き直した後も照合する点検を加えました。意味保持の既存ルールと組み合わせた独自の指示であり、本書の全手順を再現するものではありません。
### 5. 利用者による検証と説明関係の点検
- [「AIっぽい文章を直すスキル」に、うちの日記を通したら、ほとんど直されなかった](https://note.com/discovery_lab/n/nff4ed74de854)
自然な文を不要に変更しないことと、保存済みサンプルの意味を原文と照合することを、検証項目として見直しました。
- [流行りの「AI日本語推敲スキル」を使う前にやっておきたいこと](https://note.com/nice_loris4267/n/n71e1f0de1474)
説明すると述べた対象や関係が、本文から読み取れるかを確認する観点を参考にしました。
## 作者・宛先
開発者: 大賀 愛一郎（oga_aiichiro）@ALGO ARTIS
宛先: [@oga_aiichiro](https://x.com/oga_aiichiro)
※ 本スキルおよび本リポジトリは個人の研究・創作物であり、所属企業の公式プロダクトや見解を代表するものではありません。
## ライセンス
本リポジトリのコードおよびドキュメントは [MIT License](./LICENSE) のもとで公開しています。同梱しているUnicode由来データの著作権・許諾通知は [UNICODE-LICENSE.txt](./UNICODE-LICENSE.txt) に記載しています。検証や引用に用いた外部資料の権利は各著作者に帰属し、それぞれの利用規約（CC BY 4.0等）に従うものとします。
## 紹介・解説について
yomiyasuを記事や動画、SNS、勉強会などで紹介・解説していただけると嬉しいです！
作者への連絡や許可はいりません。
ただし、yomiyasuは無料で公開しているオープンソースのスキルで、正式な配布元はこのリポジトリだけです。
yomiyasuを紹介・同梱する有料の教材や情報商材、yomiyasuとの関連をうたうトークンや暗号資産に、作者は一切関わっておらず、収益も受け取っていません。
yomiyasuは、多くの先行研究や公開された知見をもとに作っています。
そのため作者は、これまでもこれからも、yomiyasuそのもので利益を得るつもりはありません。
## 最後に
このREADMEの「これは何？」から「限界」までの節は yomiyasu で推敲しています。README の全体は付属の `yomiyasu_lint.py` に通しています。
