yomiyasu（よみやす）

English

これは何？

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

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

Claude Code、Codex、CursorをはじめとするAIコーディング環境に読み込ませて使用してください。本体を入れられない環境のために、本体から作った yomiyasu-mini と yomiyasu-pocket も公開しています（本体を入れられない環境では）。

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

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

Built with curiosity at ALGO ARTIS

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

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

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

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

背景と課題

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

AIが書いた日本語には、たとえば次のような形がよく出ます。

1. 主述関係の曖昧さと非生物主語
   誰が何をどうするのかが省略されたまま、概念や道具が比喩的な動詞（壊れる、倒す、効くなど）と結びつき、読み手が文脈を補って読む必要があります。
2. 形式の偏重と情報密度の低下
   太字や箇条書きが増える一方で、手順やコードの仕組みといった中身は抽象的に書かれ、文章の量に比べて実際の情報が少なくなります。
3. 間を作るだけの読点と決まった形
   短い主題のすぐあとに間を作るだけの読点を置く、箇条書きの先頭に太字のラベルとコロンを付ける、否定と肯定を2文に分けて対比する、といった形です。

こうした所を元の意味を保ったまま直すために、yomiyasu は指示書（SKILL.md）と、直す前と後を比べて意味が変わる恐れのある所を出す検査のツールをまとめています。

本スキルのアプローチ

元の意味を保つことを最優先にして、読み違えやすい箇所や、文の関係を追うのに負担がかかる箇所を直します。自然に読める部分は残すよう SKILL.md に書いています。

7つの変換原則

1. 主述・修飾・条件の点検
   主語と述語、修飾語と掛かる先、指示語と指す対象を対応づけます。条件・例外・否定・並列・数量・順序も、書き直す前後で同じように追えるか確かめます。主体や対象を補うのは、原文や提供文脈から確定できる範囲に限ります。
2. 文の働きと文体の保持
   文ごとに評価・説明・依頼・予定・感想の働きを区別し、働きに合わない文末だけを直します。完了した変更作業、現在の動作や方針、今後の予定を時制と役割に合わせて書き分け、語尾を散らすこと自体を目的にしません。常体・敬体は変更の指定がなければ保ち、技術記事という分野だけを理由に敬体へ変えません。
3. 擬人化の整理
   道具や概念に感情や意志を持たせた表現を直します。道具やシステムの客観的な動作を述べる非生物主語は残します。
4. 比喩を平易な言葉へ
   壊れる、倒す、効く、溶かすなどは、何がどう変わったかを書くか、ふだんの言い方に直します。元の含みと意味の広さは保ち、原文より強い確度の語は足しません。慣用句は残します。
5. 前置き・否定対比の役割の確認
   否定対比（AではなくB）を肯定文にするのは、Aを外しても主張が変わらないときだけです。誤解を正す否定は残し、否定と肯定を2文に分けた形は1文にまとめます。理由・対比・結論を示す前置きは残します。
6. 情報を勝手に足さない
   主張・比重・言い切りの強さ・文の働きを保ち、原文にない動作主・原因・条件・数値・例・専門用語を推測で足しません。決まりを「契約」、原文を「正本」と大げさに呼ぶ場合は役割に合う語へ直し、正式な名称や専門用語としての用法は保ちます。意味を確定できない箇所は、原文にある未確定の状態や既知の動作を本文に残した暫定文とし、推敲の理由や確認事項は本文の後に添え、読者向けの本文には入れません。
7. 文長・読点・装飾の調整
   文が長いことだけを理由に文を分けません。短い主語や主題、目的語のすぐあとに置いて間を作るだけの読点は外し、誤読を防ぐ読点、並んだ語句を区切る読点、条件や理由の切れ目の読点は残します。箇条書きの先頭のラベルとコロンは、値の項目や、物や作業の名前に説明が続く項目では残します。分類の語、出来事を名詞にまとめた語、短い述語のラベルは、外して説明と1文にまとめます。ラベルを文に入れて条件や働きが変わるときは、ラベルとコロンを残します。絵文字やダッシュなどの装飾記号は外します。文書の種類のファイルに従って、メール・チャットや宣伝文で書き手が気持ちを表した絵文字と小説のダッシュは残します。英数字の前後の空白は一律に足したり消したりしません。

バージョンごとの変更は CHANGELOG.md にあります。

Before → After 例

2.0.0 のスキルで AI の文章を推敲した例です。Claude Code（Claude Opus 5.5）に「draft.md を yomiyasu で読みやすくして、結果を out.md に書いてください。」とだけ頼み、1回目の出力をそのまま載せています。どちらも開発の途中で使った原稿に対する 2.0.0 の出力で、今のバージョンで測った数は docs/limitations.md にあります。

例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（推奨）

# 新規インストール
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 も付けます）。

npx skills add nanaism/yomiyasu -g -a grok

2. gh skill install

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

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

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

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

3. npx openskills install

# 新規インストールと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 プラグイン

/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を再起動してください。

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

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

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

6. Codex で使うリポジトリに置く（Codex Cloud など）

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

(
  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 は、移したときに表示された名前に替えてください。

rm -rf .agents/skills/yomiyasu
mv .agents/yomiyasu.bak-20261024-153000 .agents/skills/yomiyasu

移したフォルダは git に入れず、要らなくなったら消してください。

この置き方では Codex がスキルを yomiyasu という名前で一覧に載せます。呼ぶときは「/yomiyasu」とだけ送るか、依頼の文に「yomiyasu で」と書いてください。一覧の名前どおり $yomiyasu と書いても呼べます。3.0.1 までに入れたフォルダをそのまま使っている場合は、名前が yomiyasu:yomiyasu のままなので、$yomiyasu:yomiyasu と書きます。3.1.0 以降に更新したときに書き換える所と、名前が yomiyasu にならない置き方は、docs/usage.md にまとめています。コピーしたフォルダは自動では新しくなりません。最新にするには