← Back to Skills Marketplace
Better Readme
by
Thomaszhou
· GitHub ↗
· v1.0.0
· MIT-0
19
Downloads
0
Stars
0
Active Installs
1
Versions
Install in OpenClaw
/install better-readme
Description
Use when the user asks to create, improve, or audit a README.md file, or when setting up a new project's documentation. Provides template matrix (Library, CL...
README (SKILL.md)
Better README
Create, audit, and optimize project README files with quality scoring, template matching, and multilingual support.
Activation Triggers
- "write/improve/fix my README"
- "create a README for this project"
- "score/check my README"
- "my README is bad, help"
- Setting up a new open-source project
- Preparing a GitHub launch
Workflow
Phase 1: Classify
Identify the project type by scanning the codebase:
| Signal | Project Type |
|---|---|
package.json with main/exports, no UI |
Library/SDK |
bin/ field, CLI framework (commander, click, clap) |
CLI Tool |
| React/Vue/HTML, deploy target (Vercel/Netlify) | App/Product |
SKILL.md exists, skills/ directory |
Agent Skill |
.csv/.json/.parquet dataset, no src/ |
Data/Resource |
If ambiguous, ask the user.
Phase 2: Score (if README exists)
Run the audit script:
python3 scripts/readme_audit.py --path /path/to/README.md
This produces a 0–100 score across 8 dimensions. See references/scoring-rubric.md for criteria.
If score \x3C 70, recommend a full rewrite using the appropriate template.
Phase 3: Generate
- Load the matching template from
references/templates.md - Scan the project for real data:
- Project name, description from
package.json/pyproject.toml/Cargo.toml - Install command (detect package manager)
- License file
- Key features (scan source for main entry points)
- Badge URLs (CI, coverage, npm/PyPI)
- Project name, description from
- Fill the template with real data
- Generate both
README.md(English) andREADME.zh-CN.md(Chinese) with language toggle - Print a preview for the user to review
Phase 4: Pre-Publish Checklist
Run through references/pre-publish-checklist.md and report:
- ✅ Passed items
- ⚠️ Warnings (nice to have)
- ❌ Missing critical items
Template Selection Guide
| Type | Hero | Focus | Install |
|---|---|---|---|
| Library/SDK | Code snippet | API reference | npm install / pip install |
| CLI Tool | Demo GIF/terminal | Commands table | brew install / cargo install |
| App/Product | Screenshot/hero image | Features + live demo | Deploy button |
| Agent Skill | What it triggers on | Workflow + compatibility | clawhub install |
| Data/Resource | Stats card | Schema + sample data | Direct download |
Quality Standards (Non-Negotiable)
- 30-second rule: User must understand what this does after one scroll
- ≤3 install steps: If setup needs 10 steps, nobody finishes
- Real examples: Not
your-api-key-here— actual working snippets - No dead links: Every link must resolve
- Mobile readable: No wide tables without horizontal scroll handling
Scoring Dimensions
| Dimension | Max Points | Quick Check |
|---|---|---|
| First impression (hero/title/tagline) | 15 | H1 + one-line description in first 5 lines |
| Problem statement | 10 | "Why" section explaining what pain this solves |
| Quick start | 20 | Install + run in ≤3 commands |
| Visual demo | 10 | Screenshot, GIF, or video present |
| Feature clarity | 10 | Feature list or "what it does" section |
| API/Usage docs | 10 | Code examples for main use cases |
| Badges & metadata | 5 | License, version, CI status |
| Community & links | 10 | Contributing guide, link to issues, discussions |
| Pre-publish readiness | 10 | Topics, description, social preview configured |
See references/scoring-rubric.md for full criteria.
Language Support
Always generate bilingual READMEs:
**English** | **[中文](README.zh-CN.md)**
If the user's locale is Chinese, generate Chinese first and link to English.
Audit Script Usage
# Score a single README
python3 scripts/readme_audit.py --path ./README.md
# Score and output JSON
python3 scripts/readme_audit.py --path ./README.md --json
# Recommend a template type based on project structure
python3 scripts/readme_audit.py --detect /path/to/project
Usage Guidance
Before installing or using it, ask the agent to preview a diff and confirm before overwriting README files. Run it only on documentation-relevant project files or a clean working tree, especially if the repository contains secrets, internal notes, or single-language documentation requirements.
Capability Tags
Capability Assessment
Purpose & Capability
The stated behavior of scanning a project and generating or scoring README documentation fits a README improvement skill.
Instruction Scope
The activation examples are broad and the workflow may create both English and Chinese README files, so users should make sure the requested documentation scope matches their intent.
Install Mechanism
No suspicious install mechanism, package execution, dependency install, or hidden setup behavior was evidenced in the supplied telemetry or artifact excerpts.
Credentials
Repository scanning is plausible for generating accurate documentation, but users should avoid running it over repos containing secrets or unrelated private files unless scope is constrained.
Persistence & Privilege
The main privileged action is writing README.md and README.zh-CN.md; this is expected for the purpose, but existing files could be changed or replaced if the agent proceeds without preview.
How to Use
- Make sure OpenClaw is installed (local or Docker)
- Run the install command in chat:
/install better-readme - After installation, invoke the skill by name or use
/better-readme - Provide required inputs per the skill's parameter spec and get structured output
Version History
v1.0.0
Initial release: 9-dimension scoring, 5 templates, project detection, bilingual support
Metadata
Frequently Asked Questions
What is Better Readme?
Use when the user asks to create, improve, or audit a README.md file, or when setting up a new project's documentation. Provides template matrix (Library, CL... It is an AI Agent Skill for Claude Code / OpenClaw, with 19 downloads so far.
How do I install Better Readme?
Run "/install better-readme" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.
Is Better Readme free?
Yes, Better Readme is completely free, licensed under MIT-0. You can download, install and use it at no cost.
Which platforms does Better Readme support?
Better Readme is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).
Who created Better Readme?
It is built and maintained by Thomaszhou (@thomaszhou22); the current version is v1.0.0.
More Skills