readme

Name: readme
Author: boshu2

github.com/boshu2開発450751 回インストール今日更新

リポジトリ

readme について

readme は、プロジェクトの README を生成・書き換え、文章や構成の指針に沿って検証するスキルです。プロジェクト情報の収集、ユーザーへの質問、README 作成、レビューをエージェントに促します。

主な機能

01質問に基づく README 生成
02書き換えと検証モード
03課題を先に示す構成ガイド
04信頼性と権限情報の明記
05council によるレビューと修正

活用シーン

01新規プロジェクトの README 作成
02既存 README の構成見直し
03明瞭さやアンチパターンの確認

インストール

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

$npx skills add https://github.com/boshu2/agentops --skill readme

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

同梱ファイルreferences/.gitkeepscripts/validate.sh

詳細

/readme — ゴールドスタンダードの README 生成

目的： 読み飛ばす人をユーザーに変え、じっくり読む人の期待にも応える README を生成し、最後に評議会で検証します。

このワークフローを必ず実行してください。説明するだけではいけません。

クイックスタート

/readme                    # Interview + generate + validate (new README)
/readme --rewrite          # Rewrite existing README with same patterns
/readme --validate         # Council-validate an existing README without rewriting

パターン

以下は譲れないルールです。このスキルが生成するすべての README は、これに従います。

1. フレームワークではなく、問題から始める

悪い例：「エージェントのワークフローに Three Ways を実装する DevOps レイヤーです。」良い例：「コーディングエージェントはセッションの間にすべてを忘れてしまいます。このツールがその問題を解決します。」

読者が、どんな悩みを解決するのか一文で理解できるようにしてください。専門用語やフレームワーク名、理論は使わないでください。問題が読者を引きつけます。（注：Three Ways や Meadows などのフレームワークへの言及は、設計の根拠として本文に記載してください。冒頭で触れないようにするだけです。）

2. 先行事例を認める

アプローチが確立された手法（アジャイル、SCRUM、仕様駆動開発、CI/CD など）に似ている場合は、明示してください。

「X を経験したことがあるなら、解決策はすでにご存じでしょう。新しいのは Y です。」

これにより、車輪の再発明だと見なして退ける可能性のある経験豊富な実践者にも受け入れてもらいやすくなります。本当に新しい点だけを主張してください。

3. 主張するのではなく、実例を示す

悪い例：「これが X の違いを生みます。システムは複利的に成長します。」良い例：システムが動作していることを示すターミナルの記録。

証拠のない断言は反感を招きます。形容詞より具体例を示してください。コードブロックで示せないものは、README に載せる準備ができていません。

4. 差別化要因は一度だけ述べる

明確な説明を一度、実演を一度。それが上限です。核となる価値提案をすべてのセクションで繰り返すと、補強ではなく宣伝文句になります。読者が最初に読んだときに理解すると信頼してください。

5. インストールの近くに信頼性に関する情報を置く

コードを実行したり、フックを登録したり、設定を変更したりするものをインストールする前に、ユーザーが確認できるようにしてください。

懸念事項	回答する内容
何に触れますか？	作成・変更されるファイル、登録されるフック
外部にデータを送信しますか？	テレメトリー、ネットワーク通信、マシン外に送信されるデータ
権限の範囲	シェルコマンド、設定変更、Git の動作変更
元に戻せますか？	すぐに無効化する方法、完全にアンインストールする方法

この情報はインストールコマンドの近くに置き、FAQ の奥に埋もれさせないでください。

6. 深掘りできる情報は削らず、折りたたむ

詳細なワークフローの手順、アーキテクチャの深掘り、理論、リファレンス資料は <details> ブロックに入れてください。ざっと読む人には手早く把握できる道筋を、じっくり読む人にはクリックして展開できる情報を用意します。簡潔さのために詳しい情報を削らず、折りたたんでください。

7. 達人ぶった語り口をなくす

「N か月で学んだこと」のような表現は避けてください。「私は X の出身なので、Y を適用しました」も避けてください。「これが私たちの違いを生みます」も避けてください。ツールそのものに語らせてください。謙虚さは警戒心を和らげます。見下すような態度は人を遠ざけます。

8. セクションの順序は、導入を促すものにする

Problem → Install → See It Work → Getting Started Path → How It Works (collapsed) → Reference

理論やアーキテクチャは、ユーザーが例を見て、使い始める方法を把握した後に配置してください。「試す方法」より前に「なぜこれが重要なのか」を置いてはいけません。

実行手順

/readme [--rewrite] [--validate] が指定された場合：

Step 1: 事前確認

ls README.md 2>/dev/null

モードの判定：

--validate と README が存在する場合 → Step 5 に進みます（評議会による検証のみ）
--rewrite と README が存在する場合 → 既存の README を読み、書き直しの参考情報として使います
README が存在し、フラグが指定されていない場合 → 次を確認します：
- 「書き直す — ゴールドスタンダードのパターンで再生成する」
- 「検証する — 既存の README を評議会で確認する」
- 「キャンセル」
README が存在しない場合 → Step 2 に進みます（ゼロから生成）

Step 2: コンテキストを収集する

利用可能なプロジェクトファイルを、ユーザーに出力せずに読み取ります。

ls README.md PRODUCT.md package.json pyproject.toml go.mod Cargo.toml Makefile 2>/dev/null
ls -d src/ lib/ cmd/ app/ 2>/dev/null
ls -d docs/ 2>/dev/null
ls LICENSE CHANGELOG.md 2>/dev/null

以下を抽出します：

プロジェクト名：マニフェストファイルから
言語／ランタイム：ビルドファイルから
既存の説明：README または PRODUCT.md から
ライセンス：LICENSE ファイルから
インストール方法：マニフェストから（npm、pip、brew、go install、cargo など）

Step 3: ヒアリング

各セクションについて AskUserQuestion を使って質問します。可能な場合は Step 2 の情報をもとに候補を事前入力します。質問は簡潔にしてください。

3a：問題

質問：「これはどのような問題を解決しますか？　ユーザーが抱えている課題を一文で説明してください」

選択肢（README／PRODUCT.md がすでにある場合は、その内容をもとに作成）：

問題を説明する文の候補
より力強い表現
「自分で入力する」

3b：解決策

質問：「その問題をどのように解決しますか？　ツールが実際に行うことを一文で説明してください」

3c：対象ユーザー

質問：「誰を対象にしていますか？　ランタイム、フレームワーク、または役割を挙げてください」

例：「FastAPI を使う Python 開発者」や「Claude Code または Cursor を実行する人」

3d：インストール

質問：「インストールコマンドは何ですか？（最も目立つ場所に掲載します）」

選択肢：

マニフェストから検出（例：npm install <pkg>、pip install <pkg>）
「自分で入力する」

3e：クイックデモ

質問：「インストール後、動作を確認するためにユーザーができる最も簡単なことは何ですか？（コマンド、コードスニペット、またはターミナルセッション）」

3f：信頼性に関する懸念

質問：「ツールは次のいずれかを行いますか？　当てはまるものをすべて選んでください」

シェルコマンドまたはフックを実行する
プロジェクト外の設定ファイルを変更する
ネットワーク通信を行う
ユーザーのリポジトリにファイルを作成する
上記のいずれにも該当しない

3g：既存の類似ツール（任意）

質問：「似たツールはありますか？　ある場合、あなたのツールとの違いは何ですか？（正直に答えてください。その分野に詳しい読者は確認します）」

選択肢：

「はい、説明する」→追加質問
「特にない／スキップする」

ステップ 4：README を生成する

インタビューの回答と上記の 8 つのパターンを使用して、次の構成で README を生成します。

<div align="center">

# {Project Name}

### {Problem statement — one line}

{Badges}

{Nav links}

</div>

---

> [!IMPORTANT]
> {Trust block — local-only, what it touches, how to disable, how to uninstall}
> (Skip if no trust concerns from 3f)

{Install command}

---

## The Problem

{2-3 sentences expanding the problem. Acknowledge prior art if applicable.
State what's genuinely new about your approach — once.}

---

## See It Work

{Terminal transcript or code example from 3e. Show, don't describe.}

---

## Install

{Full install details, alternative methods in <details> blocks.
"What it touches" table if trust concerns exist.}

---

## Getting Started

{Adoption path — Day 1, Week 1, etc. Or just "Run X, then Y."}

---

## How It Works

{One paragraph summary + diagram if applicable.}

<details>
<summary><b>Details</b> — {phases, architecture, etc.}</summary>

{Deep content here}

</details>

---

## {Reference sections as needed}

{Skills, API, CLI, etc. — collapsed where appropriate}

---

## FAQ

{Top 3 questions inline, link to full FAQ if it exists}

---

## Contributing

## License

生成ルール：

すべての <details> ブロックで、<summary> の後に空行を入れます（Markdown のレンダリングを有効にするため）
details ブロック内ではインライン HTML（<code>、<a href>、<br>）ではなく、Markdown を使用します
</details> の前に空行を入れます
ユーザーの既存コンテンツで使われていない限り、絵文字を使用しません
フライホイール／差別化要素のコンセプトは、「The Problem」で一度だけ述べ、「See It Work」で一度だけ実演します
「What N months taught me」「This is what makes X different」「I come from X so I applied Y」という表現は使いません

生成した README を README.md に書き込みます。

ステップ 5：委員会による検証

README を検証するために委員会を実行します。

Skill(skill="council", args="--quick validate README.md — is it clear, non-repetitive, and does it serve both skimmers and deep readers?")

--rewrite を指定した場合、または最初から生成する場合： --quick を使用します（インラインで高速に実行）。

既存の README に対して --validate を実行する場合： 詳細なレビューのため、標準の委員会（判定者 2 名）を使用します。

委員会の検出結果をユーザーに提示します。重大な問題が見つかった場合は、次の選択肢を提示します。

「修正する — 委員会の推奨事項を自動で適用する」
「表示する — 検出結果を表示し、自分で判断する」
「このまま公開する — これで十分」

ステップ 6：修正を適用する（希望する場合）

委員会が推奨した修正を適用します。--quick で再検証し、問題がないことを確認します。

ステップ 7：報告

## README Complete

**File:** README.md
**Sections:** {count}
**Patterns applied:** {list which of the 8 patterns were relevant}
**Council verdict:** {PASS/WARN/FAIL}

{If WARN/FAIL: list the top findings and whether they were fixed}

検出すべきアンチパターン

書き換えや検証を行う際は、次のパターンを指摘してください。

アンチパターン	検出方法	修正方法
フライホイールの繰り返し	中核となる価値提案が 3 回以上述べられている	一度だけ述べ、一度だけ実演する
フレームワーク先行	問題ではなく、手法の名前から始まっている	冒頭を問題提起として書き直す
権威者のような口調	「学んだこと」「This is what makes X different」などの表現	削除し、ツール自体に語らせる
定義前の専門用語	説明する前に専門用語が使われている	初出時に定義するか、平易な言葉を使う
信頼性に関する情報が見つけにくい	セキュリティ／権限に関する情報が最初の画面に表示されない	インストール案内の近くに移動する
アンインストール方法が見つからない	10 秒以内にアンインストール方法を見つけられない	インストール案内の近くに追加する
インストール情報の散在	同じインストールコマンドが 3 か所以上にある	最初に目立つ場所と、正式な参照先の 2 か所にまとめる
試す前に理論を説明	例より先にアーキテクチャや理念を説明している	例を先に配置し、理論は details 内に移動する
根拠のない主張	デモなしで「最高」「異なる」「独自」などと主張している	具体例に置き換えるか、削除する

例

新しいプロジェクト用の README を一から生成する

ユーザーの入力： /readme

動作：

事前チェックで既存の README.md がないことを検出し、一からの生成に進みます。
スキルがプロジェクトのコンテキスト（マニフェストファイル、ソースディレクトリ、ライセンス）を読み込み、課題、解決策、対象ユーザー、インストールコマンド、簡単なデモ、信頼性に関する懸念について尋ねる短いインタビューを実施します。
8 つのゴールドスタンダードパターン（課題を最初に示す導入、インストール手順の近くに置く信頼性に関する情報、折りたたまれた詳細説明など）に従って README を生成し、簡単な評議会レビューで検証します。

結果： 流し読みする人をユーザーへと導き、じっくり読む人にも役立つ、ディスクに書き込まれた完全な README.md と、品質を確認する評議会の判定が得られます。

既存の README を変更せずに検証する

ユーザーの入力： /readme --validate