| name | skill-readme-writer |
| version | 2.0 |
| description | Use when the user needs to write, improve, or review a README.md for an Agent Skill. Triggers: "write a README for my skill", "improve my skill's README", "review this README", "帮我写 README", "优化 README", "怎么写 skill 的 README", "README 不够好". Covers 8 skill types, each requiring a different README strategy because each answers a different human decision question. NOT for traditional project READMEs (Install/Usage/Contributing) — those are a different format.
|
匾额 | Skill README Writer
Traditional project READMEs don't work for Agent Skills. A Skill README is a sales page — it answers "should I install this?" in 10 seconds. The SKILL.md handles the agent; the README handles the human.
Different skill types need different proof. A PPT generator proves itself with screenshots; a debugger proves itself with Before/After comparison. This skill identifies the type first, then applies the matching strategy.
Workflow
Step 1: Identify type → 🔴 CP1
Ask what the skill does. State your judgment in plain language the user can verify:
"Your skill produces [specific output] — that's Output Type.
The README should lead with screenshots of the output."
→ User confirms: "yes, it produces PPT files" or "no, it's not that"
"Your skill makes [process] faster/better — that's Efficiency Type.
The README needs a Before/After comparison."
→ User confirms: "yes, it saves time" or "no, it adds capability"
Do NOT ask "is this Type 3?" — the user doesn't know the taxonomy. Ask about behavior.
If unclear after 2 questions → default to Type 2 (Efficiency). Its Before/After + trust system is the most transferable baseline.
🔴 CP1 — 类型确认： 展示判断结果和理由，等用户确认后再进入 Step 2。用户纠正类型 → 不要 patch，从 Step 2 重新开始。
Step 2: ONE proof + hero 定位 → 🔴 CP2
Find the matching Type (1-8) below. Each card has a "ONE proof" line — this is the single element that will do 80% of the convincing. Before writing anything, identify what this proof IS for the user's skill.
Then draft the hero positioning (1-2 sentences). This is where agent judgment diverges from user intent most often — the agent defaults to abstract descriptions, but the user knows which capability is the real differentiator.
Hero 定位句规则：
- 必须说清"从什么到什么"，每个动词具体（不是"针对X的Y工具"）
- 最有差异化的能力放在第一个动词位置
- 品牌隐喻放在 quote / section 标题里，不放在定位句里——两者分工明确
- 正例（luban）：「把一个"能用的Skill"，打磨成"能被理解、能被安装、能被传播、能被验证、能持续进化"的公共资产」
- 反例：「针对 JD 交互式定制简历的求职教练」—— 太抽象，任何同类工具都能这么说
🔴 CP2 — ONE proof + hero 确认： 同时展示两项判断，等用户确认：
"ONE proof: [具体是什么]
Hero 定位句: [1-2 句，纯具体动作链]
→ 这两个方向对吗？"
这是最关键的决策点。ONE proof 错了整个 README 方向就错，hero 定位句抽象了用户一定会要求返工。等用户确认后再动笔。
Boundary rule: Types 5-8 are specialized (collection, platform, security, science). If the skill doesn't clearly match, default to Types 1-4.
Step 3: Draft + verify → 🔴 CP3
Write the full README following the type card's mandatory sections + Universal Structure.
After each major section, show a 2-line summary:
Section: Hook + Before/After comparison
Answers: "should I install?" in 10 seconds
→ Does this feel right?
Cross-reference check (mandatory after full draft):
Re-read the target skill's SKILL.md and verify:
- Every claim in README traces to SKILL.md
- Every number (pattern count, step count, percentage) matches SKILL.md
- No section implies capability SKILL.md doesn't implement
- Conversation examples show behavior consistent with SKILL.md instructions
If a claim can't be traced back, remove it or flag it. Don't round up, don't extrapolate. Agent 在总结时天然倾向"圆"出更完整的能力——这个检查就是拦这个的。
🔴 CP3 — 全稿确认： Cross-reference check 通过后，展示完整 README 给用户审阅。用户可能要求调整任何部分——如果涉及类型或 ONE proof 变更，回退到 CP1/CP2 而不是 patch。
8 Iron Laws
All types, no exceptions.
| # | Law | How to check | Fail signal |
|---|
| 1 | First screen answers "should I install?" | Hook + proof + install visible without scrolling | Feature list with no proof; install below the fold |
| 2 | Install command in first scroll range | Copy-pasteable npx skills add or equivalent | Reader must scroll to find install |
| 3 | Conversation example > code example | At least 1 User: / Agent: dialogue | from skill import X; result = run() |
| 4 | Proof format matches type | See type card below | Screenshots for efficiency skill; text for output skill |
| 5 | Honesty > hype | Specific limitations section exists | "Best tool ever" with no caveats |
| 6 | Attack target named | Specific problem or competitor called out by name | "Better than traditional approaches" |
| 7 | Social proof layered | Badges + at least one deeper signal | Badges only, or no proof at all |
| 8 | Emotional connection present | Origin story, personal pain, or relatable frustration | Pure feature list with no human voice |
Law 3 format reference:
User: "审一下这份 JD — 腾讯微信事业群高级产品经理"
Agent: "JD 解析完成。量化追问第 1 轮..."
NOT: from skill import analyze_jd; result = analyze_jd("job.pdf")
Law 7 deeper signals (beyond badges): usage data, real testimonials with links, third-party validation, methodology transparency. When too new for usage data, the creator's research process IS the social proof.
Law 8 elements: "I built this because [pain]. The existing options [gap]." Even 2 sentences of origin story beat 10 feature bullets.
Universal Structure (all types)
Every README starts with the hero block from templates/hero.md, then follows the type-specific template（每个 Type card 的 Template 行指向对应模板）。
Hero block encodes the universal layer all types share:
- Hero block — centered title + optional brand quote + badge row + hero positioning sentence
- Badge row — version, license, Agent Skills, skills.sh, runtime compatibility. Add stars badge once repo has traction
- Hero positioning — 1-2 sentences following the rules in Step 2 (specific action chain, most differentiating capability first)
Fill in template placeholders, delete sections that don't apply.
Visual Toolkit（视觉素材制作）
人是视觉动物。截图 > 描述，GIF > 说明书，信息图 > 表格文字。README 里每个"放截图"的位置都应该真的有截图。
详细制作指南见 references/visual-toolkit.md，核心工具链：
| 场景 | 推荐 Skill | 产出 |
|---|
| 产品截图/对比信息图/流程 GIF | huashu-design | HTML→截图/GIF/MP4 |
| 流程图/架构图 | excalidraw-diagram | .excalidraw + PNG |
| 数据图表 | show_widget（内置） | SVG 内联 |
| 品牌海报/头图 | canvas-design | PNG/PDF |
工作流： 先用模板写完文字 → 标记 <!-- TODO: 视觉素材 --> → 调用对应 skill 批量制作 → 替换占位符。
没有设计 skill 时的后备：Mermaid 代码块（GitHub 原生渲染）、对话示例代码块、shield.io 徽章。
5 Writing Principles (from 35-sample research + baogong experiment)
Iron Laws say WHAT must be in the README. These principles say HOW to write it. They emerged from analyzing why the highest-performing READMEs in the dataset outperform — and are more important than any individual section checklist.
Principle 1: Find the ONE dominant proof.
Every high-star README has one thing that does 80% of the convincing:
- guizang = the full-width screenshots
- humanizer = the 33-pattern checklist
- colleague = "You AI guys are traitors to the codebase"
- karpathy = the 4 rules themselves
- academic-research = the 4-skill pipeline diagram
No one succeeds with "10 features, equally weighted." Readers don't read READMEs — they scan. They hit one proof strong enough to decide, or they leave.
Your first job in Step 2 is to identify this ONE proof for the user's skill. Every type card below has a "Proof format" line — that's where the ONE proof lives. Everything else is supporting structure.
Principle 2: Proof must touch every claim.
Strong READMEs: claim → proof (within 3 lines) → claim → proof → claim → proof
Weak READMEs: claim → claim → claim → ... → proof section (reader already gone)
Every assertion needs evidence within 3 lines. Not "we'll prove it later" — proof and claim travel as a unit. A Limitations section the reader never scrolls to is the same as no Limitations section.
Principle 3: Name what you're killing.
Every individual skill that broke 1K stars has a named attack target:
- luban → "直接让 Agent 改"
- paoding → "看完 50 条笔记还是说不清为什么爆"
- colleague → "traitors to the codebase"
"Better than existing tools" = invisible. Naming the specific pain/competitor/bad-practice creates instant "I have that problem!" recognition.
This is the single highest-ROI sentence in any Skill README. It belongs in the first 3 lines, not buried in a comparison table.
Principle 4: Brand metaphor runs through, not just the hook.
High-star Chinese skills share one pattern: the cultural metaphor doesn't stop at the hook — it runs through section names, process descriptions, and terminology choices:
- cailun（蔡伦）→ "造纸三律" + 7 种纸命名贯穿全文
- baogong（包公）→ "堂审四幕"（调卷宗/当堂陈词/案卷归档/应对回话）+ 铡刀门
- paoding（庖丁）→ 解牛隐喻贯穿分析流程
The metaphor is not decoration — it's a memory anchor. Readers remember "堂审四幕" long after they forget "4-Phase Pipeline." When a skill has a natural metaphor, weave it into section headings and key terms. When it doesn't, don't force one — a clean technical README (karpathy style) beats a bad metaphor.
Principle 5: 有产出就贴实物。
跨类型规则：只要 skill 产出实物（简历、PPT、报告、代码、图表），README 里必须贴产出物的截图或样例，不管它的主类型是什么。Type 1 天然做到（效果展示节），但 Type 2/3/7/8 也经常有实物产出——用 bullet 列表说"交付 X、Y、Z"远不如贴一张截图。
- guizang（Type 1）：直接贴 PPT 效果截图，一目了然
- baogong（Type 2）：核心卖点是流程，但读者也想看最终简历长什么样
- code-review（Type 3）：展示一次真实 review 的截图比列能力清单更直观
判断方式： 如果 skill 的 SKILL.md 里有"交付/输出/产出"类的描述，README 就必须展示实物。文字描述是菜单，截图是上菜。
Type 1: 作品产出型 (Output)
Decision question: "What does this produce? Show me."
ONE proof: A real output screenshot or demo that takes 40-60% of first screen. Reader decides by seeing, not reading.
Proof format: Full-width screenshots, GIFs, or rendered conversation output.
Template: templates/type-1-output.md
Anti-patterns: describing output in text instead of showing it · tiny thumbnails · install after philosophy
Benchmarks: guizang-ppt-skill (screenshot-first layout, dual visual system), nuwa-skill (storytelling + star history, multi-language), cailun-skill (6 real screenshots + naming ritual)
Verify (first-time reader, 15 seconds):
Type 2: 提效/流程型 (Efficiency)
Decision question: "How much better/faster is this than what I do now?"
ONE proof: A Before/After comparison that makes the improvement undeniable in one glance.
Proof format: Side-by-side table (preferred), diff, numbers table, or competitor comparison.
Template: templates/type-2-efficiency.md
Anti-patterns: "80% better" without showing what that means · B/A that looks like rephrasing · no quantitative evidence · trust system missing
Benchmarks: luban-skill (numbers + competitor comparison table + demo GIF), paoding-skill (pain point scenarios + symmetric phrasing + zero API), karpathy-skills (176K⭐ extreme minimalism: 4 rules, no B/A, pure problem→solution — proves clarity alone can win at scale)
Verify (first-time reader, 15 seconds):
Type 3: 能力增强型 (Capability)
Decision question: "What can my agent do now that it couldn't before?"
ONE proof: The categorized pattern/capability checklist. The list IS the pitch — readers scan it and self-assess.
Proof format: Categorized pattern/capability list + before/after capability demo.
Template: templates/type-3-capability.md
Anti-patterns: abstract descriptions without demos · missing pattern checklist · no verification method
Benchmarks: humanizer (33 patterns in 5 categories + per-pattern B/A), code-review-skill (1K⭐, four-phase flowchart + severity color coding, bilingual), addyosmani/agent-skills (lifecycle organization + rationalization tables)
Verify (first-time reader, 15 seconds):
Type 4: 风格/视角型 (Style)
Decision question: "What does it sound like? Let me feel the difference."
ONE proof: Side-by-side text comparison — same prompt, generic vs styled output. The reader FEELS the difference. If this doesn't land, nothing else will.
Proof format: Same prompt → generic output vs styled output, side by side.
Template: templates/type-4-style.md
Anti-patterns: describing style in adjectives without showing it · toy examples · no methodology
Benchmarks: nuwa-skill (multi-perspective dialogue: Naval, Musk, Jobs), colleague-skill (19.4K⭐, emotional hook + multi-source distillation)
Verify (first-time reader, 15 seconds):
Type 5: 合集/目录型 (Collection)
Decision question: "What skills are available? Help me browse and choose."
ONE proof: The categorized listing itself — scan speed IS the product quality. 10 秒内找到相关 skill 就成功。
Proof format: Categorized tables with functional one-line descriptions.
Template: templates/type-5-collection.md
For skill COLLECTIONS and awesome-lists, not individual skills.
Anti-patterns: alphabetical without categories · entries without descriptions · no quality standards
Benchmarks: awesome-cursorrules (40K⭐, 13-category index), alirezarezvani/claude-skills (18.2K⭐, cross-platform compatibility matrix), travisvn/awesome-claude-skills (13.5K⭐, "Skills vs Other Approaches" comparison)
Verify (first-time reader, 15 seconds):
Type 6: 平台/工具型 (Platform)
Decision question: "How do I manage/install/organize skills?"
ONE proof: The one-command quickstart. Copy-paste 能跑 = 信任建立完成。
Proof format: Copy-pasteable commands + compatibility matrix.
Template: templates/type-6-platform.md
For CLI tools, package managers, and platforms that handle skills.
Anti-patterns: architecture diagrams before commands · "revolutionary platform" language · buried compatibility
Benchmarks: vercel-labs/skills (npx quickstart + progressive disclosure), daymade/claude-code-skills (1.2K⭐, marketplace-as-README: per-skill GIF demo cards)
Verify (first-time reader, 15 seconds):
Type 7: 安全/专业领域型 (Security)
Decision question: "Can I trust this in my critical workflow?"
ONE proof: The trophy case — real findings, real bugs caught. "I have detected X, here's the CVE" vs "I claim to detect X." Precision IS the marketing.
Proof format: Trophy case (real findings) + verb-driven capability list + standards coverage.
Template: templates/type-7-security.md
Anti-patterns: casual tone or emoji · "trust me" without results · vague "helps with security" · no scope definition
Benchmarks: trailofbits/skills (trophy case + verb-driven, 10 domains), code-audit (750⭐, anti-hallucination methodology + 55+ vuln types), claude-code-owasp (234⭐, OWASP Top 10:2025 + ASVS 5.0 standards matrix)
Verify (first-time reader, 15 seconds):
Type 8: 科学/研究型 (Science)
Decision question: "What complex workflows does this unlock for my research?"
ONE proof: A complete end-to-end workflow example — research question to final output. Researchers evaluate by "can this do MY pipeline?"
Proof format: Domain matrix + end-to-end pipeline examples + institutional/usage proof.
Template: templates/type-8-science.md
Anti-patterns: features without workflows · "AI-powered" hype · missing expectation management · no domain categorization
Benchmarks: academic-research-skills (31.7K⭐, 4-skill pipeline + human-in-the-loop + anti-hallucination gates), Stanford REAP (1.9K⭐, institutional backing + "verify yourself in 2 minutes"), K-Dense-AI (17 domains + "160,000+ scientists")
Verify (first-time reader, 15 seconds):
Quick Reference
| Section | Output | Efficiency | Capability | Style | Collection | Platform | Security | Science |
|---|
| Hook | Story/grab | Pain point | Gap statement | Style anchor | Criteria | One-command | Domain precision | Domain matrix |
| Proof | Screenshots | Before/After | Pattern list | 3 comparisons | Categorized list | Install methods | Trophy case | Workflows |
| Install | After proof | After B/A | + activation | + triggers | Ecosystem guide | IS the hook | + scope | + domain |
| Trust | Limitations | Safeguards | Verification | Boundaries | Quality standards | Compatibility | Standards | Expectation mgmt |
| Social proof | Demo count | Savings numbers | Pattern count | User count | Entry count | Install count | Audit cases | Scientist count |
| Emotional hook | Creator story | Pain resonance | "I kept seeing" | "I want to sound like" | Curation philosophy | "Tired of switching" | "I got burned" | Research motivation |
Entry Modes
Workflow assumes "write from scratch," but users also arrive with existing READMEs or incomplete inputs. Detect entry mode before Step 1:
Mode W (Write): No existing README, or user explicitly says "帮我写 README." → Standard workflow (Step 1 → 2 → 3).
Mode R (Review/Improve): User says "优化 README" / "review this README" / provides existing README.
- Read existing README + SKILL.md
- Score against Iron Laws (8-item checklist, pass/fail each)
- Identify type from existing README structure (skip CP1 if obvious)
- 🔴 CP-R: Present diagnosis — which laws fail, which type card sections are missing/weak, hero positioning quality. Ask user: "全部重写 or 定向修改?"
- Full rewrite → enter Step 1 as normal. Targeted fix → edit specific sections, run cross-reference check, → CP3
Mode S (No SKILL.md): User provides only a repo URL or existing README, no SKILL.md available.
- Read all available context (README, repo structure, code comments, package.json description)
- Infer skill capabilities from what's available — but mark all inferences as
[推断]
- 🔴 CP-S: Present inferred capabilities, ask user to confirm/correct before writing
- Proceed to Step 1 with confirmed capabilities as source of truth (replacing SKILL.md)
- Cross-reference check (Step 3) runs against user-confirmed capabilities instead of SKILL.md
Failure Modes
Can't determine type in 2 questions → Default to Type 2 (Efficiency). Its B/A + trust system is the most transferable. Note "type uncertain" for future improvement.
Skill doesn't match any type → Use Type 2 baseline, skip verification checklist, ask user for a README they admire.
Multi-type conflict → A skill can look like two types (e.g., baogong produces resumes = Type 1, but core value is the process = Type 2). Resolution: ask "What question does the reader ask FIRST — 'what does it produce?' or 'how is it better than what I do now?'" The answer picks the primary type. The secondary type's proof can appear as a supporting section but doesn't drive the README structure.
User corrects type mid-draft → Stop. Ask user to describe the skill in their own words. Restart from Step 2. Do NOT patch — rewrite is faster.
Any failure after 2 rounds → Conservative README: hook + install + 1 example + 1 limitation. Append <!-- WARNING: Fallback mode. Type not determined. -->.
Common Mistakes
- Wrong type strategy — screenshots for efficiency, text for output. Identify type FIRST.
- README = shorter SKILL.md — SKILL.md tells agent HOW. README tells human WHY. Different audience.
- Install buried — past 3 paragraphs = bounced. First scroll range, always.
- No limitations — stating limits builds trust. Hiding them destroys it.
- Generic claims — "better/faster" is invisible. "从~2天→实时告警" beats "提升效率" every time.
References
35-sample research dataset with per-sample analysis: references/research-data.md.
