Better README#

Create, audit, and optimize project README files with 8-dimension quality scoring (0–100), 5-type template matching (Library, CLI, App, Skill, Data), and pre-publish readiness checks.

Key differentiator: The 0–100 audit score evaluates READMEs across 8 dimensions — first impression, problem statement, quick start, visual demo, feature clarity, API docs, badges, and community. Nothing else on ClawHub does this.

Activation Triggers#

• "write/improve/fix my README"
• "create a README for this project"
• "score/check my README"
• "my README is bad"
• "I need a README template"
• "document my open source project"
• Setting up a new open-source project
• Preparing a GitHub launch

Workflow#

Phase 0: Onboarding (first use only)#

When this skill is activated for the first time (no prior onboarding record):

1. Briefly introduce what this skill can do (score, improve, create READMEs)
2. Ask the user: "Want me to evaluate the READMEs of your existing repos?"
3. If yes:
   • Fetch the user's public GitHub repo list
   • Let the user pick which repos to evaluate (or evaluate all)
   • Run Phase 2 (Score) on each selected repo's README
   • Summarize scores and highlight the weakest ones
   • Offer to improve the lowest-scoring READMEs
4. If no, skip ahead to the normal workflow
5. Record that onboarding is complete (do not repeat)

Phase 1: Classify#

Identify the project type by scanning the codebase:

SignalProject Typepackage.json with main/ exports, no UILibrary/SDKbin/ field, CLI framework (commander, click, clap)CLI ToolReact/Vue/HTML, deploy target (Vercel/Netlify)App/ProductSKILL.md exists, skills/ directoryAgent Skill.csv/ .json/ .parquet dataset, no src/Data/Resource

If ambiguous, ask the user.

Phase 2: Score (if README exists)#

Run the audit script:

bash

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 < 70, recommend a full rewrite using the appropriate template.

Phase 3: Generate#

1. Load the matching template from references/templates.md
2. 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)
3. Fill the template with real data
4. Generate README.md in English by default
5. Print a preview for the user to review
6. Ask the user if they need additional language versions (e.g., Chinese)

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#

TypeHeroFocusInstallLibrary/SDKCode snippetAPI referencenpm install / pip installCLI ToolDemo GIF/terminalCommands tablebrew install / cargo installApp/ProductScreenshot/hero imageFeatures + live demoDeploy buttonAgent SkillWhat it triggers onWorkflow + compatibilityclawhub installData/ResourceStats cardSchema + sample dataDirect download

Quality Standards (Non-Negotiable)#

1. 30-second rule: User must understand what this does after one scroll
2. ≤3 install steps: If setup needs 10 steps, nobody finishes
3. Real examples: Not your-api-key-here — actual working snippets
4. No dead links: Every link must resolve
5. Mobile readable: No wide tables without horizontal scroll handling

Scoring Dimensions#

DimensionMax PointsQuick CheckFirst impression (hero/title/tagline)15H1 + one-line description in first 5 linesProblem statement10"Why" section explaining what pain this solvesQuick start20Install + run in ≤3 commandsVisual demo10Screenshot, GIF, or video presentFeature clarity10Feature list or "what it does" sectionAPI/Usage docs10Code examples for main use casesBadges & metadata5License, version, CI statusCommunity & links10Contributing guide, link to issues, discussionsPre-publish readiness10Topics, description, social preview configured

See references/scoring-rubric.md for full criteria.

Language Support#

Default to generating an English-only README.

After generation, ask the user: "Do you need a README in another language (e.g., Chinese, Japanese, etc.)?"

Only generate additional language versions if the user requests it. Keep each language version in a separate file (e.g., README.zh-CN.md) with a language toggle at the top:

markdown

**English** | **[中文](README.zh-CN.md)**

Audit Script Usage#

bash

# 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