360 Secure SkillHub
360 安全技能中心

better-readme

面向开源项目 README，按 8 个维度给出 0–100 分审计，按 Library、CLI、App、Skill、Data 五类匹配模板，辅助生成或改进 README，并执行发布前检查；默认英文版，可按需增加其他语言版本。

thomaszhou22
thomaszhou22
热度 48.65
最近更新 2026-08-01 02:12:39
分类：效率依赖：代码执行 / 读写文件应用场景：文案创作 / 模板 / 报告撰写

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add better-readme
Metadata
name
better-readme
version
1.1.0
description
Use when the user asks to create, improve, fix, or audit a README.md file, score their README, document an open source project, or set up new project docs. Provides 8-dimension 0-100 quality scoring, 5-type template matrix (Library, CLI, App, Skill, Data), and pre-publish checklist. Do NOT use for API docs, wikis, inline code comments, or general technical writing.

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:

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 < 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

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)

  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

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

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:

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

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