readme-generator について
メイカープロジェクト向けに初心者にも読みやすい README を作成するスキルです。対話式またはコマンドラインのスクリプトを使い、既存プロジェクトのスキャンや、ハードウェア、ソフトウェア、導入、設定の文書化を支援します。
主な機能
- 01対話形式での README 生成
- 02プロジェクトとボード情報から生成
- 03既存プロジェクトのスキャン
- 04README 構成と公開前チェックリスト
活用シーン
- 01動作するメイカープロジェクトの文書化
- 02GitHub や Instructables 向け説明の準備
- 03Arduino プロジェクトの導入手順作成
- 04ハードウェア、ライブラリ、設定要件の整理
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/readme-generatorを入力して読み込まれたか確認します。
同梱ファイルscripts/generate_readme.py
詳細
README ジェネレーター
メーカー向けプロジェクトの、プロフェッショナルで初心者にもわかりやすい README ファイルを作成します。
リソース
このスキルには、以下のツールが含まれています。
- scripts/generate_readme.py - 配線図とテンプレートを備えた、完全な README ジェネレーター
クイックスタート
対話モード：
uv run --no-project scripts/generate_readme.py --interactive
クイック生成：
uv run --no-project scripts/generate_readme.py --project "Weather Station" --board "ESP32" --output README.md
既存のプロジェクトをスキャン：
uv run --no-project scripts/generate_readme.py --scan /path/to/arduino/project --output README.md
使用するタイミング
- 「このプロジェクトのドキュメント作成を手伝ってください」
- 「これを GitHub で共有したいです」
- 「プロジェクトの README を書いてください」
- ユーザーが動作するプロジェクトを持っていて、ドキュメントが必要な場合
- GitHub/Instructables で公開する前
情報の収集
ユーザーに尋ねる項目：
1. Project name and one-line description
2. What problem does it solve / why did you build it?
3. Main features (3-5 bullet points)
4. Hardware components used
5. Software libraries required
6. Any photos/videos/GIFs available?
7. License preference (MIT recommended for open source)
8. Target audience (beginners/intermediate/advanced)
コードから自動抽出する項目：
- config.h のピン割り当て
- ライブラリのインクルード
- WiFi/Bluetooth の機能
- センサーの種類
README テンプレート
以下の構成（awesome-readme のベストプラクティスに基づく）を使用して生成します。
# 🎯 [Project Name]
> One-line description of what this project does and why it's useful.
## 📋 Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Hardware Components](#hardware-components)
- [Wiring Diagram](#wiring-diagram)
- [Software Dependencies](#software-dependencies)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)
## 🔍 Overview
[2-3 paragraphs explaining:]
- What the project does
- Why you built it / what problem it solves
- Who it's for (target audience)
### Demo
[Embed video or GIF showing project in action]
## ✨ Features
- ✅ Feature 1 - brief description
- ✅ Feature 2 - brief description
- ✅ Feature 3 - brief description
- 🚧 Planned: Feature 4 (coming soon)
## 🔧 Hardware Components
| Component | Quantity | Purpose | Notes |
|-----------|----------|---------|-------|
| [MCU Board] | 1 | Main controller | [version/variant] |
| [Sensor 1] | 1 | [function] | [I2C address, etc.] |
| [Display] | 1 | User interface | [resolution] |
| ... | ... | ... | ... |
**Estimated Cost:** $XX-XX
### Where to Buy
- [Component 1](link) - Amazon/AliExpress
- [Component 2](link) - Adafruit/SparkFun
## 📐 Wiring Diagram
### Pin Connections
| MCU Pin | Component | Pin | Function |
|---------|-----------|-----|----------|
| GPIO21 | BME280 | SDA | I2C Data |
| GPIO22 | BME280 | SCL | I2C Clock |
| GPIO4 | LED | Anode | Status indicator |
| ... | ... | ... | ... |
## 💻 Software Dependencies
### Required Software
- [Arduino IDE](https://www.arduino.cc/en/software) (v2.0+) or [PlatformIO](https://platformio.org/)
- [Board package] - [installation link]
### Required Libraries
| Library | Version | Purpose | Install via |
|---------|---------|---------|-------------|
| [Library1] | >=1.0.0 | [function] | Library Manager |
| [Library2] | >=2.3.0 | [function] | Library Manager |
| ... | ... | ... | ... |
## 📦 Installation
### Option 1: Arduino IDE
1. **Install Arduino IDE**
- Download from [arduino.cc](https://www.arduino.cc/en/software)
2. **Add Board Support** (if using ESP32/RP2040)
File → Preferences → Additional Board Manager URLs: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
Then: Tools → Board → Boards Manager → Search "[board]" → Install
3. **Install Required Libraries**
- Sketch → Include Library → Manage Libraries
- Search and install each library from the table above
4. **Clone or Download This Repository**
```bash
git clone https://github.com/[username]/[repo-name].git
または ZIP をダウンロードして展開します
- プロジェクトを開く
- Arduino IDE で
[project-name].inoを開きます
- Arduino IDE で
オプション 2：PlatformIO（上級ユーザーにおすすめ）
-
VS Code + PlatformIO 拡張機能をインストールします
-
クローンして開きます：
git clone https://github.com/[username]/[repo-name].git cd [repo-name] code . -
PlatformIO が
platformio.iniから依存関係を自動的にインストールします
⚙️ 設定
アップロードする前に、config.h をカスタマイズします。
// === NETWORK SETTINGS ===
#define WIFI_SSID "your-wifi-name"
#define WIFI_PASSWORD "your-wifi-password"
// === HARDWARE PINS ===
#define LED_PIN 4
#define SENSOR_SDA 21
#define SENSOR_SCL 22
// === FEATURE FLAGS ===
#define ENABLE_OLED true
#define ENABLE_WIFI true
#define DEBUG_MODE true
環境固有の設定
| 設定 | 開発 | 本番 |
|---|---|---|
| DEBUG_MODE | true | false |
| SERIAL_BAUD | 115200 | 9600 |
| SLEEP_INTERVAL | 10s | 300s |
🚀 使用方法
基本操作
- 電源を入れる - USB またはバッテリーを接続します
- 起動を待つ - 初期化中はステータス LED が点滅します
- [通常動作] - 動作の説明
LED ステータスインジケーター
| LED の状態 | 意味 |
|---|---|
| 緑色で点灯 | 正常動作 |
| 青色で点滅 | WiFi に接続中 |
| 赤色で点滅 | エラー（シリアル出力を確認してください） |
シリアルモニター
シリアルモニターを 115200 ボーで開くと、次の情報を確認できます。
[BOOT] Project Name v1.0.0
[INFO] Initializing sensors...
[OK] BME280 found at 0x76
[INFO] Connecting to WiFi...
[OK] Connected: 192.168.1.100
[DATA] Temp: 23.5°C, Humidity: 45%
Web インターフェース（該当する場合）
http://[device-ip] にアクセスすると、以下を利用できます。
- センサーのリアルタイム測定値
- 設定パネル
- データのエクスポート
❓ トラブルシューティング
よくある問題
アップロードに失敗する：「Failed to connect」
ESP32： BOOT ボタンを押しながら「Upload」をクリックし、「Connecting...」と表示されたらボタンを離します。
Arduino： Tools → Port で正しい COM ポートが選択されているか確認します。
センサーが検出されない
- 配線を確認します（SDA/SCL が逆になっていませんか？）
- I2C スキャナーのスケッチを実行して、アドレスを確認します
- モジュールにプルアップ抵抗がない場合は、プルアップ抵抗（4.7kΩ）を追加します
- 電圧の互換性を確認します（3.3V と 5V）
WiFi に接続できない
- config.h の SSID/パスワードを確認します（大文字と小文字が区別されます！）
- 2.4GHz のみ対応しています（ESP32 は 5GHz をサポートしていません）
- ルーターが新しいデバイスをブロックしていないか確認します
- ルーターに近づいてみます
ランダムに再起動する
- 電源が弱すぎます - 500mA 以上の電源を使用します
- MCU の近くに 100µF のコンデンサーを追加します
- ショートしていないか確認します
- ブラウンアウト検出器を無効にします（ESP32）
まだ解決しませんか？
- 同様の問題がないか、Issuesを確認します
- 以下の情報を添えて、新しい Issue を作成します。
- ハードウェア構成（ボード、センサー）
- エラーメッセージ（シリアル出力全体）
- 問題を再現する手順
🤝 コントリビューション
コントリビューションを歓迎します。方法は以下のとおりです。
バグの報告
- まず既存の Issue を確認します
- バグ報告テンプレートを使用します
- シリアル出力とハードウェアの詳細を記載します
機能の提案
[Feature Request]のプレフィックスを付けて Issue を作成します- ユースケースと期待される動作を説明します
プルリクエスト
- リポジトリをフォークします
- 機能ブランチを作成します：
git checkout -b feature/amazing-feature - 変更を加えます
- 十分にテストします
- コミットします：
git commit -m 'Add amazing feature' - プッシュします：
git push origin feature/amazing-feature - プルリクエストを作成します
コードスタイル
- 意味が明確な変数名を使用します
- 複雑なロジックにはコメントを付けます
- 既存のフォーマットに従います
- PR の前に実機でテストします
📄 ライセンス
このプロジェクトは MIT License のもとでライセンスされています。詳細はLICENSEファイルをご覧ください。
MIT License
Copyright (c) [year] [author]
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
🙏 謝辞
- [Library/Project] - [what it provides]を提供してくれたこと
- [Person/Tutorial] - インスピレーション／ガイダンス
- [Community] - テストとフィードバック
📬 お問い合わせ
[Your Name] - @twitter_handle - [email protected]
プロジェクトリンク：https://github.com/[username]/[repo-name]
⭐ このプロジェクトがお役に立った場合は、スターを付けてください！
---
## Section Guidelines
### Good vs Bad Examples
**Project Description:**
❌ 悪い例：「センサーを搭載した Arduino プロジェクト」 ✅ 良い例：「温度、湿度、空気質を追跡し、しきい値を超えるとアラートを送信する、バッテリー駆動の環境モニター」
**Features:**
❌ 悪い例：「WiFi を搭載」 ✅ 良い例：「📶 自動再接続と OTA アップデートに対応した WiFi 接続」
**Installation Steps:**
❌ 悪い例：「ライブラリをインストールしてアップロード」 ✅ 良い例：スクリーンショット、バージョン番号、正確なメニューパスを含む、手順を追った説明
### Visual Assets
**Recommended:**
- Project photo (hero image)
- Wiring diagram (Fritzing or hand-drawn)
- Demo GIF (< 5MB, 10-15 seconds)
- Schematic (KiCad export)
**Creating GIFs:**
- Use ScreenToGif (Windows) or Peek (Linux)
- Optimize with ezgif.com
- Keep under 5MB for GitHub
### Badges
```markdown
推奨ファイル構成
project-name/
├── README.md # Main documentation
├── LICENSE # MIT license file
├── .gitignore # Ignore build files
├── src/
│ ├── main.ino # Main sketch
│ └── config.h # User configuration
├── lib/ # Local libraries (optional)
├── docs/
│ ├── WIRING.md # Detailed wiring guide
│ ├── API.md # API documentation (if applicable)
│ └── CHANGELOG.md # Version history
├── images/
│ ├── project-photo.jpg
│ ├── wiring-diagram.png
│ └── demo.gif
├── hardware/ # PCB/enclosure files (optional)
│ ├── schematic.pdf
│ └── enclosure.stl
└── examples/ # Additional example sketches
└── basic/
README クイックチェックリスト
公開する前に、次の項目を確認してください：
□ Project name is clear and memorable
□ One-line description explains the "what" and "why"
□ Hero image/GIF shows project in action
□ All hardware components listed with links
□ Wiring diagram included
□ All libraries listed with versions
□ Step-by-step installation instructions
□ Configuration section explains all settings
□ Usage section shows expected output
□ Troubleshooting covers common issues
□ License file present
□ Contact information included
□ No broken links
□ Spelling/grammar checked
共有出力仕様
共有 Arduino スキル仕様を使用してください： 前提条件、必要なツールとバージョン、実装手順、証明段階ごとのテスト／証拠、既知の制限事項、復旧／セキュリティに関する注意事項を記載します。
コメント
Markdown 対応