majiayu000 Write Skill README
为 Agent Skills 编写符合最佳实践的 README.md 用户使用指南。
触发条件
用户要求为技能生成/编写/更新 README.md、用户使用指南、技能文档时使用本技能。
核心工作流
⚠️ 安全限制：本技能仅用于生成/更新 README.md 文件，永远不能修改目标技能的任何现有内容（包括但不限于 SKILL.md、SKILL.yaml、config.yaml、scripts/、references/ 等）。只能读取这些文件作为分析输入，不能对它们执行任何写入或编辑操作。
步骤 1：分析技能结构
读取并分析以下文件：
- SKILL.yaml — 技能元数据（name、description、version、author、metadata）
- SKILL.md — 技能核心规范（触发条件、工作流、输入输出）
- config.yaml（可选）— 可配置参数
- scripts/ 目录（可选）— 硬编码用法
- references/ 目录（可选）— 参考文档
步骤 2：确定 README 类型
根据技能特性选择模板：
| 技能类型 | 特征 | 推荐模板 |
|---|---|---|
| 功能型 | 主要通过 Prompt 触发，有明确工作流 | 模板 A：systematic-literature-review 风格 |
| 工具型 | 主要通过脚本/命令行调用 | 模板 B：install-bensz-skills 风格 |
| 混合型 | Prompt 优先 + 脚本备选 | 模板 C：make_latex_model 风格 |
步骤 3：生成核心章节
按以下顺序生成 README.md 内容：
3.1 标题与受众声明
# {技能名称} — 用户使用指南
本 README 面向**使用者**：如何触发并正确使用 `{技能名称}` skill。
执行指令与硬性规范在 `SKILL.md`；默认参数在 `config.yaml`。
3.2 快速开始（核心章节）
原则：将"最推荐/最简单/作者最喜欢"的 Prompt 放在最前面。
包含内容：
- 经典 Prompt（1-2 个）— 最常用、最简单的用法
- 场景化变异 Prompt（2-4 个）— 针对不同场景优化的变体
- 每个 Prompt 用子标题标注场景（如 "- 最推荐"、"- 结合 XXX 流程"）
3.3 设计理念 / 功能概述
解释：
- 技能的核心价值
- 工作原理（简化版，面向小白）
- 设计哲学（如有）
- 与其他技能的区别/配合使用
3.4 提示词示例 / 使用示例
按场景分类 + 渐进式复杂度组织：
### 示例 1：[场景描述]（最简单）
Prompt
### 示例 2：[场景描述]
Prompt
3.5 输出文件 / 配置选项
列出技能生成的文件或可配置参数，用表格或列表呈现。
3.6 备选用法（如有硬编码）
仅当技能有脚本调用方式时添加此章节：
## 备选用法（脚本/硬编码流程）
### 步骤 1：[做什么]
```bash
command
#### 3.7 常见问题（FAQ）
预测小白用户可能遇到的问题，用 Q&A 形式解答。
### 步骤 4：应用风格规范
遵循以下风格规范：
#### 4.1 小白友好设计
- 使用**表格**呈现决策指南（如"你的需求 → 推荐档位 → 理由"）
- 提供**丰富别名**（如"旗舰级、顶刊级、高级"）
- 使用**对话式呈现**（"你：... / 技能：..."）
- 代码块添加**行内注释**（注释在命令前）
#### 4.2 硬编码用法处理
- **Prompt 调用**标记为"推荐用法"
- **脚本调用**标记为"备选用法"
- 硬编码用法放在 README **最后**
#### 4.3 语言风格
- 使用**第二人称**（"你"）
- **有选择地使用 emoji**（特性列表 ✨、状态标记 ✅、章节标题 📖）
- 技术术语用**代码高亮**（`` `SKILL.md` ``、`` `/path/to/file` ``）
### 步骤 5：输出 README.md
将生成的内容写入技能目录下的 `README.md`。
## 输出文件
- `README.md` — 技能的用户使用指南
## 参考文档
- [README 结构模板](references/README-templates.md) — 三种典型模板的详细结构
- [风格规范清单](references/style-guidelines.md) — 完整的风格规范和检查清单
- [Prompt 编写指南](references/prompt-writing-guide.md) — 如何编写经典 Prompt 和变异 Prompt
## 常见问题
### Q：如何确定"经典 Prompt"？
A：经典 Prompt 应该是：
1. **最简单**的可用用法（最小可执行）
2. **最常用**的场景（覆盖 80% 用户需求）
3. **已验证可靠**（在实际使用中测试过）
### Q：变异 Prompt 要写多少个？
A：建议 2-4 个，覆盖主要使用场景：
- 按复杂度递增（最小可用 → 指定参数 → 高级用法）
- 按场景分类（不同输入源、不同输出格式）
- 避免过度细分（不要为每个参数组合都写一个 Prompt）
### Q：什么时候需要"备选用法"章节？
A：仅当技能满足以下条件之一时：
1. 有独立的 `scripts/` 可以直接运行
2. 支持命令行参数调用
3. 有 API 或其他编程接口
如果技能只能通过 Prompt 触发，则不需要此章节。
### Q：如何处理"小白用户看不懂的技术细节"？
A：
1. **移除**：如果对使用者没用，直接删除
2. **简化**：用通俗语言解释，避免专业术语
3. **后置**：放在 FAQ 或"更多文档"章节
4. **引用**：指向 SKILL.md 或 references/