📝 Generate professional README.md documentation for local projects or GitHub projects
Uses an interactive workflow: automatically collect information → user confirmation → generate table of contents → user confirmation → generate README → iterative refinement
🎯 When to use (trigger scenarios)
✅ Use this skill when the user says:
| Scenario | Example |
|---|---|
| Local project | "Write a README for this project: ~/.openclaw/skills/my-project" |
| GitHub project | "Write a README for https://github.com/user/repo " |
| Skill project | "Write a README for easy-image-generate" |
| Optimize existing | "Optimize this project's README" |
| Specify style | "Write a README following the skill-rembg style" |
❌ Do not use this skill for:
- Code review → use code analysis tools
- Project deployment → use deployment/CI/CD tools
- Troubleshooting → use debugging tools
🔄 Interactive workflow
Full workflow (11 steps)
- User input (local path or URL)
- Automatically collect project information
- Display information, user confirms/modifies
- Ask about README purpose and style preferences
- Generate suggested table of contents structure
- User confirms/adjusts table of contents
- 💬 Optional section inquiry (acknowledgments/contributing/changelog)
- Generate README draft
- Quality check + user feedback
- Iterative refinement (multiple rounds possible)
- Final version + backup
📊 Step 1: Project information collection
Local project
Automatically read:
- package.json → project name, description, version, scripts
- requirements.txt → Python dependencies
- pyproject.toml → Python project configuration
- Cargo.toml → Rust project
- Main language files (.py/.js/.ts/.rs, etc.)
- Directory structure (scripts/ docs/ tests/)
- Existing README (if any)
Display to user for confirmation:
📊 Detected project information:
Basic information:
- Project name: [auto-extracted]
- Version: [auto-extracted]
- Description: [auto-extracted]
- Main language: [auto-extracted]
Project type: [auto-identified]
Core features: [auto-analyzed]
Is the above information correct? Anything to add or modify?
🎯 Step 2: Ask about README purpose
Inquiry template:
🎯 Who is the main audience for this README?
A. Potential users - Quickly understand the project's purpose B. Developers - Want to contribute code C. Both(Recommended)
📝 What would you like to highlight?
A. Quick start - Installation + usage examples B. Features - Detailed feature list C. API documentation - Technical details D. Project background - Why this project was created
🎨 Documentation style preference?
A. Concise and professional - Like the requests library B. Lively and friendly - Like skill-rembg (emoji + bilingual) C. Detailed and complete - Like a large framework
📑 Step 3: Generate directory structure
Generate a suggested directory structure based on the project type and preferences, and continue only after the user confirms.
💬 Step 3.5: Optional section inquiry
Sections that must be asked about:
📝 Would you like to add the following sections?
1️⃣ Acknowledgements section (🙏 Acknowledgements)
Thank contributors, tools, or platforms used
Please reply:
- "Yes, acknowledgements: OpenClaw, ClawHub"
- "No, not needed"
2️⃣ Contributing guide (🤝 Contributing)
How to contribute code to the project
Please reply:
- "Yes, it's an open source project"
- "No, it's a personal project"
3️⃣ Changelog (📝 Changelog)
Project version history
Please reply:
- "Yes, there are multiple versions"
- "No, it's the initial version"
Rules:
- ✅ Must ask first, then generate
- ✅ If the user says "no", do not generate that section
- ✅ If the user says "yes", list the specific content
✍️ Step 4: Generate README draft
Generation rules
0. Badge area (after the project introduction)
🎨 Use a multi-line professional layout (rich and complete; users can manually simplify it):
<!-- Badge Row 1: Core Info - 项目身份 -->
[](https://clawhub.ai/author/skill)
[](https://github.com/author/repo)
[](https://github.com/author/repo)
<!-- Badge Row 2: Package Registry - 包管理器（如已发布） -->
[](https://npmjs.com/package/package-name)
[](https://pypi.org/project/package-name)
<!-- Badge Row 3: Tech Stack - 技术栈/语言版本 -->
[](https://nodejs.org)
[](https://python.org)
[](https://rust-lang.org)
<!-- Badge Row 4: Platforms - 平台支持 -->
[](https://openclaw.ai)
[](https://openclaw.ai)
[](https://openclaw.ai)
[](https://openclaw.ai)
[](https://openclaw.ai)
[](https://openclaw.ai)
<!-- Badge Row 5: License - 许可证 -->
[](LICENSE)
💡 Design philosophy:
- ✅ Rich and complete badges - Generate all possible badges; users can manually delete unwanted ones
- ✅ Flexible URL handling - Use actual links where they can be determined; use Demo placeholders where they cannot
- ✅ No personal information - All Demos use generic placeholders (
author、repo、skill-name） - ✅ Windows uses Base64 - Avoid broken image links
📋 Dynamic badge generation rules
Row 1: Core information badges (project identity)
1. ClawHub Badge
- Condition: Detected as an OpenClaw Skill (has
SKILL.md） - Format：
[](https://clawhub.ai/author/skill) - skill-name: Read from SKILL.md's
namefield, converted to kebab-case - Link: Use Demo placeholder
https://clawhub.ai/author/skill
2. GitHub Badge
- Condition: The user provided a GitHub URL or
.gitdirectory was detected - Format：
[](https://github.com/author/repo) - author/repo: Extract from the Git remote or package.json
- Link: If it cannot be extracted, use Demo placeholder
https://github.com/author/repo
3. Version Badge (must be generated)
- Read priority：
package.json→versionpyproject.toml→versionCargo.toml→versionpom.xml→versioncomposer.json→version- Default：
0.0.1
- Format：
[](链接) - Link: Use project homepage or Demo placeholder
Row 2: Package Manager Badge (if published)
Generate the corresponding package manager Badge based on the project type:
| Project Type | Badge | Link |
|---|---|---|
| npm package | [](https://npmjs.com/package/package-name) |
npmjs.com |
| Python package | [](https://pypi.org/project/package-name) |
pypi.org |
| Ruby Gem | [](https://rubygems.org/gems/gem-name) |
rubygems.org |
| Go Module | [](https://pkg.go.dev/module/path) |
pkg.go.dev |
| Maven | [](https://search.maven.org) |
search.maven.org |
Link handling: If the actual package name cannot be obtained, use a Demo placeholder
Row 3: Tech Stack/Language Version Badge
Automatically read project configuration to generate:
Node.js project(read package.json → engines.node）：
[](https://nodejs.org)
Python project(read pyproject.toml or setup.py → python_requires）：
[](https://python.org)
Rust project(read Cargo.toml → edition）：
[](https://rust-lang.org)
Go project(read go.mod → go version):
[](https://go.dev)
PHP project(read composer.json → require.php）：
[](https://php.net)
Link handling: Use official documentation links or Demo placeholders
Row 4: Platform Badges (generate all, user can trim)
Generate all platform Badges by default, users can manually delete as needed:
[](https://openclaw.ai)
[](https://openclaw.ai)
[](https://openclaw.ai)
[](https://openclaw.ai)
[](https://openclaw.ai)
[](https://openclaw.ai)
Color specification：
- macOS:
#000000(black) - Windows:
#0078D6(blue) + Base64 SVG Logo - Linux:
#FCC624(yellow) - Android:
#3DDC84(green) - iOS:
#000000(black) - Web:
#4285F4(blue)
Link handling: Use Demo placeholder https://openclaw.ai
Row 5: License Badge
Read priority：
package.json→licensepyproject.toml→licenseCargo.toml→licenseLICENSE/LICENSE.md/LICENSE.txtfilename- Default：
MIT
License color mapping：
- MIT:
#BD2D2D(red) - Apache-2.0:
#D54D2D(orange-red) - GPL-3.0:
#FF7A00(orange) - BSD-3-Clause:
#3B82F6(blue) - ISC:
#10B981(green) - Unlicense:
#6B7280(gray) - Other:
#6B7280(gray)
Format：[](LICENSE)
Link handling: Point to LICENSE file (if it does not exist, users can modify manually)
✅ Badge generation example (full version)
Example: Node.js project (full Badge display)
<!-- Badge Row 1: Core Info -->
[](https://clawhub.ai/author/project)
[](https://github.com/author/repo)
[](https://github.com/author/repo)
<!-- Badge Row 2: Package Registry -->
[](https://npmjs.com/package/package-name)
<!-- Badge Row 3: Tech Stack -->
[](https://nodejs.org)
<!-- Badge Row 4: Platforms -->
[](https://openclaw.ai)
[](https://openclaw.ai)
[](https://openclaw.ai)
[](https://openclaw.ai)
[](https://openclaw.ai)
[](https://openclaw.ai)
<!-- Badge Row 5: License -->
[](LICENSE)
💡 Tip for users: Add a note at the end of the README:
> 💡 **Badge 说明**：以上 Badge 为自动生成，如与实际不符可手动删除或修改。
⚠️ Badge generation rules summary
- ✅ Must use HTML comments for line breaks（
<!-- Badge Row X: ... -->） - ✅ Badges rich and complete - Generate all possible Badges, users can manually trim
- ✅ Version Badge must be generated(use 0.0.1 when there is no version number)
- ✅ Generate all platform Badges（macOS/Windows/Linux/Android/iOS/Web）
- ✅ Windows uses Base64 SVG Logo(to avoid image link failure)
- ✅ License Badge generated based on the actual License(default MIT when none)
- ✅ Flexible URL handling - Use the actual link when it can be determined, otherwise use a Demo placeholder
- ✅ No personal information - All Demos use generic placeholders (
author、repo、skill-name） - ✅ Unified colors(use shields.io standard colors)
- ✅ Placement: After the project description, before the table of contents
1. Chinese-English bilingual rules
Chinese part:
- Complete project introduction
- Content of all sections
- All code examples
English Version：
- ✅ Must be fully translatedAll chapters
- ✅ Comments and output in code examples must be in English
- ✅ TOC links must correspond to English anchors
- ✅ Content length and information volume must be consistent with the Chinese version
- ✅ The English section must have its own independent Table of Contents
- ✅ The number of English TOC entries must match the Chinese version
Chapter correspondence rules:
- Chinese uses
##to mark main chapters - English uses
###to mark main chapters - English TOC uses
### Table of Contents - Chinese code blocks use ``` markers
- English code blocks use ``` markers
2. Code block format
All code blocks use ``` markers
Format:
代码内容
Rules:
- ✅ Code blocks must specify a language
- ✅ Do not use ~~~ markers
- ✅ Do not have extra ```
3. Optional chapters
Generate based on the user confirmation results from step 3.5:
- Acknowledgements section (if the user confirms it is needed)
- Contributing guide (if the user confirms it is needed)
- Changelog (if the user confirms it is needed)
4. Other rules
- Emoji markers - Use moderately to enhance readability
- Code examples - At least 3 practical examples
- Table presentation - Use tables for parameters, configuration, etc.
- Quality check - Automatic check after generation
🔄 Step 5: Iterative optimization
Support multiple iterations and modify the README based on user feedback.
📋 Special scenario handling
Scenario 1: Existing README
⚠️ Existing README.md detected
Options: A. Complete rewrite (overwrite existing) B. Optimize based on existing (keep structure, improve content) C. Generate a new version (README.new.md)
Scenario 2: Multilingual project
🌍 Multilingual project detected
Suggestions: A. Generate separate README_CN.md and README_EN.md B. Split into sections in the main README (Chinese | English)
Scenario 3: Large project
📊 Large project detected (>50 files)
Suggestions:
- README.md (introduction + quick start)
- docs/ directory (detailed documentation)
🎨 README style guide
Core principles
- Clear structure - Emoji-marked chapters, clear hierarchy
- Bilingual Chinese and English - Chinese by default + English version,complete and consistent content
- Practicality first - Adjust according to project type
- Flexible and creative - Organize freely according to project characteristics
Project type-specific content
| Project type | Specific chapters | Description |
|---|---|---|
| Python | Dependency installation, virtual environment, PyPI publishing | requirements.txt, setup.py |
| Frontend | Tech stack, build commands, deployment guide | package.json, npm scripts |
| API service | Endpoint list, request examples, authentication methods | REST/GraphQL, curl examples |
| CLI tools | Command-line arguments, subcommands, configuration options | Parameter descriptions, usage examples |
| Library/SDK | API reference, type definitions, version compatibility | Function/class descriptions, type hints |
| OpenClaw Skill | Trigger words, use cases, configuration | SKILL.md content extraction |
✅ Quality Checklist
Automatically check after generating README:
Basic Checks
- Project introduction is clear (1-2 sentences)
- Installation steps are complete and executable
- At least 3 usage examples
- Features listed (3-5)
- Table of contents navigation is correct (if >100 lines)
- Code blocks specify language
- Links are valid
- License is explicit
Chinese-English Bilingual Checks
- Chinese content is complete
- English version fully translates all sections
- English table of contents links are correct (anchors use English)
- Comments in English code examples are translated
- English content length matches Chinese
- English section has an independent Table of Contents
- Number of English TOC entries matches Chinese table of contents
Optional Section Checks
- Asked the user about the acknowledgments section(Yes/No)
- Asked about contribution guidelines (needed/not needed)
- Asked about changelog (needed/not needed)
Badge Checks (New)
- Badge area follows the project description
- Uses 3-line layout(core info + platforms + license)
- Uses HTML comments for line breaks（
<!-- Badge Row X: ... -->） - Version Badge is generated(0.0.1 when no version number)
- Platform Badge is correct(default macOS+Windows+Linux or user-specified)
- License Badge is correct(based on actual License or default MIT)
- Each Badge has a link
- Colors conform to standards(use shields.io standard colors)
Code Block Checks
- Code blocks use ``` markers (no ~~~)
- No extra ```
Prohibitions
- ❌ Do not automatically generate the acknowledgments section(must ask first)
- ❌ Do not omit content from the English version
- ❌ Do not use Chinese anchors to generate the English table of contents
- ❌ Do not omit the Table of Contents in the English section
- ❌ Do not let English TOC entries differ from Chinese
- ❌ Do not use ~~~ to mark code blocks
- ❌ Do not generate extra ```
- ❌ Badges must not lack Version(must use 0.0.1 when no version number)
- ❌ Platform Badge must not be wrong(must be macOS+Windows+Linux when not specified by the user)
- ❌ License must not be wrong(must read the actual License or default to MIT)
- ❌ Badges must not lack links
- ❌ Do not omit HTML comment line breaks
📝 Version Management
Backup Strategy
Back up the existing README before generation:
cp README.md README.md.bak.日期
Version History
Add a changelog section at the end of the README.
🔧 Configuration Options
Language Settings
| Parameter | Description | Default |
|---|---|---|
--lang bilingual |
Bilingual (Chinese and English) | ✅ |
--lang chinese |
Chinese only | - |
--lang english |
English only | - |
Level of Detail
| Parameter | Sections | Suitable For |
|---|---|---|
--detail minimal |
Introduction, Installation, Usage | Small projects |
--detail standard |
+ Features, API, Contributing | Medium projects (default) |
--detail complete |
+ FAQ, Benchmarks, Architecture | Large projects |
Style Options
| Parameter | Description |
|---|---|
--style professional |
Concise and professional |
--style friendly |
Lively and friendly (emoji + bilingual) |
--style complete |
Detailed and complete |
🚀 Quick Start
Basic Usage
为这个项目写 README：~/.openclaw/skills/my-project
Specify Style
为 https://github.com/user/repo 写 README，参考 skill-rembg 风格
Specify Type
为 Python 项目写 README，突出 API 文档
📄 License
MIT License
Happy Documenting! 📝✨
Top / Back to Top