---

name: skill-readme-optimizer description: > 优化 Agent Skill 类型 GitHub 仓库的 README.md。根据 agentskills.io 规范和最佳实践， 生成结构清晰、信息完整、双语友好的 README，帮助 skill 被更多用户发现和使用。 当用户提到优化 README、写 skill 的 README、改进 skill 仓库文档、 skill repo documentation、README optimization 时使用此技能。 metadata: author: Ficere version: '1.0' language: zh-CN / en

Skill README 优化器

为 Agent Skill 类型的 GitHub 仓库生成高质量的 README.md。

When to Use This Skill

当用户要求以下任务时使用：

• 为一个 Agent Skill 仓库撰写或优化 README
• 改进已有 skill README 的结构、内容或可读性
• 将一个普通的 skill 文档升级为高质量的开源项目文档
• 检查 skill README 是否符合最佳实践

Instructions

第一步：扫描项目

在编写 README 之前，先收集项目信息：

1. 读取 SKILL.md frontmatter —— 提取 name、description、license、compatibility、metadata
2. 检查目录结构 —— 是否有 scripts/、references/、assets/、LICENSE 等
3. 读取 SKILL.md body —— 理解技能做什么、何时触发、核心工作流
4. 如果有 scripts/ —— 了解是否可独立运行、依赖什么、输入输出格式
5. 如果有 package.json 或 pyproject.toml —— 提取依赖信息
6. 检查 git remote —— 提取 owner/repo 用于安装命令和 badge

将收集到的信息整理为结构化笔记，再进入写作。

第二步：确定语言策略

根据项目情况选择语言策略：

| 场景 | 策略 | |------|------| | SKILL.md 为中文 | 主体中文，关键术语附英文，节标题双语 | | SKILL.md 为英文 | 主体英文 | | 用户明确要求 | 按用户要求 | | 面向国际受众 | 英文为主，或中英双语 |

节标题双语格式示例：## 安装 / Install

第三步：按模板结构撰写

阅读 references/readme-structure.md 获取完整的 README 结构规范。

核心结构（按顺序）：

1. 标题区 —— emoji + 名称（中英），一句话描述，副标题说明适用范围
2. 生态位说明 —— 遵循 Agent Skills 开放标准，列出兼容平台
3. 安装 —— npx skills add owner/repo 一行安装，折叠区放替代方式
4. 使用 —— 自然语言示例（3-5个），展示真实触发场景
5. 功能表 —— 表格形式，一眼看清能力边界
6. 详细说明 —— 折叠区放评分细则、输入格式等深度内容
7. 独立脚本（如有）—— 脱离 Agent 平台的用法
8. 目录结构 —— tree 格式 + 注释
9. 免责声明（如需）—— 适用于医疗、法律、金融、命理等敏感领域
10. License

第四步：应用写作原则

阅读 references/writing-principles.md 获取详细的写作原则。

关键原则：

• 一眼可装：安装命令在首屏可见，不超过一行
• 三秒明意：标题区读完就知道这个 skill 做什么
• 自然语言优先：使用示例展示真实对话，而非 API 调用
• 渐进式披露：核心信息直接展示，细节用 <details> 折叠
• 信息密度高：不写废话，每一行都有信息增量
• badge 克制：只加真实有意义的 badge（license、兼容平台等），不堆砌装饰性 badge

第五步：自查清单

完成后对照检查：

• [ ] 安装命令正确且在首屏可见
• [ ] owner/repo 与实际 git remote 一致
• [ ] 使用示例是真实可运行的自然语言
• [ ] 功能表覆盖了 SKILL.md 中的所有核心能力
• [ ] 目录结构与实际文件一致
• [ ] 折叠区内容格式正确（<details> 标签）
• [ ] 无占位符文本残留（如 {{PLACEHOLDER}}）
• [ ] License 与 SKILL.md 或 LICENSE 文件一致
• [ ] 中英文之间有空格（如：Agent Skill 技能）
• [ ] 敏感领域有免责声明

Examples

输入

用户提供一个 skill 仓库路径或链接，要求优化 README。

输出

一份结构完整、信息准确、双语友好的 README.md 文件。 参考 assets/example-readme.md 查看完整示例。