| name | ost-usage-examples |
| description | Write optional usage_examples.md for an open_supports support package when a library has meaningful post-install workflows. Use after repo summary, install script, and setup Skill are complete. |
| argument-hint | GitHub owner/repo of the target library, e.g. colbymchenry/codegraph |
编写 open_supports 使用示例（usage_examples.md）
When to Use
- workflow 在
skill_for_setup 完成后检测到该库有足够复杂的安装后用法，并且用户同意生成详细用例
- 用户明确要求为某个支持包补充安装后的常见使用说明
- 官方 README 或
.ost-refs/ 提供了多个实际用法场景，需要整理为本地快速入口
本 Skill 是可选阶段。没有 usage_examples.md 不影响支持包核心完成。
Pre-read
执行前读取以下内容，按优先级顺序：
- 目标支持包的
repo_readme_summary.md
- 目标支持包的
skill_for_setup/README.md
- 目标支持包的
skill_for_setup/ost_*_install/SKILL.md
- 目标支持包的
scripts_for_install/install.*
- 目标支持包的
.ost-refs/ 目录（如存在且有内容）
repo_readme_summary.md 中引用的官方 README / 官方文档链接（仅在需要确认用法时读取）
GitHub Source Policy
读取 GitHub 仓库事实、README、目录、release、issue、PR 或文件内容时，优先使用 GitHub connector / GitHub app 的结构化工具；若工具不可见，先通过 tool_search 搜索 GitHub 工具。仍不可用时，再考虑 gh CLI、GitHub 官方 API 或官方文档网站。
curl / raw GitHub URL 只用于官方安装命令本身，或作为明确记录的 fallback。生成使用示例时，不要用 raw README 抓取替代 GitHub connector / 官方文档入口；如必须降级，记录原因。
作为 workflow 阶段子代理返回结果时，必须包含：
sources_used: 来源类别和关键路径摘要fallbacks: 降级原因摘要；没有降级时返回空数组
Clarification / Blocking
如果执行本阶段所需信息无法从 repo_readme_summary.md、安装脚本、setup Skill、.ost-refs/ 或官方文档中可靠判断：
- 不要猜测命令、配置、客户端接入或预期结果
- 向 workflow 返回一个澄清问题
- 标明 blocked 字段：
stage: optional_usage_examplesreasonquestionsuggested_default（如有）
- 等用户回答后再继续本阶段
典型阻塞点：
- 官方文档没有给出某个常见场景的命令或配置
- setup Skill 与官方文档对客户端接入方式描述不一致
- 无法判断示例应覆盖项目级配置还是全局配置
- 无法确认示例命令的预期成功输出
输出文件
写入目标支持包根目录：
usage_examples.md
文件头格式：
# {LibraryName} — 使用示例
> 来源：官方 README / 文档；本文件只保留 open_supports 使用者最常见的入口。
文档结构
按以下顺序编写：
| # | 部分标题 | 内容定位 |
|---|
| 1 | 快速开始 | 安装完成后的第一条可执行路径，不重复安装步骤 |
| 2 | 常见场景 | 2~5 个高频任务，每个任务可独立阅读 |
| 3 | 与 Agent 客户端配合 | Claude Code、Codex、MCP、IDE 等接入或日常使用方式；无相关内容则删除本节 |
| 4 | 验证与排错 | 最小验证命令、常见失败现象、可执行处理方式 |
| 5 | 延伸阅读 | 官方文档中更完整的教程或高级配置链接 |
示例条目格式
每个示例尽量使用以下结构：
### {场景名称}
适用场景：{什么时候使用}
```sh
{命令或最小配置}
```
预期结果：{成功后应看到什么}
注意事项：{只写会影响执行的限制；没有则删除本行}
编写原则
- 面向“已经安装完成，现在要开始使用”的用户
- 示例必须能从官方文档、现有支持包文件或
.ost-refs/ 追溯来源
- 优先保留最常见、最短路径的操作
- 注释用于解释命令目的和成功判断，不展开背景教程
- 安装步骤仍以
repo_readme_summary.md 第 2 部分和 scripts_for_install/install.* 为准
- 有副作用的命令必须明确说明影响范围，不能伪装成无风险示例
禁止事项
- 不复制大段官方文档
- 不发明官方没有的命令、flag、配置键或客户端接入方式
- 不重写完整安装流程
- 不把卸载流程写成可执行指导；如官方有卸载文档，只能在延伸阅读或排错中给链接
- 不加入与 open_supports 使用者无关的高级场景
- 不把会修改用户项目、配置、云资源或本地状态的命令写成无副作用示例
Quality Checklist
