---
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` 查看完整示例。