README ライター

プロジェクトの README を作成または書き直し、訪問者をユーザーやコントリビューターに変えます。ワンラインピッチ、バッジ、60秒クイックスタート、実際の例、機能、FAQ、コントリビュート方法、ライセンスを含み、不足セクション、壊れた相対リンク、見出しと一致しない目次アンカー、代替テキストの欠如、遅い最初のコードブロックを lint します。ユーザーが README の作成、改善、レビュー、再構成を依頼したときや、プロジェクトが理解されない、スターがつかないと言ったとき、オープンソース公開の準備をしているときに使用します。

README ライター とは?

このスキルは、プロジェクトの README を作成または改善するためのプロフェッショナルなアシスタントです。README の唯一の役割は、訪問者を「これは何?」から「最初のコマンドを実行する」まで1分以内に導き、さらにその先へ進む方法とプロジェクトへの貢献方法を示すことだと定義しています。対応プラットフォームは、Claude Code や Cursor、Codex などの AI エージェントで、Python スクリプトによる lint 機能を備えています。ワークフローは、まずプロジェクトのマニフェストファイルや CLI ヘルプから事実を収集し、コードからわからないことだけをユーザーに質問します。次に既存の README を lint し、所定の構造に従って書き直し、最後に再度 lint してエラーがないことを確認します。lint ルールは、タイトル、ピッチ、バッジ、インストール手順、クイックスタート、コードブロック、スクロール位置、コントリビュートセクション、ライセンス、FAQ、目次、代替テキスト、壊れたリンク、壊れたアンカー、プレースホルダーなどをチェックし、エラーがあれば終了コード1を返します。このスキルは、プロジェクトへの訪問者を増やしたい、スターやコントリビューターを獲得したい、オープンソース公開前のレビューが必要な場合に特に有用です。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/saizul/oss-maintainer-skills/tree/HEAD/skills/readme-writer

Installed? Explore more 生産性&コラボレーション skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

README ライター は何をしますか?

README の仕事はただ一つ:訪問者を「これは何?」から最初のコマンドの実行まで1分以内に導き、さらにその先へ進む方法とプロジェクトへの貢献方法を示すことです。

使用するタイミング

  • 新しいプロジェクトの README を作成する、または薄い・冗長な README を書き直すとき
  • 公開前や 1.0 リリース前に README をレビューするとき
  • ユーザーが「プロジェクトにアクセスはあるがスターやインストール、コントリビューターが増えない」と言ったとき

使用しないタイミング

  • API リファレンスドキュメント(コードから生成し、README からリンクする)
  • 長いチュートリアルやアーキテクチャドキュメント:docs/ に入れてリンクする

ワークフロー

  1. 書く前に事実を収集する。 マニフェスト(pyproject.toml、package.json、composer.json、Cargo.toml...)、CLI の --help やメインエントリポイント、既存のドキュメント、ライセンスを読む。実際のインストールコマンドと実際の例を見つける。フラグ、出力、ベンチマーク、機能を決して作り出さない。

  2. コードからわからないことだけをユーザーに質問する: プロジェクトの対象者、解決する1つの問題、明らかな代替手段より優れている理由。ユーザーが利用できない場合は、コードから中立的なピッチを書き、レビュー用にマークする。

  3. 現在の README を lint する(存在する場合)。scripts/ はこのスキルからの相対パス:

    python3 scripts/readme_lint.py README.md
    python3 scripts/readme_lint.py README.md --json --strict
    
  4. structure.md の構造に従い、テンプレート から書き始める。順序が重要: タイトル+バッジ、ピッチ、(デモ画像)、クイックスタート、機能、使用法/例、設定、FAQ、ロードマップ、コントリビュート、ライセンス。

  5. ライティングルールを適用する:

    • ピッチ:一文、200文字未満、誇大広告なし。パターン: 「<名前> は、<対象> のために <X> を行う <カテゴリ> であり、<主な差別化要因>。」
    • 最初のコードブロックは 60 行目より上に。すべてのコマンドはコピペ可能で実際のもの。
    • コマンドの後には役立つ出力を示す(# => ... または別ブロック)。
    • オプションや比較にはテーブル、機能にはリストを使用(利点を先に)。
    • リンクする、貼り付けない:長いドキュメント、変更履歴、API リファレンスは別の場所に。
    • すべての画像に代替テキストを設定する;メインフローは SVG または短い GIF を推奨。
  6. バッジ。 実際に存在し維持されているバッジのみを使用し、順序は次の通り:CI ステータス、最新バージョン(PyPI/npm/Packagist/リリース)、ダウンロード数(任意)、ライセンス。structure.md に例あり。

  7. 再 lint する エラーがなくなるまで。警告は解決するか、ユーザーに理由を説明する。

  8. リンターがチェックできないリンクを確認する: 絶対 URL とアンカー。クリックテストするか、検証できなかったものを説明する。

出力

  • 新規または更新された README.md(書き直しの場合は差分サマリーを表示)。
  • 最終的な lint 結果。
  • 検証できなかった事実と、ユーザーが埋める必要のあるプレースホルダーの短いリスト(デモ GIF、スクリーンショット、ベンチマーク数値)。

Lint ルール

ルールレベル意味
titleエラー/警告正確に1つの H1
pitchエラー/警告タイトルの下にある短い最初の段落
badges警告バッジが見つからない
installエラー/警告インストール(またはクイックスタート)セクション、コードブロック付き
quickstartエラー/警告使用法、クイックスタート、または例のセクション、コード付き
codeエラーコードブロックがまったくない
scroll警告最初のコードブロックが --max-scroll 行(デフォルト 60)より後にある
contributing, license警告セクションが欠けている
faq, toc情報推奨
alt-text警告代替テキストのない画像
broken-linkエラー存在しないファイルへの相対リンク、または空のリンク
broken-anchorエラーGitHub のスラッグルールに基づき、見出しや HTML の id/name と一致しない #anchor リンク(目次)
placeholder警告TODO、TBD、または lorem ipsum が残っている

エラーがある場合は終了コード 1(--strict の場合は警告も)。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

関連スキル