mcpField
M
make-documentation

make-documentation

github.com/callicrate開発11.5k 回インストール24 週間前に更新
リポジトリ

make-documentation について

README や運用手順書、エージェントのワークフローガイドなど、プロジェクト文書の作成とレビューを支援するスキルです。文書の種類に応じたガイドを選び、必要に応じて既存文書を調査し、根拠に基づく簡潔な内容を重視します。

主な機能

  1. 01文書構成と不足箇所の監査
  2. 02文書の種類に応じたガイドの選択
  3. 03README、運用手順書、エージェント文書への対応
  4. 04チェックリストによる原稿レビュー
  5. 05不要な図表や情報源の重複の回避

活用シーン

  1. 01プロジェクト README の作成や改訂
  2. 02文書の不足や構成上の問題の調査
  3. 03環境別のインストール手順や運用手順の作成
  4. 04エージェントのワークフロー文書の準備

インストール

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

$npx skills add https://github.com/callicrate/skills --skill make-documentation

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

同梱ファイル

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

agents/
openai.yaml
references/
ascii-art-standards.md
guide-access-runbook.md
guide-agent-ops-docs.md
guide-ai-ingestion.md
guide-architecture.md
guide-changelog.md
guide-ctf-handoff.md
guide-diagrams.md
guide-install-runbook.md
guide-notebook-documentation.md
guide-readme.md
guide-security-article.md
review-checklist.md
source-discovery-and-heading-stability.md
scripts/
audit_documentation.py

詳細

ドキュメントの作成

使用する場合

  • README.md、アーキテクチャに関するメモ、変更履歴、リリースノートを作成または更新する場合
  • 不足しているドキュメントを追加する前に、既存のプロジェクトドキュメントを監査する場合
  • ソース資料をもとに、顧客向けのセキュリティガイダンスやパートナーに配慮した記事の文章を作成する場合
  • ライブアクセス、再現手順、ラボインターフェース、ワークステーション／サーバー、オペレーター向けのランブックを作成する場合
  • ノートブック、生成されたノートブック、またはテーブルを生成するノートブックのワークフローを文書化する場合
  • WSL、ローカル環境、Docker、または環境固有のインストール手順を作成する場合
  • エージェント運用マニュアル、ロールファイル、ピアステータスの契約、AI が読み取るワークフローのドキュメントを作成する場合
  • ユーザーから明示的に依頼された場合、またはプロジェクトですでに使用されている場合に限り、図のドキュメントを作成する場合

使用しない場合

  • API リファレンスのドキュメントを作成する場合
  • AGENTS.md を作成または更新する場合。他のドキュメントも依頼に含まれていても、agents-md を使用してください。
  • 文章や表で十分な場合に、図のファイルをデフォルトで生成する場合

ワークフロー

  1. 新しいドキュメント、大規模な書き換え、ドキュメントの移動、ドキュメント不足の調査、構成が不明確な場合は、scripts/audit_documentation.py を実行します。明確に指定された小規模な編集では、対象ファイルと周辺のドキュメントを直接確認します。
  2. ユーザーの依頼と監査結果に基づいて必要な成果物だけを選びます。固定のドキュメント一式をデフォルトで生成しないでください。
  3. ドキュメントの種類に応じて、次のガイドを使用します。README.md には references/guide-readme.md、docs/architecture.md またはリポジトリ内の既存の同等ファイルには references/guide-architecture.md、エージェント／AI による取り込み用のドキュメントだとユーザーが指定した場合は references/guide-ai-ingestion.md、エージェントが参照するロール／ワークフローのドキュメントには references/guide-agent-ops-docs.md、ライブアクセス、再現手順、オペレーター、ラボインターフェース、機能台帳には references/guide-access-runbook.md、ノートブックの説明には references/guide-notebook-documentation.md、WSL／ローカル環境／Docker のインストール手順には references/guide-install-runbook.md、パートナーに配慮したセキュリティ記事には references/guide-security-article.md、CHANGELOG.md またはリリースノートには references/guide-changelog.md を使用します。AGENTS.md が作業範囲に含まれる場合は、このスキルを拡張せず、そのファイルには agents-md を使用してください。
  4. ユーザーから図のドキュメントを明示的に依頼された場合、またはプロジェクトですでに図のドキュメントを管理している場合に限り、references/guide-diagrams.md を使用します。
  5. 大規模なドキュメント、反復レポート、機能一覧、コンセプトの整理、または根拠監査に関する修正では、執筆前に references/source-discovery-and-heading-stability.md を読み込みます。
  6. コンセプトや戦略に関するドキュメントでは、アーキテクチャの詳細に入る前に、実行可能な最初のワークフローを見える形で示します。読者がモデルを理解する前に、小規模な作業を実行できるようにします。
  7. 出力はソースに裏付けられた簡潔なものにします。ユーザーが指定した用語を保持し、分野の意味や含意を変えるような一般的な書き換えを避けます。
  8. 後続の実装作業で同じノートブック、ドキュメント、またはフォルダーに手を加える場合も、以前に依頼されたドキュメントを保持します。関係のない実装変更によって既存のドキュメントが削除されたおそれがある場合は、完了前に変更対象のドキュメントを再確認します。
  9. 完了前に references/review-checklist.md を使って結果を確認します。

アンチパターン

  • 誤り：生成された README、レビューパケット、AI による解説、または古くなったコメントをもとにノートブックを要約すること。正しい方法：実行可能なセル、インポート、ウィジェット、SQL、設定、出力をたどってから、簡潔な説明を作成します。
  • 誤り：移動後に、記憶を頼りにフォルダーの契約に関するドキュメントを作成すること。正しい方法：ツリーを監査し、親と子のドキュメントをまとめて更新します。
  • 誤り：実装を参照しながらドキュメントを作成する際に、バリデーター、スキーマ、CLI、テーブル一覧、または信頼できる情報源となるモジュールを重複して作成すること。正しい方法：既存の信頼できる情報源となるアセットを検索し、それらへのリンクを記載します。
  • 誤り：ユーザーから明示的な指定がない限り、ワークフローのドキュメントを VS Code、特定のエディター、または特定の UI に依存させること。正しい方法：エディターに依存しない開始状態と実行環境を記載します。
  • 誤り：スキーマで必須とされている場合を除き、review packet、AI-generated summary、analysis artifact などのメタラベルを、ユーザー向けドキュメントに残すこと。正しい方法：対象読者に合った自然なセクション名を使用します。
  • 誤り：デモ専用のフラグやフィルターを、将来の製品インターフェースとして示すこと。正しい方法：テスト用の仕組みと、永続的なユーザーまたはエージェント向けインターフェースを分けます。

決定論的ツール

ツール使用する場合結果
scripts/audit_documentation.pyドキュメント作成前に、決定論的な一覧が必要な場合現状のドキュメント監査

参考資料

コメント

Markdown 対応