tomevault-io Write Skill README
与 bensz-collect-bugs 的协作约定
- 因本 skill 设计缺陷导致的 bug，先用
bensz-collect-bugs规范记录到~/.bensz-skills/bugs/，不要直接修改用户本地已安装的 skill 源码；若有 workaround，先记 bug，再继续完成任务。 - 只有用户明确要求“report bensz skills bugs”等公开上报时，才用本地
gh上传新增 bug 到huangwb8/bensz-bugs；不要 pull / clone 整个仓库。
为 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 章节要短、直观、可复制。优先给用户一个“最小可用”的通用格式，让用户一眼就知道：用哪个 skill、输入是什么、会产出什么。
包含内容（推荐最小集合）：
- 常规 Prompt（最小可用）（1 个）— 必须用统一格式说明“用哪个 skill / 输入 / 输出”
- 进阶 Prompt（可选）（1 个）— 在常规 Prompt 基础上追加“参数约束”，不展开长篇叙述
常规 Prompt 模板（写进 README，作为“最推荐用法”）：
请使用 {skill_name} skill {完成xxx任务}
输入：{输入是什么（文件/路径/URL/文字/文件夹等）}
输出：{输出是什么（文件/路径/格式/数量等）}
进阶 Prompt 模板（写进 README，作为“进阶用法/带参数约束”）：
{常规Prompt}
另外，还有下列参数约束：
- 参数1：{说明}
- 参数2：{说明}
3.3 设计理念 / 功能概述
解释：
- 技能的核心价值
- 工作原理（简化版，面向小白）
- 设计哲学（如有）
- 与其他技能的区别/配合使用
3.4 提示词示例 / 使用示例
按场景分类 + 渐进式复杂度组织（但每条示例仍保持短小，避免把 README 写成“参数手册”）：
### 示例 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：默认 1-2 个就够（常规 Prompt + 进阶 Prompt）。只有当技能确实存在多个高频输入源/输出形态时，再补 1-2 个场景化变体：
- 按复杂度递增（最小可用 → 带参数约束）
- 按场景分类（不同输入源、不同输出格式）
- 避免过度细分（不要为每个参数组合都写一个 Prompt）
### Q：什么时候需要"备选用法"章节？
A：仅当技能满足以下条件之一时：
1. 有独立的 `scripts/` 可以直接运行
2. 支持命令行参数调用
3. 有 API 或其他编程接口
如果技能只能通过 Prompt 触发，则不需要此章节。
### Q：如何处理"小白用户看不懂的技术细节"？
A：
1. **移除**：如果对使用者没用，直接删除
2. **简化**：用通俗语言解释，避免专业术语
3. **后置**：放在 FAQ 或"更多文档"章节
4. **引用**：指向 SKILL.md 或 references/
---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/huangwb8) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-12 -->