# 使い方の詳細

README の[使い方](../README.md#使い方)の節を詳しく書いたものです。

## 「/yomiyasu」とだけ送ったとき

「/yomiyasu」とだけ送ったときは、直前の返答で書いた本文か、作業フォルダの直下に指示のファイル以外の `.md` か `.txt` が1つだけあればそれを推敲します。ファイルを選んで推敲したときは、最終稿を同じフォルダにまだない名前で保存し、原文のファイルは書き換えません（作業フォルダに原稿を1つ置いて Codex で試した8本では、1.1.2 は8本とも「文章を貼ってください」と返し、2.0.0 は8本とも推敲しました）。

## 文書の種類と読者の指定

文書の種類と読者は、依頼の中で伝えられます。伝えなければ、スキルが行き先と本文の形から推定します。推定に自信がなく、答えによって直し方が変わり、問い返せる場面では、書き直す前に1回だけ確かめます。本文だけを返す指定、一回きりの実行、ほかのスキルの途中、「質問しないで」と頼まれたときは確かめず、種類を決めないまま、種類ごとの規則を当てずに直します。

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

種類ごとに、その種類で普通な書き方には当てない規則があります。値は付属ツールの `--doc-type` と同じです。

| 値 | 種類 | 当てない規則 |
|---|---|---|
| pr | PR説明 | 過剰な箇条書き（変更点、確認したこと） |
| article | 技術記事 | なし |
| incident | 障害報告 | 過剰な箇条書き（時系列）、硬い漢語（発生、復旧などの報告の語） |
| proposal | 提案書 | なし |
| minutes | 議事録 | 過剰な箇条書き（太字のラベルを含む）、同じ文末の連続（〜しました。の連続）、伝聞の「〜とのこと」 |
| manual | マニュアル | 過剰な箇条書き（番号つきの手順） |
| slides | スライド | 過剰な箇条書き（太字のラベルを含む）、数の宣言、繰り返すだけの「まとめ」、体言止めの項目での主語の抜けと文末、箇条の「〜のは、A、B、C」、他動詞を読点で並べる形 |
| essay | エッセイ・小説 | 読み取れる比喩（エッセイでも「効く」の類は直す）、小説のコピー調とダッシュ、見出しの比喩、他動詞を読点で並べる形 |
| formal | 公用文、規程、契約書、仕様書 | 硬い漢語（正式な語）、「〜を行う」「〜することができる」の外枠 |
| promo | 紹介記事・宣伝文 | 見出しのキャッチコピー、「！」と絵文字、勢いのある語と強める語、見出しの比喩、他動詞を読点で並べる形 |
| mail | メール・チャット | 宛名、挨拶、結び、署名、クッション言葉の削除、敬語の度合いと口語の書き換え、絵文字の削除 |
| paper | 論文・研究レポート | ぼかした語の具体化（慎重な言い方）、専門用語と論文調（本研究では）の言い換え、長い文の分割、名詞化の言い換え |
| script | 台詞・脚本 | 台詞の口調、言い回し、短い文を重ねる形（台詞の最後の「。」だけを外す。句点の指定があれば外さない）、見出しの比喩、他動詞を読点で並べる形 |

エッセイ・小説では、何を何に例えたかが読み取れる比喩を書き手の個性として残し、主語と述語が成り立たず連想もできない比喩を直します。紹介記事・宣伝文では、「！」（同じ段落に3つ以上あっても）、評価の語を短く重ねる型（安い。うまい。早い。）、同じ褒め言葉の繰り返しを残し、根拠のない誇張は書き換えずに書き手へ根拠を尋ねます。どちらも、書き手の表現を残したときは、そう判断したことを本文とは別に1行で伝えます。

メール・チャットで残すのは、宛名、挨拶、結び、署名、クッション言葉、敬語の度合い、チャットの口語で、直すのは敬語の誤りなどです。論文・研究レポートでは、慎重な言い方を断定に変えず、引用の書き方、数値、専門用語、「である」調を残します。

読者は3段階です。expert（同じ分野の専門家）には用語を残して説明を足しません。informed（分野は違うが技術に詳しい人）と general（専門知識のない人）では、その読者を指定されたときだけ、原文と資料にある説明で言い換えるか添えます。説明が原文と資料にないときは、説明を作らずに語を残し、「ここに説明が必要です」と書き手に返します。見出しと節の数と順は、どの種類と読者でも変えません。

種類を決めないときは、種類ごとの規則を当てず、1.1.2 からある分野別の指針（技術記事 tech、業務文書 business、エッセイ essay）を使います。

## 書き手と読み手の指定

書き手の立場と、読み手との関係（上司、同じチーム、取引先、お客さまなど）は、依頼の中で伝えられます。

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

関係を伝えたときだけ、本文を次のように直します。

- 上司と社外の読み手には、読み手への依頼と読み手の行為を尊敬語に、社外の読み手に向かう書き手の行為を謙譲語に上げます。同じ動詞に「お・ご」を付けた形のほか、その関係で人がふつう書く言い回しも使います（来てください → お越しください、変更があれば言ってください → 変更があればお知らせください）。説明や手順を頼む「教えてください」は、「ご教示ください」か「教えていただけますか」にします。頼む中身、期限、選択肢、頼みの数は変えません。二重敬語と、原文にない「させていただく」は作りません。
- 読み手が社外の特定の相手なら、読み手に向けた言い回しとお詫びの文も、その関係で人がふつう書く形にします（申し訳ありません → 申し訳ございません、もっと → これまで以上に、気をつけます → 努めます）。作業を述べる文（直しました）は丁寧語のままです。
- 書き手が自分でした行為で、主語がなくほかの人の行為と読み違えうる文には、原文にある書き手の一人称（私、弊社など）を主語に補います（3か所まで）。原文に一人称がなければ補いません。
- 書き手の立場で知りえない事情、立場に合わない断定、関係に合わない言い方（お客さま宛ての「僕」など）は、本文を変えずに「書き手に確かめたい点」で知らせます（2点まで。ほかの確かめたい点の3点とは別に数えます）。
- 担当者、説明、挨拶、お詫びは足しません。エッセイと紹介記事・宣伝文では、書き手と読み手を伝えても本文を変えません。敬語を下げるのは、頼まれたときだけです。

伝えないときは、宛名や署名から読み手を推定しても、本文も知らせも変えず、推定した読み手を、変えなかった理由として返答に書くこともしません。確認の記録に、推定した値を1行だけ書きます。

## 文脈から事実を補うとき

推敲する原稿に、中身や値の書かれていない所があると、スキルは同じことを述べた根拠の文をこの会話と資料から探し、根拠があるときだけ補います。

- AI が自分で書いた原稿では、読み手が動く値（期限、数量、バージョン、手順の値）と、原因・結果・済んだかどうか・担当を述べた文を、合わせて10個まで同じ材料と照らします。
- 根拠にするのは、原文、依頼、資料、この会話の利用者の発言、この会話で開いたファイル、コマンドの出力（テストの結果、ログ、`git diff` など）です。AI 自身やほかの AI の発言、会話のまとめ、一般の知識、ウェブの内容は使いません。
- 値が合うだけでは補いません。補う値が何の値か（対象、条件、時点）まで根拠の文に書かれているときだけです。「予定」「かもしれない」のような確度は、そのまま書きます。
- 補う・直すは合わせて5件までで、今の文の中で補い、新しい文や段落は作りません。説明、例、効果、原因、気持ちは、材料にあっても足しません。要約や短くする依頼では補いません。
- 原稿の値が利用者の渡した資料と食い違い、資料の値が1つに決まるときは、資料に合わせて直します。会話やファイルの値で直すのは、AI が自分で書いた値で、原稿の値に出典がなく、材料の値が1つに決まるときだけです。
- 読みに行くファイルは原稿か会話に名前の出たものを3つまでで、読むだけです。`.env` や秘密鍵のような認証情報らしいファイルは開きません。変更の説明の原稿で、会話に差分がないときだけ、読むだけの `git diff` か `git log -p -1` を1回動かします。
- 原文が省いたと示している所（詳細は省きます、別途お知らせします）、ぼかした数や時期（一部の利用者、近日中に）、「未定」「調査中」は、補わず、問いもしません（ぼかした語のせいで読み手が誤って読む恐れのあるときだけ、1回問います）。社外向けか分からない文書には、出典があっても、内部のホスト名、メールアドレス、個人の名前、未公開の数値などを入れません。
- 「昨日」「先週」のような相対の日付には、書いた日が確かに分かるときだけ、括弧で日付を添えます（昨日（3月4日））。書いた日が分かるのは、原稿に書いた日の行があるときと、依頼や会話から原稿を今日書いたと分かるときです。今日の日付はホストが知らせる日付を使います。推測では添えず、曜日も足しません。エッセイ・小説と紹介記事・宣伝文では添えません。
- エッセイ・小説、紹介記事・宣伝文、公用文・規程・契約書・仕様書、論文・研究レポートでは、会話やファイルから補いません。本文だけを返す指定、「確かめずに」と頼まれたとき、Python を実行できないときも補いません。
- 根拠がなければ本文を変えず、読み手が動けない所だけを問いにします。問いは3つまでで、元の書き手（人か別の AI）にそのまま貼って渡せる形にし、候補の値は挙げません。答えが来たら、最初の原稿と、前の問いと答えをまとめて渡してください。前の往復を覚えていない呼ばれ方（子エージェントなど）では、そうして渡したときにだけ続きを進められます。
- 補いに使った根拠の文は最終稿と同じフォルダに「最終稿の名前.material.txt」として一字も変えずに写し、`yomiyasu_check.py run` に `--material` で渡します（[資料の出典と事実の穴の候補](./tools.md#資料の出典と事実の穴の候補)）。

## 完了報告

書き直した本文のあとには「変えたところ」（5点まで）、「残したAIっぽいところ」、「書き手に確かめたい点」（3点まで。多いときは本文の意味への影響が大きいものから選び、残りの数を「ほかに N か所」と添えます）、「事実の確かめ」、「確認の記録」が付きます。「事実の確かめ」は材料から補った事実、直した事実、材料と照らした値、確かめられなかった点のどれかがあるときだけ付く節で、補った語句ごとに出典の場所と根拠の文を書き、最後に「元の書き手に渡す問い」をまとめます。確認の記録は実行した検査と、実行しなかった検査とその理由を分けて書き、run の出力の「見直し候補: 原文 N件 → 最終稿 M件」の件数を「（件数は点数ではない。増減は読みやすさの良し悪しを示さない）」と添えて写し、最後に `yomiyasu_check.py` の状態の行（`yomiyasu-check:` で始まる行）を写したものです。Python を実行できない環境では、スキルは検査の代わりに原文と最終稿を読み比べ、状態の行を `yomiyasu-check: not_run reason=no_python` のように書きます。本文だけを返すよう頼んだときは、確認の記録も説明の欄も、区切りの線のあとの注記も付けません（検査は同じように行います）。

## 資料から新しく書かせるとき

2.0.0 からのスキルに資料から新しく書かせると、スキルは `yomiyasu_check.py run` に資料を `--material` で渡し、最終稿の数値、名前、語、確度の語を資料と照らします。資料にない数値や名前は候補に出ます（新規作成のモード）。

2.0.2 からは名前を出さずに書かせると yomiyasu は使われません。「notes.md をもとに記事を書いて、最後に yomiyasu で推敲して」のように、書かせる依頼にも名前を入れてください。Claude Code 2.1.296 で、プラグインで入れた形とプロジェクトに置いた形のそれぞれに、notes.md のメモから社内ブログの記事を書いて最後に yomiyasu で推敲するよう3回ずつ頼むと、6回のすべてでスキルが読み込まれました。

## スキルの名前

2.0.2 から、エージェントが yomiyasu を使うのは利用者が名前を出して頼んだときと、スキルでの推敲をはっきり頼んだときだけです。「/yomiyasu」と送るか、依頼の文に「yomiyasu で」と書くか、`$yomiyasu:yomiyasu` のようにスキルの名前を `$` に続けて書けば呼べます。名前を出さずに「読みやすくして」とだけ頼んだときと、名前を出さずに記事やコミットメッセージを書かせたときは使われません。

毎回使いたいときは、CLAUDE.md や AGENTS.md に1行を足します（[毎回 yomiyasu を使いたいとき](../README.md#毎回-yomiyasu-を使いたいとき)）。その1行に書くスキルの名前は入れ方で変わります。Claude Code では `npx skills add` と `gh skill install` で入れたときが `yomiyasu`、プラグインで入れたときが `yomiyasu:yomiyasu` です。Codex では `npx skills add` や `gh skill install` で入れたときも、`.agents/skills/` に置いたときも `yomiyasu:yomiyasu` になります。`npx openskills install` で入れたときと、Claude.ai に ZIP で登録したときは `yomiyasu` を使います。

### Claude Code のプラグインで入れたとき

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

2.0.2 では Claude Code 2.1.296 で、プラグインで入れた形と、プロジェクトの `.claude/skills/yomiyasu/` に置いた形（`npx skills add` が置く場所）の両方を試しました。依頼は名前を出すかスキルでの推敲をはっきり頼む11種類で、「/yomiyasu」とだけ送るもの、`$yomiyasu:yomiyasu` に依頼の文を添えるもの、依頼の文に「yomiyasu で」「よみやすで」と書くもの、「日本語を推敲するスキルを使って」と頼むものなどです。それぞれを2つの形で3回ずつ送ると、合わせて66回のすべてでスキルが読み込まれました（[CHANGELOG](../CHANGELOG.md) の 2.0.2）。対話の画面では試していません。

### Codex で使うリポジトリに置いたとき

この置き方ではフォルダの中に Codex 用のプラグインの設定 `.codex-plugin/plugin.json` があるため、Codex がスキルを `yomiyasu:yomiyasu` という名前で一覧に載せます。呼ぶときは「/yomiyasu」とだけ送るか、依頼の文に「yomiyasu で」と書いてください。一覧の名前どおり `$yomiyasu:yomiyasu` と書いても呼べます。

2.0.0 で確かめたのは、macOS の codex-cli 0.162.1 で、作業場所の `.agents/skills/yomiyasu/` に置いたスキルを読んで推敲したことだけです（[確かめた範囲](./limitations.md#確かめた範囲)）。Codex Cloud、利用者のスキルの置き場所（`~/.agents/skills/`）に置く形、Windows では確かめていません。写したフォルダは自動では新しくならないので、更新するときは同じ手順で写し直してください。