<p align="center">
<img src="./assets/yomiyasu_logo.jpg" alt="yomiyasu logo" width="700">
</p>
# yomiyasu（よみやす）
[](./LICENSE)
[](https://github.com/nanaism/yomiyasu/releases)
[English](./README.en.md)
## これは何？
『**yomiyasu（よみやす）**』はAIが生成した日本語の不自然な比喩、曖昧な主述関係、不要な装飾を直し、読みやすい文章に整えるスキルです。
主に技術記事、設計書・仕様書、PR説明文、社内レポートなどの実務的な文章を対象として設計されています。
Claude Code、Codex、CursorをはじめとするAIコーディング環境に読み込ませて使用してください。本体を入れられない環境のために、本体を短くした yomiyasu-mini と yomiyasu-pocket も公開しています（[本体を入れられない環境では](#本体を入れられない環境では)）。
開発の背景、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文にまとめます。過剰な装飾記号を整理し、英単語や数値の前後の空白は元の書式や指定されたスタイルを保ちます。残す太字は表示される形に整えます。
バージョンごとの変更は [CHANGELOG.md](./CHANGELOG.md) にあります。
## 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か所に配置しています。
Grok Build に入れるときは、`-a grok` を付けます。`-g` を付けるとユーザーの `~/.grok/skills/yomiyasu/`（`GROK_HOME` を設定しているときはその下の `skills/`）に、付けないと作業するリポジトリの `.grok/skills/yomiyasu/` に入ります。更新は上と同じ `npx skills update yomiyasu` です（`-g` で入れたときは `-g` も付けます）。
```bash
npx skills add nanaism/yomiyasu -g -a grok
```
### 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にはスキル本体、参照文書、検査スクリプト、ライセンスだけを入れています。
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
(
set -e
tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT
git clone --depth 1 https://github.com/nanaism/yomiyasu "$tmp/yomiyasu"
mkdir -p .agents/skills
if diff -r "$tmp/yomiyasu/skills/yomiyasu" .agents/skills/yomiyasu >/dev/null 2>&1; then
echo "Already up to date: .agents/skills/yomiyasu"; exit 0
fi
if [ -e .agents/skills/yomiyasu ] || [ -L .agents/skills/yomiyasu ]; then
backup=.agents/yomiyasu.bak-$(date +%Y%m%d-%H%M%S)
if [ -e "$backup" ]; then echo "$backup already exists. Run this again in a second." >&2; exit 1; fi
mv .agents/skills/yomiyasu "$backup"
echo "Moved the previous folder to $backup"
fi
cp -R "$tmp/yomiyasu/skills/yomiyasu" .agents/skills/yomiyasu
echo "Installed .agents/skills/yomiyasu"
)
```
このコマンドは最新版を一時フォルダに取り出してから `.agents/skills/yomiyasu/` にコピーし、最後に一時フォルダを消します。前の `.agents/skills/yomiyasu/` があって中身が最新版と違うときは、消さずに `.agents/yomiyasu.bak-日付-時刻/` に移してからコピーします。中身が最新版と1字も違わなければ、何も変えません。入れたあとにフォルダの中のファイルが変わったり増えたりしたとき（Finder の `.DS_Store` など）は、同じバージョンでも移します。取り出しに失敗したときは、前のフォルダをそのままにして止まります。移したフォルダの置き場所は、Codex がスキルを探す `.agents/skills/` の外です。新しいバージョンに入れ直すたびに、移したフォルダが1つ増えます。
コマンドが英語で出す文は、`Installed .agents/skills/yomiyasu` が入れ終えたこと、`Moved the previous folder to …` が前のフォルダを移した先、`Already up to date: .agents/skills/yomiyasu` が中身が最新版と同じで何も変えなかったことを表します。`… already exists. Run this again in a second.` が出たら、同じ名前の移し先がすでにあるので、1秒おいてからもう一度実行してください。
前のフォルダに戻すときは、入れたフォルダを消して、移したフォルダを元の名前に戻します。`20261024-153000` は、移したときに表示された名前に替えてください。
```bash
rm -rf .agents/skills/yomiyasu
mv .agents/yomiyasu.bak-20261024-153000 .agents/skills/yomiyasu
```
移したフォルダは git に入れず、要らなくなったら消してください。
この置き方では Codex がスキルを `yomiyasu:yomiyasu` という名前で一覧に載せます。呼ぶときは「/yomiyasu」とだけ送るか、依頼の文に「yomiyasu で」と書いてください。一覧の名前どおり `$yomiyasu:yomiyasu` と書いても呼べます。コピーしたフォルダは自動では新しくなりません。最新にするには、同じコマンドをもう一度実行してください。
### スキルのフォルダの中を書き換えたとき
入れたスキルのフォルダの中のファイルを書き換えても、入れ方によっては、更新するとフォルダの中身が入れ替わり、書き換えた所が残りません。プロジェクトに合わせた語や使い方の決まりは、スキルのフォルダの外の `.yomiyasu-words/`、`CLAUDE.md`、`AGENTS.md` に書いてください。
### 本体を入れられない環境では
SKILL.md の字数やファイルの数に上限がある環境や、スキルを読み込めず指示欄に貼るしかないAIのために、本体を短くしたものを2つ、別のリポジトリで公開しています。本体を読み込める環境では、本体をおすすめします。
- [yomiyasu-mini](https://github.com/nanaism/yomiyasu-mini): SKILL.md を18,000字以下にしたスキルです。Microsoft 365 Copilot の宣言型エージェントのように、スキルの大きさに上限がある環境向けです。意味が変わる恐れの検査（本体の diff と同じ結果）を含みます。
- [yomiyasu-pocket](https://github.com/nanaism/yomiyasu-pocket): AIの指示欄に貼って使う、400〜500字の指示文です。メールの作成画面のAIやチャットのカスタム指示のように、スキルを読み込めない所向けです。スキルの仕組みと検査は使いません。
### 他の日本語校正スキルとの干渉について
他の日本語校正スキルと併用すると、指示が食い違う場合があります。出力が乱れる場合は、類似スキルを一時的に無効にして使用してください。
## 使い方
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 で読み込みます）。コードを直したあとの作業の報告には使わなくてかまいません。
```
更新したら、`npx openskills update yomiyasu` のあとに `npx openskills sync` も実行してください。スキルの description は sync のときに `AGENTS.md` に写されるので、sync するまで、エージェントは更新する前の 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 で、専門知識のない社外の利用者向けに読みやすくして。
（ここに修正したい文章を貼り付け）
```
種類は次の13種類で、その種類で普通の書き方（表の右の列）は直しません。値は付属ツールの `--doc-type` に渡すものと同じです。
| 値 | 種類 | 直さない書き方の例 |
|---|---|---|
| pr | PR説明 | 変更点の箇条書き |
| article | 技術記事 | なし |
| incident | 障害報告 | 時系列の箇条書き、発生・復旧などの報告の語 |
| proposal | 提案書 | なし |
| minutes | 議事録 | 箇条書き、「〜しました。」の連続、「〜とのこと」 |
| manual | マニュアル | 番号つきの手順 |
| slides | スライド | 箇条書き、体言止めの項目、箇条の「〜のは、A、B、C」 |
| essay | エッセイ・小説 | 読み取れる比喩 |
| formal | 公用文、規程、契約書、仕様書 | 正式な語としての漢語、「〜を行う」 |
| promo | 紹介記事・宣伝文 | 見出しのキャッチコピー、「！」、絵文字 |
| mail | メール・チャット | 宛名、挨拶、結び、署名、クッション言葉 |
| paper | 論文・研究レポート | 慎重な言い方、専門用語、「である」調 |
| script | 台詞・脚本 | 台詞の口調と言い回し、台詞の中の文と文の間の「。」、ト書き |
読者の知識は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-を前のキーの名前で読んでいたとき) にあります。
#### プロジェクトの語の一覧
git の最上位（git の外では作業ディレクトリ）に `.yomiyasu-words/` を置き、`allow.txt`（直さない語）と `flag.txt`（指摘を出して見直す語）に1行に1語ずつ書くと、lint、diff、check、フックが同じ一覧を読みます。`#` で始まる行と空の行は読み飛ばします。allow.txt の語は、直訳語などの指摘と、比喩動詞、直訳の語、決まり文句の候補から外れ、外した件数が出力と JSON（`context.words`）に出ます。flag.txt の語には `project_term` の指摘が出ます。リポジトリに入れてチームで共有する前提のファイルで、状態フォルダ `.yomiyasu/` とは別の場所に置きます。`--words フォルダ` で場所を指定でき、`--no-words` を付けると読みません。詳しくは [docs/tools.md](./docs/tools.md#プロジェクトの語の一覧) にあります。
#### 出力例
```text
表現・書式の検査を実行しました。
見直し候補: 1件
この検査では、意味の保持と読者にとっての分かりやすさは判定していません。
内訳: error 0件、warn 1件、info 0件
L1 [WARN] metaphor_verb: 比喩動詞「壊れる」が検出されました。不自然な比喩動詞であれば、ふだん使う動詞や客観的な表現に書き直してください。ただし、文字どおりの動作や状態変化を表している場合は無理に言い換える必要はありません。
> 単にメッセージを流すだけでは、背後でデータが静かに壊れます。
```
### 2. yomiyasu_diff.py（推敲の前後の比較）
推敲の前と後を比べ、変わった箇所をすべて出します。数値、否定、「が」「を」の入れ替え、文の種類（伝聞、推量、依頼など）が変わった所は、意味が変わる恐れとして先に示します。原文にない人や担当を、主語として、または知らせる・頼む相手として足した文も、別の節にまとめて示します（2.4.0 から）。
```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 の管理には入りません。同じリポジトリをほかの OS ユーザー（Codex のサンドボックスなど）も使うときは、`YOMIYASU_STATE_DIR` でユーザーごとに別の場所を指定してください（[docs/tools.md](./docs/tools.md)）。実行漏れを見つけるための記録なので、合格の証明にはなりません。
### 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/ # 文書の種類ごとの注意（13種類）
│ ├── 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)）
強調やリストへの評価偏向、英語直訳思考の影響を理解するための補助資料として活用しました。
- 蔡盛植, 日本語動詞連用形への構文論的アプローチ —『動詞連用形』と『連用形名詞』との相関関係を中心に—, 日本研究 第21集, 2014
他動詞の連用形を1語だけ名詞にした語を「の」で受ける形と、成り立つ形（複合語、複合動詞から来た語、「お」を付けた形、意味が変わって定着した語）の線引きを、2.3.0 の `renyo_noun` の規則に使いました。
### 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` に通しています。
