findscripter 何时使用
适用：
- 编写或更新 OpenAPI 3.1 / AsyncAPI 规范（REST、事件驱动、实时 API）。
- 搭建开发者门户、SDK 文档或新手上手流程。
- 提升既有 API 文档的质量、准确性与可发现性。
- 从 API 规范生成多语言代码示例或 SDK。
不该用（负边界）：
- 只需一段内部速记或非正式摘要。
- 任务是纯后端实现，不涉及对外文档。
- 没有任何 API 面或规范可供描述。
步骤
- 明确目标读者、API 范围与文档目标（先确认开发者画像与「首次成功时间」诉求）。
- 编写或校验规范：补全请求/响应示例、错误码、鉴权流程，并按 schema 做校验。
- 构建交互式文档（Swagger UI / Redoc / Stoplight），并用契约测试保证示例可运行、与实现一致。
- 规划维护：版本策略、破坏性变更迁移指南、弃用时间线与 changelog 自动化。
指令
- 规范优先采用 OpenAPI 3.1（完整 JSON Schema 支持）；事件驱动 API 用 AsyncAPI，GraphQL 用 SDL。
- 每个端点必须含可工作的示例（含 curl）、典型错误响应与鉴权方式；安全方案（OAuth 2.0 / OpenID Connect / API Key / JWT）给出可运行示例与刷新机制。
- 遵循 docs-as-code：文档纳入 Git，接入 CI/CD 自动校验、自动部署。
- 示例与代码片段须自动化测试（response 对照 schema 校验、curl 可执行），避免文档与实现漂移。
- Webhook 文档须含 payload 示例与签名验证/安全说明。
- 重实用、可运行示例，轻理论描述；渐进式披露，兼顾完整性与简洁。
示例
- 「为这个 REST API 编写完整的 OpenAPI 3.1 规范，含鉴权示例。」
- 「从这份 OpenAPI 规范生成 Python、JavaScript、Go 三种 SDK。」
- 「为 v1 升级到 v2 的开发者设计迁移指南。」
- 「编写带安全最佳实践与 payload 示例的 Webhook 文档。」
- 「为所有 API 文档中的代码示例搭建自动化测试。」
注意事项
- 不要把产出当作环境特定校验、测试或专家评审的替代品；规范落地前需在真实环境验证。
- 缺少必要输入（如目标读者、API 范围、鉴权方式、成功标准）或权限边界不明时，先停下来澄清。
- 仅在任务明确落入上述范围时使用本技能。
- 把文档当作产品：建立反馈闭环、持续迭代，关注可发现性（SEO/搜索）与可访问性。
互见
- 技术写作 / 文档风格规范类技能（文书 domain）。
- API 设计与契约驱动开发相关技能。
- CI/CD 与 docs-as-code 自动化部署相关技能。
采编自 sickn33/antigravity-awesome-skills（MIT）。