mcpField
R
readme-writer

readme-writer

github.com/steveclarkeドキュメント36135 回インストール今日更新
リポジトリ

readme-writer について

文章の読みやすさを測定し、改善するライティングスキルです。READMEの構成案も示し、推測ではなくスクリプトで可読性と語彙の指標を算出します。

主な機能

  1. 01Flesch-Kincaid学年の測定
  2. 02基本語彙の使用率の分析
  3. 03明瞭さを高める文章の修正
  4. 04READMEの推奨構成の適用
  5. 05技術文書の品質確認

活用シーン

  1. 01技術提案書の読みやすさの改善
  2. 02メールや文書の明瞭さの向上
  3. 03プロジェクトREADMEの構成

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/steveclarke/dotfiles --skill readme-writer

インストール後、Claude Code で/readme-writerを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

scripts/
flesch_kincaid.rb
top1000.txt
vocabulary_profiler.rb

詳細

読みやすさと README の書き方

2 つの役割があります。一般的な役割は、あらゆる文章（ドキュメント、メール、提案書、仕様書、計画書）の読解レベルを測定して改善することです。より限定的な役割は、README の構成を整えることです。

必ず測定する — 推測しない

文書全体の音節数を目視で正確に数えることはできません。スクリプトを実行せずに Flesch-Kincaid スコアを報告するのは、推測にすぎません。スクリプトを実行してください。

cat FILE | ruby scripts/flesch_kincaid.rb

Markdown 以外のあらゆるテキストで使えます。メールの下書き、ドキュメントの一節、ヒアドキュメントに貼り付けた段落をパイプで渡してください。

目標：学年相当のレベルを 11 以下にすること。 専門用語はスコアを押し上げますが、それで問題ありません。技術的な内容を理解しやすくするため、周囲の文章を明快に保つことが目標です。

修正したら、もう一度測定してください。次の点を中心に修正します。

  • 用語を簡単にするのではなく、文を短くする
  • 複雑な接続表現を簡単なものに置き換える
  • 複数の節を含む文を 2 つに分ける

修正前と修正後のスコアを報告してください。

語彙のカバー率

技術文書の読者には、英語を母語としない人が多くいます。

cat FILE | ruby scripts/vocabulary_profiler.rb

英語で最もよく使われる単語 1000 語に含まれる単語の割合を高めることを目指してください。専門用語によってこの割合が下がるのは想定内です。専門用語以外の単語は簡単なものを使ってください。

推奨事項：

  • 能動態を使う
  • 名詞句を短く、簡潔にする
  • 埋め込み節は 1 段階の入れ子までにする
  • 簡単な「if/then」条件文を使う
  • 接続語（however、therefore、because など）を使って、論理的なつながりを明示する
  • 必要に応じて、情報を複数の文に分ける

避けること：

  • 名詞の前に複数の修飾語を重ねる（「最近改訂された標準化テストのプロトコル」など）
  • 複合条件文や倒置条件文に頼る（「もし彼女が知っていたなら……」など）
  • 読者がアイデア同士の関係を推測することを前提にする
  • 1 つの文に新しい概念を詰め込みすぎる
  • 慣用句や文化的な表現を読者が知っていると想定する

流れと接続

  • 概念を先に説明し、その後で詳細を示します。読者には「方法」より先に「理由」を伝えます
  • 主要なセクションの間に接続を加え、互いに無関係なブロックの羅列ではなく、流れのある文章にします
  • 大まかな説明から詳細へと、論理的に展開します

README の構成

README に特化した文書では、次のセクションで構成します。

  1. 概要と目的 — パッケージの機能と重要性（「自分にどんなメリットがあるか」）
  2. インストールと使い方 — すぐに使い始める方法
  3. 設定 — 一般的なオプションと方法
  4. コントリビューション — 貢献方法、または CONTRIBUTING.md への案内。ビルド環境と移植性に関する注意事項
  5. プロジェクトの構成 — 通常とは異なるトップレベルのディレクトリやファイル、ソースコードを確認する際のヒント

書式

重要な情報を目立たせるには、GitHub 形式のコールアウトブロックを使います。

注意

[!IMPORTANT] [!NOTE] [!TIP] [!WARNING]

  • 太字は、重要な概念を初めて紹介するときに使います
  • コマンド、ファイル名、設定キー、値には code を使います
  • 例には具体的で説明的な名前を使います（「例 1」ではなく「請求書の承認」など）

品質チェックリスト

  • Flesch-Kincaid の学年相当レベルをスクリプトで測定し、11 以下にする
  • 語彙のカバー率を測定し、専門用語以外は簡単な単語を使う
  • 各セクションが次のセクションへ自然につながっている
  • 重要な概念を初めて使うときに太字にする
  • 例には汎用的なプレースホルダーではなく、実際のシナリオ名を使う
  • 企業的なバズワードを使わない（comprehensive、robust、seamless、leverage、utilize）
  • 用語を一貫して使う（同じ概念には同じ単語を使う）
  • 略語や専門用語を、初出時に定義する
  • できる限り能動態を使う

参考文献

コメント

Markdown 対応