核心用法
README Craft 是一个专注于项目文档入口优化的专业写作工具，提供三种工作模式：create（从零创建）、audit（质量审计评分）、rewrite（智能重写优化）。用户通过 /readme-craft 指令触发，系统会自动检测项目状态（有无现有 README）并推荐最优模式，也可通过 --mode 参数强制指定。
该工具深度集成项目扫描能力，能自动解析 package.json、Cargo.toml、pyproject.toml 等配置文件，识别 CLI 工具、库/SDK、Web 应用、框架、插件等 6 种项目类型，并匹配对应的「Golden Structure」黄金结构模板。输出遵循严格的认知漏斗设计原则——从项目名、一句话描述、视觉演示到快速上手，每层信息精准过滤读者，确保 30 秒内完成从"这是什么"到"我要用"的决策转化。
显著优点
1. 实战验证的方法论体系：技能蒸馏自 OMC/ECC 等真实高星项目的 README 实战经验，融合 awesome-readme、Standard README、Art of README 等社区权威标准，非空洞模板堆砌。
2. 科学的量化评估机制：独创 22 项、100 分制审计评分体系，6 大维度（Hook/Onboarding/Content/Trust/Structure/Polish）加权计算，输出 S/A/B/C/D 等级和可执行的 TOP3 改进建议，告别主观"感觉还行"。
3. 类型感知的智能适配：针对不同项目类型自动调整结构重点——CLI 工具强调终端 GIF 和命令表格，框架项目突出架构图和概念解释，库/SDK 聚焦代码示例和 API 概览，避免一刀切。
4. 去 AI 味的写作指导：明确反对"模糊描述""只说不做"等 15 个常见反模式，强制要求每个功能配备代码示例，用 Show Don't Tell 原则替代模板化空话。
潜在缺点与局限性
1. 纯文档类 Skill 的功能边界：该 Skill 本质是基于提示词工程的文档生成助手，依赖底层 Agent 的代码分析和写作能力，本身不包含静态代码分析引擎。对于超大型 Monorepo 的复杂依赖关系，自动扫描可能不够深入，需要人工补充。
2. 中文本地化程度有限：虽然支持触发词"写 readme"，但核心方法论和评估体系源自英文开源社区标准，生成的 README 默认英文为主，双语版本（README_CN.md）需额外指定，中文表达的自然度依赖底层模型能力。
3. 视觉资产需外部工具配合：推荐的 Hero Visual（终端 GIF、架构图等）需要 vhs、asciinema、Mermaid 等外部工具生成，Skill 本身不直接生成这些资产，仅提供格式指导和占位符。
4. 不适用场景的判断依赖用户：虽然文档明确列出 API 文档、CHANGELOG、CLAUDE.md 等不适用场景，但实际使用中仍需用户自行判断，Skill 无法自动拦截误用。
适合的目标群体
- 开源项目维护者：希望提升 GitHub Star 转化率和 contributor 参与度的个人或团队
- 内部工具开发者：需要让新团队成员快速上手的内部项目文档负责人
- 技术产品经理：追求专业开发者体验（DX）的 B 端产品团队
- 技术写作爱好者：希望系统学习 README 最佳实践、建立评估标准的文档工程师
- AI 辅助编程用户：习惯用 Claude 等工具辅助开发，希望一键生成高质量项目入口文档
使用风险
性能风险：对于代码量极大的项目（数万文件），自动扫描 package.json/Cargo.toml 及源码提取信息的过程可能耗时较长，建议在 .gitignore 规范的清洁仓库中使用。
依赖风险：生成的 README 包含 shields.io 徽章图片 URL，若用户未替换占位符直接提交，可能导致无效链接；Quick Start 中的安装命令依赖实际发布的包版本，需确保 README 与发布流程同步。
同步风险：README Craft 强调"过时的 README 比没有更糟"，但工具本身不提供持续同步机制。建议建立代码变更时的 README 审查 checklist，或结合 git hooks 提醒更新。
模型一致性风险：rewrite 模式的 diff 预览依赖底层 Agent 的编辑能力，复杂重写场景可能出现格式错乱，建议生成后人工校验 Markdown 渲染效果。