📝 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 optimization
🎯 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 in the style of skill-rembg" |
❌ 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
Complete 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 optimization (can be multiple times)
- 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 for user confirmation:
📊 Detected project information:
Basic information:
- Project name: [automatically extracted]
- Version: [automatically extracted]
- Description: [automatically extracted]
- Main language: [automatically extracted]
Project type: [automatically identified]
Core features: [automatically analyzed]
Is the above information correct? Does anything need to be added or modified?
🎯 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 content do you want 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 after the user confirms.
💬 Step 3.5: Optional section inquiry
Sections that must be asked about:
📝 Do you need 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 is an open source project"
- "No, it is a personal project"
3️⃣ Changelog (📝 Changelog)
Project version history
Please reply:
- "Yes, there are multiple versions"
- "No, it is 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 when they can be determined, and Demo placeholders when they cannot
- ✅ No personal information - All Demos use generic placeholders (
author、repo、skill-name） - ✅ Use Base64 on Windows - Avoid image link failures
📋 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 the
namefield in SKILL.md, converted to kebab-case - Link: Use the Demo placeholder
https://clawhub.ai/author/skill
2. GitHub Badge
- Condition: The user provided a GitHub URL or a
.gitdirectory was detected - Format：
[](https://github.com/author/repo) - author/repo: Extract from the Git remote repository or package.json
- Link: If it cannot be extracted, use the 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 the project homepage or a 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 the 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 Badge (generate all, users can trim)
Generate all platform Badges by default, users can manually delete them according to the actual situation:
[](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 the LICENSE file (if it does not exist, users can modify it manually)
✅ Badge generation example (complete version)
Example: Node.js project (complete 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)
💡 Prompt the user: Add a note at the end of the README:
> 💡 **Badge 说明**：以上 Badge 为自动生成，如与实际不符可手动删除或修改。
⚠️ Badge generation rule 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)
- ✅ Generate License Badge based on the actual License(defaults to 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
- All section content
- All code examples
English Version：
- ✅ Must be fully translatedAll sections
- ✅ Comments and output in code examples must be in English
- ✅ Table of contents links must correspond to English anchors
- ✅ Content length and information volume must match the Chinese
- ✅ The English part must have an independent Table of Contents
- ✅ The number of English TOC entries must match the Chinese
Section correspondence rules:
- Chinese uses
##to mark main sections - English uses
###to mark main sections - 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 sections
Generate according to the user confirmation result in step 3.5:
- Acknowledgements section (if the user confirms it is needed)
- Contribution 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 - Automatically 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. Completely 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 (中文 | 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 - Mark sections with emoji, with distinct hierarchy
- Bilingual Chinese-English - Default Chinese + English version,complete and consistent content
- Practicality first - Adjust according to project type
- Flexible expression - Organize freely according to project characteristics
Project type-specific content
| Project type | Unique sections | 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 method | REST/GraphQL, curl examples |
| CLI tools | Command-line arguments, subcommands, configuration options | Parameter descriptions, usage examples |
| Libraries/SDKs | 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 the README:
Basic checks
- Project introduction is clear (1-2 sentences)
- Installation steps are complete and executable
- At least 3 usage examples
- Feature list (3-5 items)
- Table of contents navigation is correct (if >100 lines)
- Code blocks specify the language
- Links are valid
- License is clear
Chinese-English bilingual check
- 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 the Chinese
- The English part has its own Table of Contents
- Number of English TOC entries matches the Chinese table of contents
Optional section checks
- Acknowledgements section has been asked about with the user(yes/no)
- Contribution guidelines have been asked about (needed/not needed)
- Changelog has been asked about (needed/not needed)
Badge check (new)
- Badge area after the project description
- Use a 3-line layout(core information + platform + license)
- Use HTML comments for line breaks（
<!-- Badge Row X: ... -->） - Version Badge is generated(0.0.1 when there is no version number)
- Platform Badge is correct(default macOS+Windows+Linux, or as specified by the user)
- License Badge is correct(based on the actual License or default MIT)
- Every Badge has a link
- Colors conform to the standard(use standard shields.io colors)
Code block checks
- Code blocks use ``` markers (no ~~~)
- No extra ```
Prohibited items
- ❌ Do not automatically generate the acknowledgements section(must ask first)
- ❌ Do not omit content from the English version
- ❌ Do not use Chinese anchors to generate the English table of contents
- ❌ The English part must not lack a Table of Contents
- ❌ English TOC entries must not be inconsistent with the Chinese
- ❌ Do not use ~~~ to mark code blocks
- ❌ Do not generate extra ```
- ❌ Badges must not lack Version(must use 0.0.1 when there is no version number)
- ❌ Platform Badge must not be wrong(must be macOS+Windows+Linux when the user has not specified)
- ❌ 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 generating:
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-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