---

name: write-skill-readme description: | 技能 README 生成器：基于 SKILL.md、配置、脚本和参考资料生成面向普通用户的 README 使用指南。 输出聚焦快速开始、典型场景、功能概述、输出说明和 FAQ，帮助技能在资源市场中更清晰地展示。 author: "Bensz Conan" license: "MIT" category: "writing" tags: "技能文档, README, 用户指南, 文档生成" source: "https://github.com/huangwb8/skills/tree/main/write-skill-readme" allowed-tools: "glob, read_file, search_file_content, write_file, replace, ask_user_question"

Write Skill README：技能用户指南生成器

适用场景

适用于以下任务：

• 为某个 Skill 生成 README.md
• 编写技能用户指南、使用说明、快速开始文档
• 把技能的 SKILL.md 改写成普通用户能看懂的说明
• 更新已有 README，使其更清晰、更适合资源市场展示

安全边界

默认只生成或更新目标技能目录下的 README.md。

• 可以读取：SKILL.md、配置文件、脚本、参考文档、已有 README
• 不要修改：SKILL.md、配置文件、脚本、参考文档
• 如果用户明确要求修改技能本体，应先说明这已经超出 README 生成范围，再按用户的新要求处理
• 不要把脚本中的危险命令、内部路径、私有令牌或平台绑定说明原样写入 README

输入要求

用户至少提供一个技能目录路径，或明确指出当前工作区中的某个技能。

如果目标不明确，先询问：

1. 要为哪个技能生成 README？
2. README 面向谁：普通用户、开发者、管理员还是市场审核者？
3. 是否要覆盖已有 README？

工作流程

1. 分析技能结构

优先读取以下文件：

文件/目录	用途
SKILL.md	提取技能名称、触发条件、核心流程和输出要求
config.yaml / config.json	提取可配置参数和默认值
scripts/	判断是否存在可选脚本用法，只记录安全、必要的用户用法
references/	提取可面向用户解释的背景资料
README.md	如果已存在，判断是否更新而不是完全重写

读取脚本或参考资料时，只抽取用户需要理解的用法，不复制内部实现细节。

2. 判断 README 类型

类型	特征	文档重点
功能型	主要通过自然语言触发	快速开始、场景示例、输出说明
工具型	主要依赖脚本或命令	前置条件、参数、命令示例、输出文件
混合型	自然语言优先，脚本可选	推荐用法在前，脚本作为备选放后面

3. 生成 README 结构

默认生成以下章节，按技能实际情况裁剪：

# {技能名称} — 用户使用指南

本 README 面向使用者，说明如何触发并正确使用 `{技能名称}`。

## 快速开始

```text
请使用 {skill_name} skill {完成具体任务}
输入：{输入内容或路径}
输出：{输出文件、格式或结果}
```

## 适用场景

| 你的需求 | 推荐用法 |
| --- | --- |
| ... | ... |

## 功能概述

| 能力 | 说明 |
| --- | --- |
| ... | ... |

## 使用示例

### 示例 1：最小可用

```text
...
```

### 示例 2：带参数约束

```text
...
```

## 输出说明

- `{文件名}`：{说明}

## 配置选项

| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| ... | ... | ... |

## 常见问题

### Q：...

A：...

4. 写作要求

• 使用第二人称，避免内部实现视角
• 快速开始必须短、可复制、能覆盖 80% 常见需求
• 示例按“最小可用 → 进阶 → 特殊场景”排列
• 复杂选择用表格表达，不写长篇说教
• 文件、路径、命令、参数使用代码格式
• 不暴露不适用于当前平台的安装路径、外部工具绑定或私有工作流

5. 写入或更新 README

如果目录中没有 README.md，直接写入新文件。

如果已有 README.md：

1. 先读取原文，保留仍然正确的信息
2. 删除过期、平台绑定或误导性内容
3. 用新结构补齐快速开始、示例、输出说明和 FAQ
4. 写入前简要说明覆盖范围

完成前自检

交付前检查：

• README 是否能让第一次使用的人直接上手
• 快速开始是否包含输入和输出
• 是否误写了不存在的工具、平台、安装路径或外部服务
• 是否复制了脚本内部实现细节而不是用户用法
• 链接、相对路径、文件名是否准确
• 若修改了已有 README，是否保留了仍然有效的用户信息